solid2-agent-kit 0.15.0 → 0.17.0

package/README.md

@@ -16,11 +16,11 @@ 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`), two-phase effects whose apply only writes a local signal (use a writable derivation), core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction), and `setStore(async ...)` on a `createStore` / `createOptimisticStore` setter (the draft is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]`) |
+| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[paths...]` — files are checked, directories are walked, a missing path fails): 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 (valueless `use:x` included), Solid 1.x `createEffect(fn)` / `createEffect(fn, init)` / `createMemo(fn, init)` signatures, `const [x] = createProjection(...)` (it returns the store, not a tuple), `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props (except on `@solidjs/meta` tags), `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 — import `JSX` from `@solidjs/web`, or use an aliased `Element` from `solid-js`), two-phase effects whose apply only writes a local signal (use a writable derivation), core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction), and `setStore(async ...)` on a `createStore` / `createOptimisticStore` setter (the draft is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]`) |
 | 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 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) |
+| 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` / `@solidjs/testing-library` / `@tanstack/solid-router` / `@tanstack/solid-query` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router's and Query's on `rc`), `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
@@ -40,10 +40,15 @@ npx github:lightsound/solid2-agent-kit init
 npx github:lightsound/solid2-agent-kit init --cursor
 npx github:lightsound/solid2-agent-kit init --claude
 
-# run the mechanical pattern gate (default source dir: src; or name files)
+# run the mechanical pattern gate (default source dir: src; or name files and directories)
 npx github:lightsound/solid2-agent-kit check
 npx github:lightsound/solid2-agent-kit check --dir app
-npx github:lightsound/solid2-agent-kit check src/App.tsx
+npx github:lightsound/solid2-agent-kit check src/App.tsx src/routes
+
+# only the files a change touched: a missing path always fails (exit 2), so
+# --diff-filter=d keeps deleted files out of the list; -z / -0 keep paths with
+# spaces whole, -r skips the run on an empty (or delete-only) diff
+git diff --name-only -z --diff-filter=d main | xargs -0 -r npx github:lightsound/solid2-agent-kit check
 
 # check the project wiring (deps, tsconfig, root configs)
 npx github:lightsound/solid2-agent-kit doctor

package/bin/solid2-kit.mjs

@@ -405,10 +405,78 @@ function actionAsyncFindings(content) {
   }));
 }
 
