solid2-agent-kit 0.16.0 → 0.18.0

package/README.md

@@ -20,7 +20,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
 | Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
 | Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |
-| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a Solid 1.x line of `solid-js` / `@solidjs/router` / `@solidjs/meta` / `@tanstack/solid-router` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router'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) |
+| 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`), a Solid 2 prerelease older than the kit's baseline in `bin/baseline.mjs` (`@solidjs/web` / `@solidjs/signals` / `@solidjs/diagnostics` `latest` is an older rc than `next`), `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
 | Review command | `.cursor/commands/solid2-review.md` | `.claude/commands/solid2-review.md` | `/solid2-review` — on-demand deep review: runs both gates, then walks the diff against the skill checklist targeting the semantic failure classes regexes cannot see (post-`await` reads, effect misuse, unkeyed server rows, boundary placement, context snapshots) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything
@@ -169,6 +169,7 @@ markdown with an `.md` suffix).
 
 ```
 bin/solid2-kit.mjs                 CLI: init / sync / check / doctor / hook
+bin/baseline.mjs                   Solid 2 versions the kit is verified against (doctor + check:upstream)
 files/shared/rules-body.md         hard rules (rendered into .mdc and CLAUDE.md)
 files/shared/agents-section.md     AGENTS.md managed-block content
 files/skills/solid-2/              SKILL.md + references/official-docs.md

package/bin/baseline.mjs

@@ -0,0 +1,41 @@
+// The Solid 2 releases the kit's guidance is verified against, shared by
+// `solid2-kit doctor` (a project on an older release is flagged) and
+// check:upstream (scripts/upstream-probes/registry.mjs: a newer release is
+// flagged). `line` is the major the kit targets: check:upstream installs the
+// newest dist-tagged version on it. `baseline` is the version every upstream
+// probe was verified against — bump it (and fix any marked claim that changed)
+// after re-verifying.
+//
+// npm dist-tags lag each other on these prereleases (@solidjs/web, @solidjs/signals
+// and @solidjs/diagnostics `latest` is an older 2.0 rc than `next`;
+// @solidjs/vite-plugin's `next` is behind `latest`), so a bare install can
+// resolve a release older than the baseline.
+export const BASELINE = {
+  'solid-js': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.9' },
+  '@solidjs/router': { line: 2, baseline: '2.0.0-next.27' },
+  '@solidjs/vite-plugin': { line: 3, baseline: '3.0.0-next.44' },
+  '@solidjs/testing-library': { line: 1, baseline: '1.0.0-beta.3' },
+};
+
+export function parseVersion(version) {
+  const [core, pre] = version.split('+')[0].split(/-(.*)/s);
+  return { core: core.split('.').map(Number), pre: pre ? pre.split('.') : [] };
+}
+
+// Semver precedence, prerelease-aware (2.0.0-rc.10 > 2.0.0-rc.9 < 2.0.0).
+export function compareVersions(a, b) {
+  const x = parseVersion(a);
+  const y = parseVersion(b);
+  for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
+  if (!x.pre.length || !y.pre.length) return y.pre.length - x.pre.length;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const [p, q] = [x.pre[i], y.pre[i]];
+    if (p === undefined || q === undefined) return p === undefined ? -1 : 1;
+    const numeric = /^\d+$/.test(p) && /^\d+$/.test(q);
+    if (p !== q) return numeric ? Number(p) - Number(q) : /^\d+$/.test(p) ? -1 : /^\d+$/.test(q) ? 1 : p < q ? -1 : 1;
+  }
+  return 0;
+}

package/bin/solid2-kit.mjs

@@ -24,6 +24,7 @@ import {
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { BASELINE, compareVersions } from './baseline.mjs';
 
 const KIT_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf8')).version;
@@ -273,7 +274,7 @@ function init() {
   if (hooksNote) console.log(`  note: ${hooksNote}`);
   if (!hasDiagnosticsDependency(target)) {
     console.log(
-      '  note: the solid-2 skill\'s development loop drives the dev server\'s /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).',
+      `  note: the solid-2 skill's development loop drives the dev server's /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies (install @solidjs/diagnostics@^${BASELINE['@solidjs/diagnostics'].baseline} — npm \`latest\` can be an older rc) so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).`,
     );
   }
 }