+// Solid 1.x signatures: `createEffect(fn)` (Solid 2 needs compute + apply),
+// `createEffect(fn, initialValue)`, and `createMemo(fn, initialValue[, options])`
+// (Solid 2's second memo argument is the options object). A second argument
+// that is a primitive or array literal is an initial value; functions,
+// identifiers, and object literals are left alone. A name this file imports
+// from another library (effector's one-argument `createEffect`) or declares
+// itself is not Solid's.
+const INITIAL_VALUE_LITERAL = /^(?:-?\d|['"`[]|true\b|false\b|null\b|undefined\b)/;
+const NOT_SOLID_CORE_MODULE = /^(?!(?:solid-js|@solidjs\/signals)$)/;
+
+// Blank type-argument lists (`Record<string, number>`, `Map<K, () => void>`)
+// so their commas do not split arguments. `<` counts only right after an
+// identifier: formatted comparisons have a space before it.
+function blankTypeArguments(text) {
+  let previous;
+  do {
+    previous = text;
+    text = text.replace(/(?<=[\w$])<(?:=>|[^<>=])*>/g, (typeArgs) => ' '.repeat(typeArgs.length));
+  } while (text !== previous);
+  return text;
+}
+
+function solid1SignatureFindings(content) {
+  const foreign = importedNames(content, NOT_SOLID_CORE_MODULE);
+  const matches = [];
+  for (const call of content.matchAll(
+    /(?<![.\w$])create(Effect|Memo)\s*(?:<(?:=>|[^<>]|<(?:=>|[^<>])*>)*>)?\s*\(/g,
+  )) {
+    const name = `create${call[1]}`;
+    if (foreign.has(name)) continue;
+    if (new RegExp(`\\b(?:function\\s*\\*?|const|let|var|class)\\s+${name}\\b`).test(content)) continue;
+    const open = call.index + call[0].length - 1;
+    const close = scanBalanced(content, open);
+    if (close === -1) continue;
+    const args = splitTopLevelArgs(blankTypeArguments(content.slice(open + 1, close)))
+      .map((arg) => arg.trim())
+      .filter(Boolean);
+    const initialValue = args.length >= 2 && INITIAL_VALUE_LITERAL.test(args[1]);
+    const legacy =
+      call[1] === 'Effect' ? args.length === 1 || initialValue : args.length >= 3 || initialValue;
+    if (legacy) matches.push({ index: call.index });
+  }
+  return matches;
+}
+
+// `key` is meaningless in Solid JSX except on the Solid Meta tags, where it
+// names the tag's identity (`<Meta key="og-image" …>`). The enclosing tag is
+// the nearest `<Name` (or `<Namespace.Name`) before the attribute.
+const META_MODULE = /^@solidjs\/meta$/;
+
+function reactKeyPropFindings(content) {
+  const metaTags = importedNames(content, META_MODULE);
+  const metaNamespaces = new Set(
+    [...content.matchAll(/\bimport\s+\*\s+as\s+([\w$]+)\s+from\s*['"]@solidjs\/meta['"]/g)].map((m) => m[1]),
+  );
+  const matches = [];
+  for (const attr of content.matchAll(/\skey=\{/g)) {
+    const opener = [...content.slice(0, attr.index).matchAll(/<([A-Za-z][\w$.]*)/g)].pop();
+    const tag = opener?.[1] ?? '';
+    if (metaTags.has(tag) || metaNamespaces.has(tag.split('.')[0])) continue;
+    matches.push({ index: attr.index });
+  }
+  return matches;
+}
+
 // 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.
+// stray Next or Router 1.x call in the same file is still reported. TanStack
+// Router 1.x (Solid 1) and 2.x (Solid 2) export the same names from the same
+// module, so the major is invisible here; doctor's tanstack-router-version
+// reads it from package.json / node_modules.
 const TANSTACK_ROUTER_MODULE = /^@tanstack\/(?:solid-router|router-core)$/;
 
 // Local names bound by `import [Default,] { a, b as c } from "<module>"`.
@@ -454,7 +522,19 @@ const CHECKS = [
     id: 'jsx-namespace-import',
     pattern: /import\s+(?:type\s+)?\{[^}]*\bJSX\b[^}]*\}\s*from\s+['"]solid-js['"]/g,
     message:
-      'Solid 2 does not export a `JSX` namespace from "solid-js" (TS2305). Children/return types are `Element` from "solid-js"; DOM-specific JSX types (JSX.IntrinsicElements, JSX.CSSProperties) come from "@solidjs/web".',
+      'Solid 2 does not export a `JSX` namespace from "solid-js" (TS2305). Import `JSX` from "@solidjs/web" (JSX.Element, JSX.IntrinsicElements, JSX.CSSProperties), or use `Element` from "solid-js" (aliased, e.g. `type Element as SolidElement`, where the DOM Element is also used).',
+  },
+  {
+    id: 'solid1-effect-memo-signature',
+    find: solid1SignatureFindings,
+    message:
+      'Solid 1.x signature. createEffect takes (compute, apply) — a single argument is an error in Solid 2. createMemo(fn, initialValue) is gone: the second argument is the options object; give the compute a default parameter instead (createMemo((prev = 0) => ...)).',
+  },
+  {
+    id: 'projection-destructure',
+    pattern: /\b(?:const|let|var)\s*\[[^\]]*\]\s*=\s*createProjection\b/g,
+    message:
+      'createProjection returns the store itself, not a [store, setter] tuple — destructuring it takes the first row. Write `const rows = createProjection(...)`.',
   },
   {
     // A two-phase createEffect whose apply is nothing but one (optionally
@@ -508,8 +588,9 @@ const CHECKS = [
   },
   {
     id: 'react-key-prop',
-    pattern: /\skey=\{/g,
-    message: 'React `key` prop has no meaning in Solid. Row identity belongs on <For keyed={...}>.',
+    find: reactKeyPropFindings,
+    message:
+      'React `key` prop has no meaning in Solid. Row identity belongs on <For keyed={...}>. (Only the @solidjs/meta tags take `key`, as the tag identity.)',
   },
   {
     // `{todos().map((t) => <Row />)}` renders then recreates every row.
@@ -574,8 +655,14 @@ const CHECKS = [
     message: 'Solid 1.x Vite plugin. Import `solid` from "@solidjs/vite-plugin".',
   },
   {
+    // Valueless attributes count too (`<input use:autofocus />`): followed by
+    // `/>`, `>`, or another attribute, unlike an unspaced object key
+    // (`{ on:true }`, `{ on:x = false }`, `{ attr:v as string }`); `as="font"`
+    // and SVG `in="…"` are still attributes. `prop:` is still a Solid 2
+    // namespace and is not listed.
     id: 'solid1-jsx-namespace',
-    pattern: /\b(?:use|on|oncapture|attr|bool):[A-Za-z][\w-]*=/g,
+    pattern:
+      /(?<=\s)(?:use|on|oncapture|attr|bool):[A-Za-z][\w-]*(?==|\s*\/?>|\s+(?!(?:as|satisfies|in|instanceof)\b(?!\s*=))[A-Za-z_${])/g,
     message:
       'Solid 1.x JSX namespace. Use ref callbacks (and directive factories), camelCase event props, and standard attributes.',
   },
@@ -787,10 +874,15 @@ function check() {
     files = [];
     scanned = pathArgs;
     walked = false;
+    // A missing path is always an error: a deleted file, a misspelled file, and
+    // a renamed source directory look the same here, and only the list's
+    // producer knows which it was.
     for (const arg of pathArgs) {
       const path = resolve(target, arg);
       if (!existsSync(path)) {
-        console.error(`solid2-kit check — path not found: ${path}`);
+        console.error(
+          `solid2-kit check — path not found: ${path} (drop deleted files from a changed-file list with \`git diff --name-only --diff-filter=d\`)`,
+        );
         process.exit(2);
       }
       if (statSync(path).isDirectory()) {
@@ -1129,8 +1221,10 @@ const BANNED_DEPS = {
 };
 
 // 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`.
+// 1.9, @solidjs/router 1.0, @solidjs/meta 0.29, @solidjs/testing-library 0.8,
+// @tanstack/solid-router 1.x, @tanstack/solid-query 5.x): a bare
+// `pnpm add <name>` installs it. The Solid 2 releases are published under
+// `next` (TanStack: `rc` — solid-router 2.0.0-rc.x, solid-query 6.0.0-rc.x).
 const SOLID2_LINE_PACKAGES = [
   { name: 'solid-js', id: 'solid-js-version', solid1: /^[\s^~=v]*[01](?:\.|$)/, fix: 'Install solid-js@next (^2).' },
   {
@@ -1145,6 +1239,24 @@ const SOLID2_LINE_PACKAGES = [
     solid1: /^[\s^~=v]*0(?:\.|$)/,
     fix: 'Meta 0.x is built for Solid 1 (<MetaProvider> required); install @solidjs/meta@next (1.x).',
   },
+  {
+    name: '@tanstack/solid-router',
+    id: 'tanstack-router-version',
+    solid1: /^[\s^~=v]*[01](?:\.|$)/,
+    fix: 'TanStack Router 1.x has a solid-js ^1.9 peer; install @tanstack/solid-router@rc (2.x, solid-js 2 peer).',
+  },
+  {
+    name: '@tanstack/solid-query',
+    id: 'tanstack-query-version',
+    solid1: /^[\s^~=v]*[0-5](?:\.|$)/,
+    fix: 'TanStack Query 5.x has a solid-js ^1.6 peer; install @tanstack/solid-query@rc (6.x, solid-js 2 peer).',
+  },
+  {
+    name: '@solidjs/testing-library',
+    id: 'testing-library-version',
+    solid1: /^[\s^~=v]*0(?:\.|$)/,
+    fix: 'Testing Library 0.x renders through solid-js/web (Solid 1); install @solidjs/testing-library@next (1.x, solid-js 2 peer).',
+  },
 ];
 
 function installedVersion(target, name) {

package/files/commands/solid2-review.md

@@ -39,7 +39,7 @@ Steps:
    - 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`;
+     data (writes vanish on settle) <!-- upstream:optimistic-value-overlay --> 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
@@ -47,10 +47,12 @@ Steps:
      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 })`;
+     `configureClientErrors` / `configureServerErrors` / `render(fn, root, undefined, { onError })`
+     (options are `render`'s 4th argument — a 3rd-argument object is `init`);
    - store setter callbacks that `await` (the draft closes when the callback returns —
-     `[ASYNC_STORE_SETTER]`), store setters called at component-body top level, and
-     `latest()` used as a null-safe read of an unsettled source;
+     `[ASYNC_STORE_SETTER]` <!-- upstream:async-store-setter-throws -->), store setters called at
+     component-body top level <!-- upstream:store-write-owned-scope -->, and `latest()` used as a
+     null-safe read of an unsettled source <!-- upstream:latest-throws-unsettled -->;
    - nested fetches assumed to waterfall, or `<Loading>` lifted along with a lifted fetch;
    - mutations on a value read through `live()` that settle on `yield save()` alone or
      `refresh()` the live-derived store, instead of `yield until(predicate, { timeout })`

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` — 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.
+- 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 — markup types are `JSX.Element` from `@solidjs/web` or `Element` from `solid-js` (alias it `SolidElement` next to DOM code) <!-- upstream:jsx-namespace-absent -->. 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) <!-- upstream:async-store-setter-throws -->, and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or per root `render(fn, root, undefined, { onError })` — options are the 4th argument), 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()`. <!-- upstream:dynamic-deprecated --> 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

@@ -18,7 +18,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    Rest props: `omit(props, "label", "value")` (or a predicate: `omit(props, (k) => k.startsWith("data-"))`),
    never `const rest = { ...props }` (a snapshot). `merge` / `omit` return read-only live
    views — assigning onto them is a silent no-op; `{ ...merged }` gives an own object that
-   never updates again.
+   never updates again. <!-- upstream:merge-omit-readonly -->
    JSX `{...rest}` is fine once `rest` is a reactive proxy. Rule of thumb: the string `props.`
    must never appear at component-body top level *as a read* (`const x = props.x`); nested
    functions (`() => props.x`, `omit(props, ...)`, `children(() => props.children)`) are fine.
@@ -42,7 +42,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    before a flush, use the setter updater (`setCount((c) => c + 1)`); `setCount(count() + 1)`
    reads the last *committed* value and drops the other staged writes. To store a *function*
    in a signal, wrap it: `setHandler(() => myHandler)` — `setHandler(myHandler)` treats it
-   as an updater.
+   as an updater. The initial value too: `createSignal(() => myHandler)` —
+   `createSignal(myHandler)` is the derived form (it calls `myHandler` and stores the result).
 5. `class`, not `className`; `for`, not `htmlFor`. `class` accepts strings, conditional
     objects, and nested arrays: `class={["btn", { active: selected() }]}`. Put *conditional*
     names in an object — `class={`btn ${on() ? "on" : ""}`}`, `clsx(...)`, and
@@ -60,13 +61,15 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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.
+7. **Lists use `<For>`**, never `{list().map(...)}` in reactive JSX and never `key` props (only `@solidjs/meta` tags take `key`, as the tag's identity).
     `{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 (dev + attribution flags the rebuilds as `[UNSTABLE_LIST_IDENTITY]`). Reference keying is for local arrays whose item identities are
+    recreates every row (dev + attribution flags the rebuilds as `[UNSTABLE_LIST_IDENTITY]`).
+    Usually better still: load them into a function-form store (rule 20), whose proxies keep
+    identity per id, and keep default keying. 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
@@ -83,8 +86,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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.
+    `createTrackedEffect` for that — it is `@deprecated` since 2.0.0-rc.9 (kept only for
+    1.x migration) <!-- upstream:tracked-effect-deprecated -->. 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. The return
    form is for shapes where mutation is awkward — most commonly removal
@@ -93,6 +96,9 @@ 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 setter takes only a function: `setState("a", v)` and the 1.x shallow merge
+   `setState({ a: 1 })` throw `fn is not a function`, and an object *returned* from the
+   callback replaces the whole store (keys it omits are deleted).
    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.
@@ -101,10 +107,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    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).
+   lost before) <!-- upstream:async-store-setter-throws -->. `await` first, then call the setter (inside an `action`, `yield` first).
    Mechanically enforced by `solid2-kit check`. A store setter called at
    component-body top level is a write in an owned scope (`[REACTIVE_WRITE_IN_OWNED_SCOPE]`,
-   same as a signal setter) — seed the initial shape through the `createStore` argument.
+   same as a signal setter) <!-- upstream:store-write-owned-scope --> — seed the initial shape through the `createStore` argument.
 10. **Async data is an async computation**: `createMemo(async () => ...)` (or
     `createMemo(() => fetchUser(id()))`) read under `<Loading>` / `<Errored>`.
     **Fetch high, block low** — creating/reading are like sync; consuming (await)
@@ -116,18 +122,22 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `<Child user={user()} />` then `{props.user.name}` under the child's
     `<Loading>` is the colorless form. `const u = user()` at the parent *is* a
     read and throws/snapshots there. Pass the memo itself only when the child
-    must `refresh()` that source — `isPending(() => props.user)` works on the
+    must `refresh()` that source — type that prop `SourceAccessor<User>` (`Accessor<User>`
+    is TS2345 at `refresh`) — `isPending(() => props.user)` works on the
     value. Read every reactive input **before the first
     `await`** — post-`await` reads do not subscribe, and in production the computation can
     sit pending with no retry. No `useEffect` + `setState` fetching, no `createResource`.
     `<Loading>` wraps the data slot, not page chrome. After first paint it keeps content
     during refetch (`isPending` for the indicator). Use `on={id()}` (the *value*, not the
-    accessor) only when that identity change should show the fallback again. Do not start `fetch` (or any request) at component-body top
+    accessor) only when that identity change should show the fallback again. `on` compares
+    with `!==` (several keys: one string such as `` `${a()}/${b()}` ``, never a fresh array)
+    and takes effect only when no reader outside the boundary waits on the same write
+    (that is how one slow panel stops holding the page). Do not start `fetch` (or any request) at component-body top
     level — that runs once at mount and is not a reactive source. Do not `try/catch` `NotReadyError` around a read, and do not
     use `loadingValue` / `seedLoadingValue` as the default first-flight UI — those skip
     `<Loading>`. `{latest(() => x())}` is a preview, not the visible answer, and not a
     null-safe probe: `latest(user)` before the first value throws `NotReadyError` in every
-    scope (event handlers included) — it never returns `undefined` for an unsettled source.
+    scope (event handlers included) — it never returns `undefined` for an unsettled source. <!-- upstream:latest-throws-unsettled -->
     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
@@ -196,8 +206,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     JSX (`<Show>`, ternary, `<Switch>`/`<Match>`). Early returns on genuinely non-reactive
     values (build-time config, missing env) are fine. `<Switch>` is first-wins: later
     truthy `<Match>`es are skipped, not “all matching branches”.
-16. Prefer `textContent` for text-only content. Use `innerHTML` only for trusted or
-    sanitized markup — never interpolate user input into it, never React's
+16. Plain text is ordinary JSX children (`<p>{message()}</p>`); `textContent` is for an
+    element whose entire content is one text value, never together with children. Use
+    `innerHTML` only for trusted or sanitized markup — never interpolate user input into it, never React's
     `dangerouslySetInnerHTML`, and never combine `innerHTML` with JSX children (they fight
     over the same contents).
 17. **Never narrow a reactive read with a non-null assertion** (`error()!.message`,
@@ -224,7 +235,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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 })`
+    `solid-js` (or per root: `render(() => <App />, root, undefined, { onError })` — options
+    are the 4th argument, the 3rd is `init` — and `hydrate(fn, root, { onError })`) and `configureServerErrors({ onError })`
     from `@solidjs/web` — do not call `captureException` inside `<Errored fallback>`.
     The server hook's return value replaces the sanitized error on the wire: return
     nothing or a reference id, never the error itself (message/stack/secrets would
@@ -245,6 +257,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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).
+    Polling is `onSettled(() => { const t = setInterval(() => refresh(stats), 30_000); return () => clearInterval(t); })`.
+    Two components that each create the same memo make two requests (no automatic
+    dedup) — create it once and pass it down or through context (router: `query`).
     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
@@ -255,13 +270,19 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     apply `reconcile(fresh, "id")(draft.slot)` inside a draft setter. Plain wholesale
     assignment (`draft.todos = fresh`) renders correctly but notifies every subscriber
     under the path and destroys row identity — same class of problem as unkeyed `<For>`.
+    `createProjection` returns the store itself, not a tuple (`const [rows] = createProjection(…)`
+    type-checks and yields row 0). `reconcile` onto a single-object store whose `id`
+    changes throws in dev (`Cannot reconcile states with different identity`) — switch records
+    with the function form (`createStore(() => getUser(id()), seed)`) or a returned object.
 21. **Solid inputs do not rewind the DOM.** `value={v()}` writes only when `v` changes; a
     React-style controlled input that ignores invalid keystrokes silently breaks. To reject
     input, write back explicitly:
     `onInput={(e) => { if (valid(e.currentTarget.value)) setV(e.currentTarget.value); else e.currentTarget.value = v(); }}`.
 22. Miscellaneous defaults: SSR-stable element ids come from `createUniqueId()` (never
     `Math.random()` or hardcoded duplicates); pass store data to `structuredClone` /
-    `postMessage` / logs via `snapshot(store)` (proxies fail or leak reactivity); render
+    `postMessage` / logs via `snapshot(store)` (proxies fail or leak reactivity) — a
+    view, not a copy: unchanged subtrees are the store's own objects, so mutating it (a
+    library's `arr.sort()`) silently changes the store; copy with `structuredClone(snapshot(store))`; 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). Durable data
@@ -269,7 +290,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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
+    outside an action do not stick <!-- upstream:optimistic-value-overlay --> — 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
@@ -292,7 +313,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     after touching `package.json` / tsconfig / root configs; it fails on React and Solid 1.x
     wiring. Server vs browser:
     `isServer` / `isDev` from `@solidjs/web`, or `clientOnly(() => import("./Widget"))` for
-    browser-only components — never `typeof window` as the SSR boundary. Default
+    browser-only components — never `typeof window` as the SSR boundary. `isServer` picks
+    code paths, never markup: a JSX branch on it (or on `Date.now()` / `Math.random()`) is
+    a hydration mismatch. On the server the component body and memo/effect *computes*
+    run; effect `apply`, `onSettled`, and handlers do not. A `clientOnly` placeholder is
+    its `fallback` prop (`<Chart fallback={<Skeleton />} />`, rendered by SSR), not a
+    `<Loading>` around it; named exports take `{ export: "Chart" }`. Default
     `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.
@@ -318,7 +344,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     fallback body), not event-time mutations. `JSON.stringify(store)`
     / `structuredClone(store)` without `snapshot(store)` can throw or leak proxies. Async SSR
     without `<Loading>` *works* but blocks the HTML shell until every read settles — wrap
-    reads, or stream with `renderToStream`. `pipe` / `pipeTo` / `readable` each consume
+    reads, or stream with `renderToStream`. A read that must be in the first HTML (SEO,
+    link previews) takes `{ deferStream: true }` on its memo; keep the boundary. `pipe` / `pipeTo` / `readable` each consume
     a stream render — use exactly one. `createRoot` is for tests, libraries, and
     non-render entry points; inside a component let `render` / the component owner
     own the scope. Async reads inside `<Portal>` start on the client — hoist the
@@ -333,7 +360,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     because the named export is not a call-site literal. Select a component from reactive
     state with `dynamic(() => ...)` from `@solidjs/web`
     (stable identity); `<Dynamic component={...}>` is deprecated (`@deprecated` in the
-    types since 2.0.0-rc.9, still shipped in 2.0). If the project has `@solidjs/router`, routes are `createRouter({ routes })`
+    types since 2.0.0-rc.9, still shipped in 2.0) <!-- upstream:dynamic-deprecated -->. If the project has `@solidjs/router`, routes are `createRouter({ routes })`
     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">`
@@ -369,12 +396,13 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`. A static
     `<title>` in the document shell is the fallback; do not hardcode other tags
     (`<meta name="description">`) that Solid Meta should manage.
-    Return `respond(value, { status, headers })` from a `"use server"` function, not
-    `Response.json` — a raw `Response` is HTTP-handler control flow; scripted
-    callers should receive the value. Production sanitizes every thrown value that
+    Success metadata is `return respond(value, { status: 201, headers })` from a
+    `"use server"` function, not `Response.json` — a raw `Response` is HTTP-handler control
+    flow; scripted callers should receive the value. A *returned* `respond()` resolves the
+    call whatever its status, so a failure is `throw respond(body, { status: 400 })`. Production sanitizes every thrown value that
     crosses the wire — server-function throws **and** SSR render errors (an `<Errored>`
     fallback printing `err().message` shows `"Internal Server Error"` in a production
-    server render) — so intentional client-facing failures are `markSafeError(...)` or
+    server render) <!-- upstream:ssr-error-sanitized --> — 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). `redirect()` /
     `reload()` are signals for an integration: Solid Router's `action` / `query` and the
@@ -399,14 +427,18 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     display). Do not write subscribe/unsubscribe in the component around `live()`.
     When the app has a server bundle (`ssr` or server functions), production is
     `handleRequest(request)` from the built `dist/server/server.js` (or its
-    Fetchable `fetch`); platform Vite plugins adopt that handler (Node: the
-    template `server.js`). Client-only start mode is static `dist/client` —
+    Fetchable `fetch`); platform Vite plugins adopt that handler. Node: set
+    `start: { node: true }` and run `node dist/server/node.js` (serves `dist/client`,
+    reads `PORT` / `HOST`; its exported `listener` mounts in an existing Express /
+    Fastify server) — `server.js` is only the handler module. Client-only start mode is static `dist/client` —
     there is no handler to wrap. Request middleware is
     `start: { middleware: "./src/middleware.ts" }`, not Express `app.use`. Do not return
     components from `"use server"` unless the project already enabled the
-    experimental `serverFunctions.components` flag. JSON-encodable server-function arguments
-    only, unless `enableRichArguments()` was called once in the client entry
-    (`Date` / `Map` / `Set` throw without it). Declare live reads as `live(GET(fn))` —
+    experimental `serverFunctions.components` flag. Server-function arguments are JSON:
+    send `Date` / `Map` / `Set` as ISO strings / arrays (they throw otherwise; one `File` /
+    `Blob` / `FormData` argument travels natively). `enableRichArguments()` from
+    `@solidjs/web/server-functions/rich-args` (at `src/App.tsx` module scope) lifts that,
+    but in rc.9 importing it fails `vite build` (`"./client" is not exported`) <!-- upstream:rich-args-vite-build https://github.com/solidjs/solid/issues/3627 -->. Declare live reads as `live(GET(fn))` —
     `live()` outermost. A plain `async function*` server function is an event stream on
     one connection (no reconnect when it drops); `live()` is one value that changes over
     time and reconnects. `live()` connection state is
@@ -437,7 +469,7 @@ directory (default `src/`).
 | `solid/event-handlers` | still valid | rule 6 |
 | `solid/jsx-no-undef`, `jsx-no-duplicate-props` | covered by TypeScript | project typecheck |
 | `solid/prefer-classlist` | obsolete — `classList` removed | `solid2-kit check` bans `classList` |
-| `solid/no-unknown-namespaces` | obsolete — `on:`/`use:`/`attr:` removed in 2.0 | banned-API table + `solid2-kit check` |
+| `solid/no-unknown-namespaces` | obsolete — `on:`/`use:`/`attr:` removed in 2.0 (`prop:` remains) | banned-API table + `solid2-kit check` |
 | `solid/no-proxy-apis` | obsolete — Solid 2 requires Proxy | not carried |
 
 ## Banned Solid 1.x APIs (Solid 2 replacements)
@@ -445,15 +477,15 @@ directory (default `src/`).
 | Never write (Solid 1.x) | Write instead (Solid 2) |
 |---|---|
 | `import ... from "solid-js/store"` or `"solid-js/web"` | stores/`merge`/`omit` from `"solid-js"`; `render`/`hydrate`/`Portal`/`Dynamic` from `"@solidjs/web"` |
-| `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"` |
+| `import type { JSX } from "solid-js"` | `solid-js` exports no `JSX` namespace: markup types are `JSX.Element` from `"@solidjs/web"` (with `JSX.IntrinsicElements`, `JSX.CSSProperties`) or `Element` from `"solid-js"` — import the latter as `type Element as SolidElement` where the DOM `Element` is also used, or it shadows it <!-- upstream:jsx-namespace-absent --> |
 | `createResource` | async `createMemo` + `<Loading>`/`<Errored>`; `refresh()`, `latest()`, `isPending()` |
-| `createEffect(fn)` (one arg), `on(...)` | `createEffect(compute, apply)`; deps belong in `compute` |
+| `createEffect(fn)` (one arg), `on(...)`, `createTrackedEffect` (deprecated in 2.0) <!-- upstream:tracked-effect-deprecated --> | `createEffect(compute, apply)`; deps belong in `compute`; one-time DOM work is `onSettled` |
 | `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}>` |
 | `<Ctx.Provider value={...}>` | `<Ctx value={...}>` |
-| `setState("a", "b", value)` path setters, `produce(...)` | draft setter: `setState(draft => { ... })` |
+| `setState("a", "b", value)` path setters, `setState({ a })` merges, `produce(...)` | draft setter: `setState(draft => { ... })` (the others throw `fn is not a function`) |
 | `mergeProps` / `splitProps` / `unwrap` | `merge` / `omit` / `snapshot` |
 | `classList={...}` | `class` object/array form |
 | `createMutable`, `modifyMutable` | `createStore` + draft setters (direct writes to the store are silently ignored) |
@@ -461,24 +493,24 @@ directory (default `src/`).
 | `startTransition`, `useTransition` | automatic held updates + `isPending` |
 | `onError` / `catchError` | `<Errored>` or effect bundle `{ effect, error }` |
 | `from(...)` / `observable(...)` (the solid-js helpers) | inbound: async iterable from a memo; outbound: split effect |
-| `createDynamic(...)`, `<Dynamic component={...}>` (deprecated in 2.0) | `dynamic(source)` from `@solidjs/web` |
+| `createDynamic(...)`, `<Dynamic component={...}>` (deprecated in 2.0) <!-- upstream:dynamic-deprecated --> | `dynamic(source)` from `@solidjs/web` |
 | `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)` (`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) |
+| `useCurrentMatches`, `MemoryRouter` / `createMemoryHistory`, `redirect` / `reload` from `@solidjs/router`, `indexArray` | `useRouteMatches`, `createRouter({ routes, history: memoryHistory("/x") })`, `redirect` / `reload` from `@solidjs/web`, `mapArray(list, fn, { keyed: false })` |
 | `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`) |
 | `<MetaProvider>` | no provider — render `<Title>` / `<Meta>` / `<Link>` from `@solidjs/meta` anywhere |
-| `use:directive`, `on:`/`oncapture:`, `attr:`/`bool:`, `/*@once*/` | `ref` callbacks, camelCase event props, standard attributes, keep values reactive |
+| `use:directive`, `on:`/`oncapture:`, `attr:`/`bool:`, `/*@once*/` | `ref` callbacks, camelCase event props, standard attributes, keep values reactive; `prop:` remains for DOM properties (`prop:indeterminate`, objects/arrays on custom elements — plain props are attributes and stringify) |
 | `resource.loading` / `resource.error` | `<Loading>` boundary / `<Errored>` boundary |
 
 When unsure about any API, verify against the official Solid 2.0 docs — fetchable URLs are
 listed in `references/official-docs.md` next to the `solid-2` skill. Do not guess from
 Solid 1.x or React memory.
 
-`createTrackedEffect` and `createRenderEffect` exist in Solid 2 but are not defaults:
-use two-phase `createEffect` unless a single tracked callback is required. `storePath`
+`createRenderEffect` exists in Solid 2 but is not a default. `storePath`
 (the 1.x path-setter migration helper) is no longer exported from `solid-js` as of
 2.0.0-rc.9 — convert path setters to draft setters instead of importing it from
-`@solidjs/signals`.
+`@solidjs/signals`. <!-- upstream:store-path-removed -->

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

@@ -69,13 +69,13 @@ Most React `useEffect` code should NOT become `createEffect`:
 | Inspect, count, or iterate children | `children(() => props.children)` then `.toArray()` |
 | Code-split a component | `lazy(() => import("./X"))` read under `<Loading>` |
 | Named export from a lazy module | `lazy(() => import("./pages"), { export: "About" })` |
-| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; `<Dynamic>` is deprecated) |
+| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; `<Dynamic>` is deprecated) <!-- upstream:dynamic-deprecated --> |
 | Overlay / modal | `<Portal>` — hoist async reads *above* the portal (reads inside start on the client) |
 | 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 widget (charts, maps, `window`) | `clientOnly(() => import("./Chart"))` from `@solidjs/web` (`{ lazy: true }` defers the import until first render; `{ export: "Chart" }` for a named export). Placeholder: `<Chart fallback={<Skeleton />} />` — SSR renders the fallback; a `<Loading>` around it leaves the server HTML empty |
 | 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` |
+| Server vs browser code path | `isServer` / `isDev` from `@solidjs/web` (build-time constants), not `typeof window` — never to choose markup (`{isServer ? <A /> : <B />}` is a hydration mismatch; use `clientOnly` / `ssrSource`) |
 | SSR-stable `id` / `for` / `aria-*` pairing | `createUniqueId()` |
 
 ## Canonical patterns
@@ -125,7 +125,7 @@ usual defaults pattern. That is not Solid 1 `mergeProps`, which ignored
 (`omit(props, (key) => key.startsWith("data-"))`). `const rest = { ...props }` compiles
 and then never updates. Both helpers return **read-only live views** (since
 2.0.0-rc.9 for every input, plain objects included): assigning onto the result is a
-silent no-op, and `{ ...merged }` is an own object that carries no sources.
+silent no-op, and `{ ...merged }` is an own object that carries no sources. <!-- upstream:merge-omit-readonly -->
 
 ### Store updates (draft mutation)
 
@@ -142,7 +142,7 @@ setProfile((draft) => {
 The setter callback is a **synchronous transaction** — the draft closes when it
 returns. `setProfile(async (draft) => { draft.name = await load(); })` used to commit
 only the writes before the first `await` and silently drop the rest; since
-2.0.0-rc.9 it throws `[ASYNC_STORE_SETTER]` in dev (`solid2-kit check` flags it too).
+2.0.0-rc.9 it throws `[ASYNC_STORE_SETTER]` in dev (`solid2-kit check` flags it too). <!-- upstream:async-store-setter-throws -->
 Await outside, then write synchronously (inside an `action`, `yield` first):
 
 ```tsx
@@ -156,7 +156,7 @@ setProfile((draft) => { draft.name = name; });
 
 A signal may hold a promise, so `setSignal` has no such rule. A store setter called
 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
+`[REACTIVE_WRITE_IN_OWNED_SCOPE]` (rc.9 closed the exemption store writes had) <!-- upstream:store-write-owned-scope --> — 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
@@ -195,7 +195,10 @@ subscribers under the path re-run and row identity is lost. In order of preferen
    `setState((draft) => { reconcile(fresh, 'id')(draft.todos); })`. Positional data
    (fixed-shape dashboards): `reconcile(next, null)`.
 
-Plain non-reactive copy for logging/serialization/`structuredClone`: `snapshot(store)`.
+Plain non-reactive view for logging/serialization: `snapshot(store)`. It is not a copy —
+subtrees with no pending changes are the store's own objects, so mutating the snapshot
+(or letting a library `sort()` it) changes the store with no notification. Edit
+`structuredClone(snapshot(store))` instead.
 Subscribe an effect compute to every nested change: `deep(store)`.
 
 ### Children: pass through, or resolve with `children()`
@@ -258,7 +261,7 @@ variable in JSX (`const View = tab() ? A : B` freezes the choice at setup).
 `<Dynamic component={...}>` is the same primitive with a worse shape (the tag travels
 in the props bag, so every instance merges and omits it and rebuilds a factory) and
 is **deprecated** since 2.0.0-rc.9 — `@deprecated` in the types, no runtime warning,
-still shipped in 2.0. Hoist a `dynamic()` per component instance (or per module for a
+still shipped in 2.0. <!-- upstream:dynamic-deprecated --> Hoist a `dynamic()` per component instance (or per module for a
 constant tag) instead.
 
 ### Two-phase effect (imperative boundary only)
@@ -432,7 +435,7 @@ return <StoryDetail story={story} />;
   `isPending(() => results())`). Freshest in-flight value for a preview:
   `latest(results)`. `latest` is not a null-safe probe: before the source's first value
   it throws `NotReadyError` in every scope (since 2.0.0-rc.9 also in event handlers and
-  imperative code, which used to receive `undefined`). A write is visible to `latest()` /
+  imperative code, which used to receive `undefined`) <!-- upstream:latest-throws-unsettled -->. A write is visible to `latest()` /
   `isPending()` only from the flush that carries it — `flush()` first when a test reads
   its own write through them. Do not start `fetch` at component-body top level.
 - Coordinate sibling `<Loading>` reveal with `<Reveal>` (`order="sequential"` default,
@@ -500,12 +503,15 @@ registers this hook must load before the server graph — put it in the plugin's
 `start: { instrument: "./src/instrument.ts" }`, not at the top of an entry (see
 [Production observability](#production-observability-the-observe-build)).
 
-`render` / `hydrate` accept a per-root `onError` that wins over the ambient hook.
+`render` / `hydrate` accept a per-root `onError` that wins over the ambient hook —
+`render(() => <App />, root, undefined, { onError })` (options are the 4th argument; a
+3rd-argument object is taken as `init` and the hook is silently not installed) and
+`hydrate(() => <App />, root, { onError })`.
 Uncaught errors (`REACTIVITY_HALTED`) go to the platform's `reportError`, which every
 monitor already listens on — do not report them twice. `renderToStream` /
 `renderToString`'s `onError` option *is* the per-render server hook: it now hears every
 handled failure, so filter on `context.handling === "failed"` when only request-failing
-errors matter (the rc.8 one-argument form keeps working).
+errors matter (the rc.8 one-argument form keeps working). <!-- upstream:render-onerror-handled -->
 
 ### Streams and subscriptions (websockets, reactive clients)
 
@@ -644,7 +650,8 @@ 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
 prediction. (Router `query` or `@tanstack/solid-query` remain valid when the
-project already uses them; they are not required to "make it real".)
+project already uses them; they are not required to "make it real". Solid 2's
+TanStack Query is `@tanstack/solid-query@rc` (6.x) — npm `latest` is the Solid 1 5.x line.)
 Optimistic rows stay interactive — a not-yet-acked todo can still
 be toggled. Do not disable the control until confirmation, and do not mutex
 rapid clicks; `action` is the transaction (no half-mutation, no interleaved
@@ -660,7 +667,7 @@ handler or the `action`.
 `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
+leaves an empty list once the action settles, with no warning. <!-- upstream:optimistic-value-overlay --> 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
@@ -1010,7 +1017,8 @@ writes from owned scopes, and async reads outside `<Loading>`. Fix them; don't s
 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
+Component tests use `@solidjs/testing-library@next` (1.x; npm `latest` is the Solid 1
+0.8 line). Pass a **function** to `render` so
 the tree has an owner, and `flush()` after interactions that stage writes:
 
 ```tsx
@@ -1029,6 +1037,14 @@ test('increments on click', () => {
 });
 ```
 
+Primitive tests write **outside** the root callback — a write inside `createRoot((dispose)
+=> { …; setA(2); })` is `[REACTIVE_WRITE_IN_OWNED_SCOPE]` in dev. Return the handles, then
+write and `flush()`: `const { setA, b, dispose } = createRoot((dispose) => { …; return
+{ setA, b, dispose }; }); setA(2); flush();`. A hook that reads context runs under
+`renderHook(useCart, { wrapper: CartProvider })`. A routed component gets a router built in
+the test — `createRouter({ routes, history: memoryHistory("/orders/42") })` — because
+Testing Library's `render(…, { location })` is typed but not implemented (1.0.0-beta.3). <!-- upstream:testing-library-location -->
+
 `jsxImportSource` for tests and app code is `"@solidjs/web"`, not `"solid-js"`.
 Vite plugin is `@solidjs/vite-plugin`, not `vite-plugin-solid`.
 
@@ -1054,14 +1070,14 @@ in observe and dev) and **checks** (dev-only guidance printed by the console rep
 Always-on dev checks include misplaced reads
 (`[STRICT_READ_UNTRACKED]`, `[PENDING_ASYNC_UNTRACKED_READ]`), misplaced writes
 (`[REACTIVE_WRITE_IN_OWNED_SCOPE]` — since rc.9 also for store setters called in a
-component or root body, `[ASYNC_STORE_SETTER]` for a store setter callback that returns
-a promise, `[FLUSH_IN_ACTION]`, `[SERVER_WRITE]`), and
+component or root body <!-- upstream:store-write-owned-scope -->, `[ASYNC_STORE_SETTER]` for a store setter callback that returns
+a promise <!-- upstream:async-store-setter-throws -->, `[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.
 Since rc.9 the server render reports on the same channel with the same owner chains:
 `[SSR_RENDER_ERROR_CONTAINED]` (a boundary routed a render error; `ownerPath` is where
-it was thrown, `boundaryPath` where it was met), `[SSR_ERROR_SANITIZED]` (the original
+it was thrown, `boundaryPath` where it was met) <!-- upstream:ssr-render-error-contained -->, `[SSR_ERROR_SANITIZED]` (the original
 behind a production-sanitized error), `[SSR_CLIENT_CONTENT_MASKED]` (client-only content
 that surfaced only after a real server wait — the wait was wasted), server-side
 `[ASYNC_WATERFALL]`, and `[REVEAL_IN_RENDER_TO_STRING]`.
@@ -1072,7 +1088,7 @@ code maps to what the runtime observed and what to change.
 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. Since
 `solid-js` 2.0.0-rc.8 the engine lives behind its own subpath — `DEV.attribution`
-no longer exists (it is a type error; `DEV` holds only devtools hooks, graph
+no longer exists <!-- upstream:dev-attribution-removed --> (it is a type error; `DEV` holds only devtools hooks, graph
 traversal, and console reporting). `OBSERVE` is the public observability surface on
 the observe and dev builds — `OBSERVE.records`, `OBSERVE.diagnostics`,
 `OBSERVE.exclude`, `OBSERVE.server.trace` are for app and tool code; only the
@@ -1080,7 +1096,7 @@ the observe and dev builds — `OBSERVE.records`, `OBSERVE.diagnostics`,
 to engines, routers, and devtools. Since 2.0.0-rc.9 the folds, queries, and
 formatters are **named exports** of that subpath, not methods of `attribution`
 (`attribution.why` / `.costs` / `.feedback` / `.subscriptions` / `.format` are type
-errors); `attribution` keeps `enable`, `disable`, `subscribe`, `markFlight`, and the
+errors) <!-- upstream:attribution-named-exports -->; `attribution` keeps `enable`, `disable`, `subscribe`, `markFlight`, and the
 record ring buffers (`history`, `holds`, `waterfalls`, `navigations`, `interactions`):
 
 ```ts
@@ -1287,22 +1303,28 @@ Solid Router 0.x/1.x stand-ins.** Patterns below; fetch the matching pages from
 ```
 
 `solid-js` does **not** export a `JSX` namespace — `import type { JSX } from "solid-js"`
-is a type error (TS2305), and `JSX.Element` as the children type is a React reflex.
-Children/return types are the renderer-neutral `Element` from `solid-js`
+is a type error (TS2305) <!-- upstream:jsx-namespace-absent -->. Markup types are `JSX.Element` from `@solidjs/web` (the
+docs' choice; it also admits DOM nodes) or the renderer-neutral `Element` from `solid-js`
 (`children?: Element`), alongside `Component` / `ParentProps` / `Accessor` / `Setter`.
-DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) and
-`ComponentProps` come from `@solidjs/web`. Vite: `import solid from "@solidjs/vite-plugin"`
+Import the latter as `import type { Element as SolidElement } from "solid-js"` in any file
+that also uses DOM elements — unaliased, it shadows the DOM `Element`
+(`el.getBoundingClientRect()` becomes TS2339). DOM-specific `JSX` types
+(`JSX.IntrinsicElements`, `JSX.CSSProperties`) and `ComponentProps` come from
+`@solidjs/web`. Vite: `import solid from "@solidjs/vite-plugin"`
 with `start: true` / `ssr: true` / `serverFunctions: true` only when the
 project already uses start mode. Tiers are `bare` → `basic` (router) →
 `fullstack` (SSR + server functions); do not jump a tier without cause.
-Under `start: true` the plugin owns entries, the document shell, and the build —
-write `src/App.tsx`, not SolidStart-style `entry-client.tsx` / `entry-server.tsx`
-or a hand-written `index.html`.
+Under `start: true` the plugin owns entries and the build — write `src/App.tsx`, not
+SolidStart-style `entry-client.tsx` / `entry-server.tsx` (authored ones replace the
+generated entries) or a hand-written `index.html`. The document shell (`<html lang>`,
+favicon, fallback `<title>`) is an optional `src/Document.tsx` default export that renders
+`<HydrationScript />` in `<head>` and `<body>{props.children}</body>`; `App` never renders
+`<html>`.
 
 ### Solid Router 2 — `createRouter`, not JSX `<Route>`
 
 ```tsx
-import { lazy } from 'solid-js';
+import { Loading, lazy } from 'solid-js';
 import { createRouter } from '@solidjs/router';
 
 export const Router = createRouter({
@@ -1320,7 +1342,9 @@ export default function App() {
       {(props) => (
         <>
           <a href={Router.paths}>Home</a>
-          <main>{props.children}</main>
+          <Loading fallback={<p>Loading…</p>}>
+            <main>{props.children}</main>
+          </Loading>
         </>
       )}
     </Router>
@@ -1328,7 +1352,9 @@ export default function App() {
 }
 ```
 
-Create the instance at **module scope**. Nested layouts are `children` arrays
+The `<Loading>` covers the first load of the lazy pages (and lets SSR stream the shell);
+later navigations hold the current page while the next one loads (links get
+`data-pending`). Create the instance at **module scope**. Nested layouts are `children` arrays
 on the route objects, not nested `<Route>` / nested routers. Solid Router does
 **not** support nested `<Router>` instances — compose one route tree (or a lazy
 `children` thunk). Navigate with
@@ -1410,7 +1436,9 @@ setSearch] = useSearchParams()` — the setter merges and navigates without scro
 `""` / `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).
+the raw strings rather than throwing). Query values are strings, so coerce in the schema —
+`page: v.optional(v.pipe(v.unknown(), v.transform(Number)), 1)`; a plain `v.number()`
+rejects every value and hands back the string, still typed `number`.
 
 **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
@@ -1435,6 +1463,14 @@ const save = action(async (form: FormData) => {
 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.
+Optimistic rows for a router form keep the `<form>` and add no core `action`: read the
+list `query` with `createOptimisticStore(() => getList(), [])` and register
+`save.onSubmit((form) => setList((d) => { d.push({ …, pending: true }); }))` in the
+component — the hook runs inside the action's transaction, so the row is an overlay,
+replaced on settle by the revalidated `query` (a plain server-function read is not
+revalidated, so the row just disappears).
+`useSubmissions` keeps only completions with a result or error; observe void and
+redirect completions with `save.onSettled(hook)`.
 
 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.
@@ -1534,7 +1570,15 @@ A function-level server function cannot close over component locals — pass
 values as arguments. Treat every argument as untrusted — TypeScript does not
 cross the HTTP boundary, so do not invent tRPC / RPC type-gen;
 validate inside the function (a parse in the function body is that
-validation, not an RPC schema across the wire). These functions *are* the RPC — do not add an
+validation, not an RPC schema across the wire). Checks belong in the body: HTTP dispatch
+calls a function-level `"use server"` body directly, so a HOF around it (`withAuth(fn)`,
+`validated(schema, fn)`) runs for in-process calls and is skipped for `curl` — an auth
+bypass. A wrapper inside a file-level `"use server"` module (`export const x =
+withAccount(async …)`) is what gets registered and does run. Arguments are capped at 1 MiB
+by default (413 beyond; the host's `bodySizeLimit`) — upload large files to a signed URL.
+Never hand a server function point-free to a library callback (`mutationFn: renameUser`,
+`onClick={deleteTodo}`): every argument the callback receives (a context object, the
+event) is sent over the wire — wrap it in an arrow that passes only the data. These functions *are* the RPC — do not add an
 API-route file (or a Next `route.ts`) just to wrap `db.todos.insert`. API
 routes are for real HTTP endpoints (webhooks, third-party POST), not for the
 app's own RPC. Read trusted identity
@@ -1588,12 +1632,19 @@ response) close that loop. For 404 during SSR: `httpStatus(404)` from `@solidjs/
 on the server-function wire **and**, since 2.0.0-rc.9, on every SSR road a failure
 takes (an `<Errored>` fallback rendered on the server, a rejected async source
 serialized into the stream, a `<Loading>` fragment's rejection), so `err().message`
-in a fallback reads the generic message in a production server render. Use
-`markSafeError` or `respond(..., { status })` for intentional client-facing
-failures. Do not `return Response.json(...)` from `"use server"` — that is
-HTTP-handler control flow; `respond(value, { status })` is what a scripted
-caller unwraps. JSON-encodable arguments only unless `enableRichArguments()`
-was called once in the client entry (`Date` / `Map` / `Set` throw without it).
+in a fallback reads the generic message in a production server render. <!-- upstream:ssr-error-sanitized --> Use
+`throw markSafeError(...)` or `throw respond(..., { status })` for intentional
+client-facing failures — a *returned* `respond()` resolves the call whatever its
+status, so `return respond({ error }, { status: 400 })` reads as success to the UI,
+`useSubmissions`, and the optimistic overlay. Do not `return Response.json(...)` from
+`"use server"` — that is HTTP-handler control flow; `return respond(value, { status: 201 })`
+is success metadata a scripted caller unwraps. Arguments are JSON: send `Date` / `Map` /
+`Set` as ISO strings / arrays (they throw otherwise; one `File` / `Blob` / `FormData`
+argument travels natively). `enableRichArguments()` from
+`@solidjs/web/server-functions/rich-args` (at `src/App.tsx` module scope) lifts that, but
+in rc.9 importing it fails `vite build` (`"./client" is not exported` — the dev server
+works, so the break shows only at build); `resolve: { dedupe: ["@solidjs/web"] }` in the
+Vite config works around it. <!-- upstream:rich-args-vite-build https://github.com/solidjs/solid/issues/3627 -->
 `GET()` is only for idempotent reads (URLs leak into logs/history);
 import it from `@solidjs/web/server-functions`, never `@solidjs/start`.
 Reads are function calls too: `GET(async (id) => { "use server"; ... })` is invoked
@@ -1686,9 +1737,11 @@ When the app has a server bundle (`ssr` or server functions), production is
 `handleRequest(request)` from the built `dist/server/server.js` (or that
 module's Fetchable default `fetch`) — not an import from `solid-js`. Cloudflare /
 Netlify / Nitro Vite plugins adopt that handler — do not write a Solid adapter,
-a custom Worker, or a Netlify Function. For Node, use the official template
-`server.js` (web `Request` in, stream the response); do not invent an
-Express/Solid bridge. Client-only `start: true` is still static `dist/client`
+a custom Worker, or a Netlify Function. For Node, set `start: { node: true }` and run
+`node dist/server/node.js` (serves `dist/client`, reads `PORT` / `HOST`); inside an
+existing Express / Fastify app, mount the `listener` that file exports — do not
+hand-write a Node↔web bridge (`node dist/server/server.js` starts nothing: it is the
+handler module). Client-only `start: true` is still static `dist/client`
 — there is no handler to wrap. Request middleware is the Vite option
 `start: { middleware: "./src/middleware.ts" }` (web `Request` + `next`), not
 Express `app.use`. Server functions that return components
@@ -1807,7 +1860,7 @@ how to reuse. Prefer the form on the right.
 | `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` |
-| `findUser(userId)` with the id from the client as identity | `getRequestEvent()!.locals.userId` |
+| `findUser(userId)` with the id from the client as identity | `const userId = getRequestEvent()?.locals.userId; if (!userId) throw respond(null, { status: 401 });` (`throw redirect("/sign-in")` under a router `action` / `query`) |
 | `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...}>` |
@@ -1839,20 +1892,20 @@ how to reuse. Prefer the form on the right.
 | `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 deprecated (rc.9); `dynamic()` hoists the factory and keeps identity stable |
-| `setStore(async (draft) => { draft.x = await load(); })` | `const x = await load(); setStore((draft) => { draft.x = x; })` — the setter is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]` |
-| `setStore((d) => { d.items = seed; })` in a component body | seed through `createStore(seed)` / `createStore(() => props.items, fallback)` — a body-level store write is `[REACTIVE_WRITE_IN_OWNED_SCOPE]` |
+| `<Dynamic component={tab() ? A : B} />` | `const View = dynamic(() => (tab() ? A : B))` — `<Dynamic>` is deprecated (rc.9); `dynamic()` hoists the factory and keeps identity stable <!-- upstream:dynamic-deprecated --> |
+| `setStore(async (draft) => { draft.x = await load(); })` | `const x = await load(); setStore((draft) => { draft.x = x; })` — the setter is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]` <!-- upstream:async-store-setter-throws --> |
+| `setStore((d) => { d.items = seed; })` in a component body | seed through `createStore(seed)` / `createStore(() => props.items, fallback)` — a body-level store write is `[REACTIVE_WRITE_IN_OWNED_SCOPE]` <!-- upstream:store-write-owned-scope --> |
 | `const saved = await api.save(); yield until(() => ...)` | `await api.save(); yield; yield until(() => ...)` — a bare `yield` re-enters the transaction before any reader is created, not only before writes |
-| `fallback={(err) => { captureException(err()); return <Fallback />; }}` | `configureClientErrors({ onError })` from `solid-js` (or `render(..., { onError })`), `configureServerErrors({ onError })` from `@solidjs/web` — once per error, with `ownerPath` / `boundaryPath` |
-| `latest(user) ?? placeholder` in a handler as a null-safe read | `latest()` throws `NotReadyError` before the first value in every scope; read settled values under `<Loading>`, or `await until(() => user())` |
-| `attribution.why(total)` / `attribution.format(e)` / `attribution.costs()` | named imports from `solid-js/attribution`: `why(total)`, `formatRerun(e)`, `costs()`, `feedback()`, `subscriptions(scope)` (rc.9) |
+| `fallback={(err) => { captureException(err()); return <Fallback />; }}` | `configureClientErrors({ onError })` from `solid-js` (or per root `render(fn, root, undefined, { onError })`), `configureServerErrors({ onError })` from `@solidjs/web` — once per error, with `ownerPath` / `boundaryPath` |
+| `latest(user) ?? placeholder` in a handler as a null-safe read | `latest()` throws `NotReadyError` before the first value in every scope; read settled values under `<Loading>`, or `await until(() => user())` <!-- upstream:latest-throws-unsettled --> |
+| `attribution.why(total)` / `attribution.format(e)` / `attribution.costs()` | named imports from `solid-js/attribution`: `why(total)`, `formatRerun(e)`, `costs()`, `feedback()`, `subscriptions(scope)` (rc.9) <!-- upstream:attribution-named-exports --> |
 | `attribution.enable()` unguarded in app code, or `enable()` with the default `log: true` left on | `if (isDev) attribution.enable({ log: false })` — on the observe build an unguarded `enable()` records in production; prefer the `/__solid/diagnostics` session (`begin` enables, `end` disables) so app code carries nothing |
 | `solid({ observe: true })` added "to see diagnostics in dev" | `vite dev` is always the dev build; `observe: true` is the production-observability opt-in (observe condition + `componentNames` for `vite build`/preview) |
 | `configureServerErrors({ onError: (e) => { report(e); return e; } })` | return nothing or a reference (`new Error(\`ref ${id}\`)`) — the return value replaces the sanitized wire value; the error itself leaks message/stack/secrets |
 | `import "./instrument"` at the top of the server entry for a monitoring SDK | `start: { instrument: "./src/instrument.ts" }` — ESM hoists static imports in dependency order, so the entry's own deps load first |
 | Express/middleware injecting `traceparent` / trace headers into responses | the runtime carries a sampled or provided trace on `Server-Timing` + `<meta>`; forward downstream with `getTraceContext()?.entries`; SDKs use `OBSERVE?.server.trace.provide` |
 | `OBSERVE.records.subscribe("call", (e) => setStats(...))` | listeners run synchronously inside the runtime and must not write signals; collect into a plain buffer and drain from outside |
-| `import { storePath } from "solid-js"` | gone from `solid-js` (rc.9); write draft setters `setState((d) => { d.user.name = "Grace"; })` |
+| `import { storePath } from "solid-js"` | gone from `solid-js` (rc.9); write draft setters `setState((d) => { d.user.name = "Grace"; })` <!-- upstream:store-path-removed --> |
 | `<meta name="description" content="...">` hardcoded in the document shell | `<Meta>` from `@solidjs/meta`. A static `<title>` is the fallback; other hardcoded tags coexist with the registry |
 | `useHead({ tag: "meta", ... })` for ordinary page tags | `<Title>` / `<Meta>` / `<Script>` (JSON-LD). `useHead` is the lower-level registry |
 | two `<Meta property="og:image">` meant as one replacement set | wrap them in `<Head>` — a later group replaces the earlier set as one unit |
@@ -1866,19 +1919,19 @@ how to reuse. Prefer the form on the right.
 | `fetch('/api')` at component-body top level | `createMemo(async () => { ... fetch ... })` under `<Loading>` — a top-level fetch runs once at mount and is not a reactive source |
 | `<input type="checkbox" value={on()} />` | `checked={on()}` for the toggle; `value="string"` only when grouping radios or listing submitted values |
 | `createMemo(() => { void save(); return x(); })` / an effect that calls an action | invoke actions from handlers, not from memos or effects |
-| `createSignal(props.value)` / `createStore(props.items)` | `createSignal(() => props.value)` / `createStore(() => props.items, fallback)` — a bare `props.x` at setup is a snapshot |
-| `createRenderEffect` / `createTrackedEffect` as the default effect | two-phase `createEffect(compute, apply)` |
+| `createSignal(props.value)` / `createStore(props.items)` | `createSignal(() => props.value)` / `createStore(() => props.items, fallback)` — a bare `props.x` at setup is a snapshot. That form resets on every prop change; an intentional one-time read (an `initialCount` prop) is `createSignal(untrack(() => props.initialCount))` |
+| `createRenderEffect` / `createTrackedEffect` as the default effect | two-phase `createEffect(compute, apply)`; `createTrackedEffect` is `@deprecated` (rc.9) <!-- upstream:tracked-effect-deprecated --> |
 | `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 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 |
+| `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 <!-- upstream:optimistic-value-overlay --> |
 | 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 |
 | router/server mutation, then `fetch` / `onSettled` / `hydrate` to refresh the page | `reload` / `revalidate` / single-flight (the mutation response can seed destination preloads). In-flight Promises serialize as Promises; `live()` continues from HTML |
 | delay `renderToStream` so HTML arrives in visual order | stream as soon as ready; `<Reveal collapsed>` controls when content *appears* |
 | subscribe/unsubscribe in the component around `live()` | `createMemo(() => stockPrice(props.symbol))` — hoist that memo to share one connection. `onstatus` is on the iterable the `live()` call returns, not on the memo. Until the first yield, `<Loading>`; later yields are updates |
-| a Solid adapter / custom Worker / Express bridge, or `entry-client.tsx` under `start: true` | With a server bundle: `handleRequest` from `dist/server/server.js` / Fetchable `fetch`; platform plugins adopt it. Node: template `server.js`. Client-only start: static `dist/client`. Middleware is `start: { middleware: "..." }`, not Express `app.use` |
+| a Solid adapter / custom Worker / Express bridge, or `entry-client.tsx` under `start: true` | With a server bundle: `handleRequest` from `dist/server/server.js` / Fetchable `fetch`; platform plugins adopt it. Node: `start: { node: true }` → `node dist/server/node.js` (its `listener` for an existing Express / Fastify app). Client-only start: static `dist/client`. Middleware is `start: { middleware: "..." }`, not Express `app.use` |
 | `createMemo(async () => (await props.story).author)` | `createMemo(() => props.story.author)` — a derivation over an async value becomes async; no await, no Promise type |
 | return a component from `"use server"` / flip `serverFunctions.components` | experimental preview — do not enable unless the project already has that flag |
 
@@ -2017,7 +2070,8 @@ always-applied rules installed alongside this skill.
       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()!`.
+      ternary/`<Show>`; no `{list().map(...)}` in JSX; no `key` props (except
+      `@solidjs/meta` tags); no `value()!`.
 - [ ] Effects are two-phase and only at imperative boundaries; apply does not read stores.
 - [ ] Async reads sit under `<Loading>` (the data slot, not chrome); errors under `<Errored>`.
       Reactive inputs of an async memo are read before the first `await`. No hand-rolled
@@ -2028,7 +2082,7 @@ always-applied rules installed alongside this skill.
       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
+      `configureServerErrors` (or `render(fn, root, undefined, { 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
       setters + `action` + server functions): do not rewrite App with
@@ -2046,8 +2100,8 @@ always-applied rules installed alongside this skill.
 - [ ] 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`, ...).
-      No `JSX` imported from `solid-js` — children/return types are `Element` from
-      `solid-js`; DOM `JSX` types come from `@solidjs/web`.
+      No `JSX` imported from `solid-js` — markup types are `JSX.Element` from
+      `@solidjs/web` or `Element` from `solid-js` (aliased next to DOM code).
 - [ ] 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` (components) / `ssrSource`
@@ -2058,7 +2112,8 @@ always-applied rules installed alongside this skill.
       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
+      body level (no `[ASYNC_STORE_SETTER]` <!-- upstream:async-store-setter-throws --> /
+      `[REACTIVE_WRITE_IN_OWNED_SCOPE]` <!-- upstream:store-write-owned-scope -->), held
       writes paired with `isPending` / `latest` / optimistic values / `affects()`
       (no `[SILENT_HOLD]`). Attribution-only costs
       (`[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`, `[EFFECT_*]`)

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

@@ -14,6 +14,32 @@ exist when a project has routing, server functions, or document head tags.
 It is not every Advanced reference page. When an API is missing here, look it up
 in `llms.txt` rather than guessing from Solid 1.x or React.
 
+## Read before using
+
+The skill does not cover these; fetch the pages when the task needs them.
+
+- Filesystem routing (`fileRoutes({ types: true })` from `filesystem-routing/vite`, `[id]` / `[[p]]` / `[...rest]` / `(group)/` names, `defineFileRoute`): https://v2-rebuild--solid-docs-v2.netlify.app/reference/filesystem-routing.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/filesystem-routing/vite.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/filesystem-routing/conventions.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/filesystem-routing/manifest.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/filesystem.md
+- A route array in its own file (`defineRoutes`, `RouteProps<typeof Router.paths.x>`, `matchFilters`): 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
+- Layout routes, pathless routes, where router hooks may run: https://v2-rebuild--solid-docs-v2.netlify.app/routing/solid-router/nested-routes.md
+- Auth guards and redirect-after-sign-in (`next` validation): https://v2-rebuild--solid-docs-v2.netlify.app/guides/protected-routes.md
+- Unsaved-changes guard (`useBeforeLeave`): https://v2-rebuild--solid-docs-v2.netlify.app/routing/solid-router/navigation.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/navigation.md
+- Row selection without `createSelector` (id-keyed projection): https://v2-rebuild--solid-docs-v2.netlify.app/guides/lists.md, https://v2-rebuild--solid-docs-v2.netlify.app/guides/performance.md
+- Infinite scroll, polling, sharing one request: https://v2-rebuild--solid-docs-v2.netlify.app/guides/data-fetching-patterns.md
+- Writing a custom primitive (called under an owner, `MaybeAccessor`, `getOwner` / `runWithOwner` / `isDisposed` after async): https://v2-rebuild--solid-docs-v2.netlify.app/guides/custom-primitives.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/owner-introspection/get-owner.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/owner-introspection/run-with-owner.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/owner-introspection/is-disposed.md
+- Wrapping a non-Solid library, push feeds with a reactive argument, web components (`prop:`, event names): https://v2-rebuild--solid-docs-v2.netlify.app/guides/integrate-non-solid-code.md
+- Typed env (`env.ts` schema, `VITE_` client keys), `import "server-only"`, what compiles `"use server"`: https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/environment.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/vite-plugin-solid/modules.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/vite-plugin-solid/server-functions.md
+- Sessions and cookies (`parseCookieHeader` / `serializeCookie`, `RequestEventLocals` typing, when a cookie write commits): https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/sessions-and-auth.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/cookies.md
+- Middleware chains and API routes / webhooks (`createAPIHandler`, `httpMethods: true`): https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/middleware-and-api-routes.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/filesystem-routing/api.md
+- Auth headers for every call, per-call `signal` / `keepalive` (`configureServerFunctionsClient`, `invoke`): https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/server-functions/metadata-and-transport.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/server-functions/configure-client.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/server-functions/invoke.md
+- Server-function limits (`bodySizeLimit`, `maxArguments`): https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/server-functions/host-configuration.md
+- Static prerendering (`prerender-crawler/vite`, `prerendered()`), choosing client / SSR / prerender: https://v2-rebuild--solid-docs-v2.netlify.app/guides/choose-a-rendering-mode.md
+- SSR-safe code (what runs on the server, hydration mismatches): https://v2-rebuild--solid-docs-v2.netlify.app/guides/ssr-safe-code.md
+- Type helpers (`VoidProps`, `FlowProps`, `ComponentProps<"button">`, `JSX.EventHandler`, generic `<T,>` components): https://v2-rebuild--solid-docs-v2.netlify.app/guides/typescript.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/types/component-types.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/types/reactive-types.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/types/jsx-types.md
+- Head tag identity (OG `property`, `key`, layout `<Head>` groups): https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/head-and-metadata.md
+- Server-side tests (`createRequestEvent`, `provideRequestEvent` from `@solidjs/web/storage`, a Node Vitest project): https://v2-rebuild--solid-docs-v2.netlify.app/guides/testing.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/provide-request-event.md
+- Migrating 1.x data fetching (`createResource`, `resource.latest`): https://v2-rebuild--solid-docs-v2.netlify.app/migration/data-fetching-from-solid-1.md
+- Terms used across the docs: https://v2-rebuild--solid-docs-v2.netlify.app/glossary.md; the mental model: https://v2-rebuild--solid-docs-v2.netlify.app/guides/thinking-in-solid.md
+
 ## Getting started
 
 - https://v2-rebuild--solid-docs-v2.netlify.app/getting-started/quick-start.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.15.0",
+  "version": "0.17.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",
@@ -16,7 +16,8 @@
   ],
   "scripts": {
     "check:drift": "node scripts/check-docs-drift.mjs",
-    "test": "node tests/check.test.mjs && node tests/hook.test.mjs && node tests/doctor.test.mjs && node tests/init.test.mjs"
+    "check:upstream": "node scripts/check-upstream.mjs",
+    "test": "node tests/check.test.mjs && node tests/hook.test.mjs && node tests/doctor.test.mjs && node tests/init.test.mjs && node tests/upstream.test.mjs"
   },
   "engines": {
     "node": ">=18"