@@ -1221,9 +1222,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, @tanstack/solid-router 1.x):
-// a bare `pnpm add <name>` installs it. The Solid 2 releases are published
-// under `next` (TanStack: `rc`, 2.0.0-rc.x).
+// 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).' },
   {
@@ -1244,8 +1246,45 @@ const SOLID2_LINE_PACKAGES = [
     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).',
+  },
 ];
 
+// Packages doctor checks the version of: the Solid 1.x lines above, then any
+// release older than the kit's baseline (bin/baseline.mjs) — a bare
+// `npm i @solidjs/web` installs `latest`, 2.0.0-rc.0, which the current
+// @solidjs/vite-plugin's `@solidjs/web ^2.0.0-rc.9` peer rejects.
+const VERSION_CHECKED = [...new Set([...SOLID2_LINE_PACKAGES.map((p) => p.name), ...Object.keys(BASELINE)])];
+
+// The lower bound of a single-comparator range ("^2.0.0-rc.0", "~2.0.0-rc.8",
+// ">=2.0.0-rc.0", "2.0.0-rc.0") or an installed version. Dist-tags, "*",
+// unions and protocol specs have no bound to read; their install is checked.
+const LOWER_BOUND = /^\s*(?:[\^~]|>=|=)?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\s*$/;
+
+// `declared` ranges are judged by their floor: npm installs the `latest` tag
+// whenever it satisfies the range, so "^2.0.0-rc.0" resolves to rc.0 today.
+function versionProblem(name, version, declared) {
+  const line = SOLID2_LINE_PACKAGES.find((p) => p.name === name);
+  if (line?.solid1.test(version)) return `the Solid 1.x line; this kit teaches Solid 2.x. ${line.fix}`;
+  const baseline = BASELINE[name]?.baseline;
+  const lowest = version.match(LOWER_BOUND)?.[1];
+  if (baseline && lowest && compareVersions(lowest, baseline) < 0) {
+    const older = declared ? 'allows releases older than' : 'older than';
+    return `${older} ${baseline}, the release this kit's guidance is verified against (npm dist-tags lag on the Solid 2 prereleases, so a bare install can resolve an older one). Install ${name}@^${baseline}.`;
+  }
+  return null;
+}
+
 function installedVersion(target, name) {
   try {
     return JSON.parse(readFileSync(join(target, 'node_modules', name, 'package.json'), 'utf8')).version;
@@ -1270,21 +1309,19 @@ function doctorFindings(target) {
   for (const [name, message] of Object.entries(BANNED_DEPS)) {
     if (name in deps) report(`dep-${name.replace(/[@/]/g, '')}`, `package.json depends on "${name}". ${message}`);
   }
-  for (const { name, id, solid1, fix } of SOLID2_LINE_PACKAGES) {
+  for (const name of VERSION_CHECKED) {
+    const id = SOLID2_LINE_PACKAGES.find((p) => p.name === name)?.id ?? `${name.replace('@solidjs/', '')}-version`;
     const range = deps[name];
-    if (typeof range === 'string' && solid1.test(range)) {
-      report(id, `package.json pins ${name} "${range}" — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`);
+    if (typeof range !== 'string') continue;
+    const declared = versionProblem(name, range, true);
+    if (declared) {
+      report(id, `package.json pins ${name} "${range}" — ${declared}`);
       continue;
     }
-    // A range such as "latest" or "*" only shows its line once resolved.
-    if (range === undefined) continue;
+    // A range such as "latest" or "*" only shows its version once resolved.
     const installed = installedVersion(target, name);
-    if (installed && solid1.test(installed)) {
-      report(
-        id,
-        `node_modules has ${name} ${installed} (package.json: "${range}") — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`,
-      );
-    }
+    const resolved = installed && versionProblem(name, installed, false);
+    if (resolved) report(id, `node_modules has ${name} ${installed} (package.json: "${range}") — ${resolved}`);
   }
 
   for (const entry of readdirSync(target, { withFileTypes: true })) {

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
@@ -50,8 +50,9 @@ Steps:
      `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 — markup types are `JSX.Element` from `@solidjs/web` or `Element` from `solid-js` (alias it `SolidElement` next to DOM code). 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 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()`. 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.
@@ -87,7 +87,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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 `@deprecated` since 2.0.0-rc.9 (kept only for
-    1.x migration). Skip the initial run with `{ defer: true }`. Most React `useEffect` code should not become an effect at all — see the skill.
+    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
@@ -107,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)
@@ -137,7 +137,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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
@@ -290,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
@@ -360,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">`
@@ -402,7 +402,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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
@@ -438,7 +438,7 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     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`). Declare live reads as `live(GET(fn))` —
+    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
@@ -477,9 +477,9 @@ 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"` | `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 |
+| `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(...)`, `createTrackedEffect` (deprecated in 2.0) | `createEffect(compute, apply)`; deps belong in `compute`; one-time DOM work is `onSettled` |
+| `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>` |
@@ -493,7 +493,7 @@ 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"` |
@@ -513,4 +513,4 @@ Solid 1.x or React memory.
 `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,7 +69,7 @@ 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)`) |
@@ -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
@@ -261,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)
@@ -435,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,
@@ -511,7 +511,7 @@ Uncaught errors (`REACTIVITY_HALTED`) go to the platform's `reportError`, which
 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)
 
@@ -650,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
@@ -666,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
@@ -1016,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
@@ -1041,7 +1043,7 @@ write and `flush()`: `const { setA, b, dispose } = createRoot((dispose) => { …
 { 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).
+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`.
@@ -1068,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]`.
@@ -1086,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
@@ -1094,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
@@ -1177,7 +1179,8 @@ effects** — a pure markup or styling change does not need it.
 2. **Name the scopes you changed** (`createMemo(fn, { name: "total" })`,
    `createStore(v, { name: "cart" })`) so chains and tables refer to them by name.
 3. **Record the interaction and ask.** First choice — no app code — is the diagnostics
-   endpoint: with `@solidjs/diagnostics` in `devDependencies`, the Vite plugin's
+   endpoint: with `@solidjs/diagnostics` in `devDependencies` at the same version as
+   `solid-js` (npm `latest` can lag; `solid2-kit doctor` flags an older one), the Vite plugin's
    `diagnostics` option (auto-on when the package is declared; dev server only, never
    under vitest, `vite build`, or preview) injects the capture bridge and serves
    `/__solid/diagnostics`. `begin` enables attribution with `log: false` for the
@@ -1301,7 +1304,7 @@ 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). Markup types are `JSX.Element` from `@solidjs/web` (the
+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`.
 Import the latter as `import type { Element as SolidElement } from "solid-js"` in any file
@@ -1630,7 +1633,7 @@ 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
+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,
@@ -1641,7 +1644,8 @@ is success metadata a scripted caller unwraps. Arguments are JSON: send `Date` /
 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).
+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
@@ -1889,20 +1893,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 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())` |
-| `attribution.why(total)` / `attribution.format(e)` / `attribution.costs()` | named imports from `solid-js/attribution`: `why(total)`, `formatRerun(e)`, `costs()`, `feedback()`, `subscriptions(scope)` (rc.9) |
+| `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 |
@@ -1917,11 +1921,11 @@ how to reuse. Prefer the form on the right.
 | `<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. 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) |
+| `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 |
@@ -2109,7 +2113,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/package.json

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