solid2-agent-kit 0.4.2 → 0.4.5

package/README.md

@@ -16,7 +16,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | Always-applied hard rules | `.cursor/rules/solid-2.mdc` (glob-attached to `*.tsx`/`*.jsx`) | managed block in `CLAUDE.md` | 23 hard rules + banned Solid 1.x API table + eslint-plugin-solid lint-heritage table. Injected without the agent having to decide to read anything |
 | Agent skill | `.cursor/skills/solid-2/` | `.claude/skills/solid-2/` | Execution-model primer, decision tables, canonical patterns, a “still runs / write the other form” table, review checklist, official-doc URL index |
 | Shared agent context | managed block in `AGENTS.md` | same (Claude Code users can reference it from `CLAUDE.md`) | Core principles and pointers, always in context |
-| Mechanical gate | `solid2-kit check` | same | Whole-file regex guard over `src/**/*.{ts,tsx}`: fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<HashRouter>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, and `=== undefined` readiness branches |
+| Mechanical gate | `solid2-kit check` | same | Whole-file regex guard over `src/**/*.{ts,tsx}`: 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), and `<Dynamic>` (use `dynamic()`) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything
 outside them is yours. Kit-owned files (`solid-2.mdc`, the skill directories) are overwritten
@@ -24,8 +24,8 @@ on sync.
 
 ## Usage
 
-GitHub is the canonical distribution channel (the kit is intentionally not published to
-npm; consumers pin a commit through their lockfile):
+GitHub is the canonical distribution channel (consumers pin a commit through their
+lockfile); the package is also published to npm as `solid2-agent-kit`:
 
 ```sh
 # install guidance for both Cursor and Claude Code (default)
@@ -55,8 +55,8 @@ resolve the project-local bin, so the bare name is safe there):
 ```
 
 Update later with `bun update solid2-agent-kit` (or the npm/pnpm equivalent) followed by
-`npx solid2-agent-kit sync`. Outside a project that has the kit installed, always use the
-`npx github:...` form — the bare package name is not claimed on the npm registry.
+`npx solid2-agent-kit sync`. Outside a project that has the kit installed, prefer the
+`npx github:...` form — it always tracks this repo directly.
 
 ## Why not eslint-plugin-solid?
 
@@ -96,6 +96,14 @@ scripts/check-docs-drift.mjs       weekly docs cross-check
 tests/                             mechanical-gate fixtures (`npm test`)
 ```
 
+## Publishing (npm)
+
+Bump `version` in `package.json` on `main` and CI publishes automatically
+(`.github/workflows/publish.yml`) — it skips when the version already exists on npm.
+Auth is npm Trusted Publishing (OIDC), so no NPM_TOKEN secret exists or is needed.
+One-time setup on npm: package → Settings → Trusted Publisher → GitHub Actions, owner
+`lightsound`, repo `solid2-agent-kit`, workflow `publish.yml`, environment left empty.
+
 ## License
 
 MIT

package/bin/solid2-kit.mjs

@@ -177,7 +177,7 @@ const CHECKS = [
   {
     id: 'react-hook',
     pattern:
-      /(?<![.\w])use(?:State|Effect|Memo|Ref|Callback|Reducer|LayoutEffect|Transition|SyncExternalStore|ImperativeHandle|Id|DeferredValue|InsertionEffect)\s*\(/g,
+      /(?<![.\w])use(?:State|Effect|Memo|Ref|Callback|Reducer|LayoutEffect|Transition|SyncExternalStore|ImperativeHandle|Id|DeferredValue|InsertionEffect|Optimistic|ActionState|FormStatus)\s*\(/g,
     message: 'React hook. See the primitive mapping in the solid-2 rules.',
   },
   {
@@ -281,15 +281,68 @@ const CHECKS = [
   },
   {
     id: 'solid1-router',
-    pattern: /<(?:HashRouter|MemoryRouter|Route|Navigate)\b/g,
+    pattern: /<(?:HashRouter|MemoryRouter|Route|Navigate|A|FileRoutes|StartClient|StartServer)\b/g,
     message:
-      'Solid Router 0.x/1.x JSX. Define routes with createRouter({ routes }) and plain <a href={Router.paths...}>.',
+      'Solid Router 0.x/1.x or SolidStart JSX. Define routes with createRouter({ routes }) / fileRoutes(pageRoutes) and plain <a href={Router.paths...}>.',
   },
   {
     id: 'meta-provider',
     pattern: /<MetaProvider\b/g,
     message: 'Solid Meta 1.x has no provider. Render <Title>/<Meta>/<Link> from "@solidjs/meta" anywhere.',
   },
+  {
+    id: 'solidstart-import',
+    pattern: /from\s+['"](?:@solidjs\/start|vinxi|h3|nitropack)(?:['"]|\/)/g,
+    message:
+      'SolidStart leftover. Import GET from "@solidjs/web/server-functions"; routes are createRouter / fileRoutes(pageRoutes), not @solidjs/start, vinxi, h3, or nitropack.',
+  },
+  {
+    id: 'solidstart-api',
+    pattern: /(?<![.\w])(?:createAsync|createAsyncStore|useSubmission|defineEventHandler)\s*\(/g,
+    message:
+      'SolidStart / Router 0.x leftover. Read query() through createMemo(() => getUser(id())); settled results via useSubmissions (plural); replace cache()/json() with query/respond; rewrite H3 handlers against Request/Response.',
+  },
+  {
+    id: 'use-client',
+    pattern: /['"]use client['"]/g,
+    message: 'React/Next client directive. Solid has no "use client"; server functions use "use server" only.',
+  },
+  {
+    id: 'next-import',
+    pattern: /from\s+['"]next(?:['"]|\/)/g,
+    message: 'Next.js import in a Solid 2.0 codebase. Use @solidjs/router, @solidjs/meta, and @solidjs/web.',
+  },
+  {
+    id: 'render-jsx-element',
+    pattern: /\b(?:render|hydrate|renderToString|renderToStream)\(\s*</g,
+    message:
+      'Pass a function to render/hydrate/renderToString/renderToStream so Solid creates the root first: render(() => <App />, root).',
+  },
+  {
+    id: 'typeof-window',
+    pattern: /typeof\s+window\b/g,
+    message:
+      '`typeof window` is not the SSR boundary. Use isServer / isDev from "@solidjs/web", or clientOnly(() => import("./Widget")).',
+  },
+  {
+    id: 'next-nav',
+    pattern:
+      /(?<![.\w])(?:useRouter|usePathname|revalidatePath|revalidateTag|notFound|hydrateRoot)\s*\(/g,
+    message:
+      'Next.js / React DOM leftover. In-app navigation is useNavigate / <a href={Router.paths...}>; 404 is httpStatus(404); hydrate is hydrate(() => <App />, root).',
+  },
+  {
+    id: 'react-dom-event',
+    pattern: /\b(?:onDoubleClick|onKeyPress|suppressHydrationWarning)=/g,
+    message:
+      'React DOM prop. Native dblclick is onDblClick; keypress is onKeyDown; Solid has no suppressHydrationWarning.',
+  },
+  {
+    id: 'history-nav',
+    pattern: /\b(?:history\.pushState|history\.replaceState|window\.location\.href\s*=)/g,
+    message:
+      'Bypass of the router. In-app navigation is useNavigate() or <a href={Router.paths...}>.',
+  },
   {
     // A zero-arg call compared against undefined/null is a manual async
     // readiness branch (`data() === undefined ? ... : ...`).
@@ -298,6 +351,20 @@ const CHECKS = [
     message:
       'Readiness branch on a zero-arg call. Read async values under <Loading> (first load) / isPending() (refetch) and let errors reach <Errored>. For non-reactive utils, assign to a variable and test that.',
   },
+  {
+    // `isPending(user())` / `latest(data())` evaluate the read before the
+    // helper runs. `isPending(user)` and `isPending(() => user())` do not match.
+    id: 'pending-accessor-call',
+    pattern: /(?<![.\w])(?:isPending|latest)\(\s*[A-Za-z_$][\w$]*\(\s*\)/g,
+    message:
+      'Pass the accessor to isPending/latest, not the call: isPending(user), not isPending(user()). Calling it first evaluates the read before the helper runs.',
+  },
+  {
+    id: 'dynamic-jsx',
+    pattern: /<Dynamic[\s/>]/g,
+    message:
+      '`<Dynamic>` is a JSX convenience wrapper. Application code should use dynamic(() => ...) from "@solidjs/web" so the component identity stays stable.',
+  },
 ];
 
 // .ts / .tsx sources, excluding .d.ts declaration files.

package/files/shared/agents-section.md

@@ -3,4 +3,4 @@
 - All TSX in this project is Solid 2.0. Components run **once**; reactivity flows through signals/stores to JSX. React patterns (props destructuring, `className`, per-keystroke `onChange`, state-synced-by-effect, `.map()` lists) and Solid 1.x APIs (`createResource`, `onMount`, `solid-js/store`, `Suspense`, path setters) are bugs here.
 - Before writing TSX, read the `solid-2` skill (`.cursor/skills/solid-2/SKILL.md` for Cursor, `.claude/skills/solid-2/SKILL.md` for Claude Code): patterns, decision tables, official doc URLs. Hard rules auto-attach from `.cursor/rules/solid-2.mdc` in Cursor and live in a managed block in `CLAUDE.md` for Claude Code.
 - 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`. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
-- 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>`.
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`.

package/files/shared/rules-body.md

@@ -33,8 +33,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    as an updater.
 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" : ""}`}` works but rebuilds the whole
-    string, so Solid cannot add/remove one token. `style` objects use CSS property names
+    names in an object — `class={`btn ${on() ? "on" : ""}`}`, `clsx(...)`, and
+    `.filter(Boolean).join(" ")` all work but rebuild the whole string, so Solid cannot
+    add/remove one token. `style` objects use CSS property names
     (`"background-color"`, not `backgroundColor`) and numbers do NOT auto-append `px`
     (`width: `${n}px``).
 6. **`onInput` for per-keystroke handling.** Solid's `onChange` is the native change event
@@ -77,23 +78,39 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     accessor) only when that identity change should show the fallback again. Pass an async
     memo to a child as the **accessor** (`user={user}`), and read `props.user()` under that
     child's `<Loading>` — `user={user()}` throws not-ready at the parent, so the child's
-    boundary never sees it. "Prop with local edits" = writable derivation:
+    boundary never sees it. Do not start `fetch` (or any request) at component-body top
+    level — that runs once at mount and is not a reactive source. Do not `try/catch` `NotReadyError` around a read, and do not
+    use `loadingValue` / `seedLoadingValue` as the default first-flight UI — those skip
+    `<Loading>`. `{latest(() => x())}` is a preview, not the visible answer. `isPending`
+    is the *refetch* indicator after a settled answer exists — do not use it as the
+    first-load spinner (`<Loading>` owns that). Pass the accessor: `isPending(user)`,
+    not `isPending(user())` (that evaluates the read before `isPending` runs).
+    "Prop with local edits" = writable derivation:
     `createSignal(() => props.value)` or `createStore(() => props.value, fallback)`.
+    `createOptimistic` is for an in-flight mutation, not a local editing session.
 11. Context: the context object is the provider — `<MyContext value={{ theme, setTheme }}>`
     (no `.Provider`). Pass accessors/setters/stores through context, never snapshot values.
     `createContext<T>()` without a default throws when read outside a provider (good) — use
     that for any reactive payload. `createContext("light")` is only for a primitive static
     fallback; a dummy default on a store/signal context *runs* and then silently no-ops
-    without a provider.
+    without a provider. Truly app-wide singletons (theme, session, locale) are a
+    **module-level** signal/store — Context is subtree scoping, not a React-style
+    app store. Module state is shared across SSR requests.
 12. Refs: `let el!: HTMLDivElement` + `ref={el}` or `ref={(node) => (el = node)}`, or forward
     `props.ref`. Compose with arrays: `ref={[props.ref, (node) => (el = node)]}`. No
     `useRef`/`.current`. Ref callbacks run untracked and **without an owner**; their
     return values are ignored. Do not create effects or register cleanup inside a ref
     callback. For reusable directives, create owned primitives (`onSettled`) in a
-    factory and return only the element callback.
+    factory and return only the element callback. Component setup/teardown is
+    `onSettled(() => { ...; return cleanup })` — `onCleanup` is for custom
+    primitives and captured owners, not component bodies. Each `onSettled`
+    registers a **single** fire (reads inside are untracked); ongoing
+    imperative work is `createEffect`.
 13. **Writes are staged** and commit on the next microtask. Event handlers need nothing
     special; tests and imperative integration code must call `flush()` before observing
-    updated state or DOM. Never call `flush()` inside an `action`.
+    updated *synchronous* state or DOM. Waiting on an async memo is
+    `await resolve(() => value())` (or Testing Library async queries), not `flush()`.
+    Never call `flush()` inside an `action`.
 14. Do not port these React tools — they have no Solid equivalent because the problems they
     solve don't exist: `useCallback`, `React.memo`, `forwardRef`, `useSyncExternalStore`,
     dependency arrays, `startTransition`/`useTransition` (updates are held and coordinated
@@ -101,7 +118,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
 15. **Components return once.** Never early-return or conditionally return based on reactive
     values — the branch is chosen once at setup and frozen forever. Put conditionals inside
     JSX (`<Show>`, ternary, `<Switch>`/`<Match>`). Early returns on genuinely non-reactive
-    values (build-time config, missing env) are fine.
+    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
     `dangerouslySetInnerHTML`, and never combine `innerHTML` with JSX children (they fight
@@ -111,6 +129,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     **narrowed accessor**, so no `!` is needed:
     `<Show when={error()}>{(err) => <p>{err().message}</p>}</Show>`. For non-reactive
     zero-arg calls, use an explicit guard variable instead of `!`.
+    Do not add `keyed` by default (the React `key` reflex) — default `Show`/`Match`
+    keep children mounted; `keyed` remounts when identity changes.
     Mechanically enforced by `solid2-kit check`.
 18. **Never hand-roll async UI state.** No `[loading, setLoading]` signals, no
     `data() === undefined` readiness branches, no `{ data, error }` signal pairs from
@@ -123,7 +143,11 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     counter/version signal read inside the computation. Input-driven refetch is automatic
     (tracked inputs re-run the computation) and subscriptions push. Legit uses: after a
     mutation inside an `action`, and explicit reload buttons. Pair with `affects(source)`
-    when the reload should present as pending.
+    when the reload should present as pending — a bare `refresh()` re-asks quietly.
+    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
+    data. Do not mix them.
 20. **External collections flow into stores through reconciliation.** First choice:
     function-form `createStore(() => source, fallback)` / `createProjection` (reconcile
     automatically, keyed by `"id"`). Manual merge: `setStore(reconcile(fresh, "id"))` or
@@ -143,10 +167,29 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
     Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`). Server vs browser:
     `isServer` / `isDev` from `@solidjs/web`, or `clientOnly(() => import("./Widget"))` for
-    browser-only components — never `typeof window` as the SSR boundary. `JSON.stringify(store)`
+    browser-only components — never `typeof window` as the SSR boundary. 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.
+    Pass a **function** to `render` / `hydrate` / `renderToString` / `renderToStream`
+    (`render(() => <App />, root)`), never `render(<App />, root)`. `hydrate` when the
+    container already holds SSR HTML; `render` for an empty mount. `renderToString`
+    emits `<Loading>` fallbacks; async or lazy-route trees need
+    `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`).
+    When the app owns the document, emit `<HydrationScript />` once before app markup;
+    extra roots get a distinct `renderId`. Import `GET` from
+    `@solidjs/web/server-functions`, never `@solidjs/start`. `httpStatus` /
+    `httpHeader` are scope *declarations* (call them bare in a component or
+    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`.
+    reads, or stream with `renderToStream`. `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
+    read above the portal. Navigation-shaped updates (a setter, then async computeds holding previous values)
+    do not need core `action` — reach for it only when writes happen *after* async work.
+    Invoke actions from handlers, not from memos or effects.
 23. **Composition.** Pass `props.children` through when you only render them. Inspect or
     iterate children with `children(() => props.children)` (then `.toArray()`), never a
     setup-time snapshot. Code-split with `lazy(() => import("./X"))` under `<Loading>` —
@@ -155,8 +198,30 @@ 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). If the project has `@solidjs/router`, routes are `createRouter({ routes })`
-    at module scope — not JSX `<Route>` / `<A>` / `<HashRouter>`. Document head is
-    `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`.
+    at module scope — not JSX `<Route>` / `<A>` / `<HashRouter>`. That package's `action` /
+    `query` are URL-addressable POST forms and a read cache — not core `action` /
+    `refresh` from `solid-js`. Router mutations: `<form action={save} method="post">`
+    (POST only; `.with(id)` binds args into the URL). `useAction` is JS-only. Cache
+    reads: `query(fn, "name")` then `createMemo(() => getUser(id()))`; after a mutation
+    `revalidate(getUser.key)`. Do not wrap mutations in `query` (an undeclared server
+    function becomes GET). `Router.paths` is not the current location (`useLocation` /
+    `useParams`); a route `preload` result is `props.data`. One router instance —
+    Solid Router does not support nested `<Router>` / nested `createRouter`.
+    In-app navigation is `useNavigate` or `<a href={Router.paths...}>`, not
+    `window.location` / `history.pushState`. Trusted identity is
+    `getRequestEvent()`, never a caller-supplied user id. Unscripted forms use
+    the function `.url` (or a router `action`), not a hand-built `/_server/`
+    path. Client history adapters do not select the SSR URL — pass
+    `<Router url={request.url}>` (or rely on the request event). Secrets belong in
+    `virtual:env/server`, never the `client` env map / `import.meta.env`. Document head is
+    `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`. A static
+    `<title>` in the document shell is the fallback; do not hardcode other tags
+    (`<meta name="description">`) that Solid Meta should manage.
+    Return `respond(value, { status })` from a `"use server"` function, not
+    `Response.json` — a raw `Response` is HTTP-handler control flow; scripted
+    callers should receive the value. JSON-encodable server-function arguments
+    only, unless `enableRichArguments()` was called once in the client entry
+    (`Date` / `Map` / `Set` throw without it).
 
 ## Lint heritage: eslint-plugin-solid (Solid 1.x) intents carried into this file
 
@@ -208,7 +273,10 @@ directory (default `src/`).
 | `renderToStringAsync(...)` | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`) |
 | `clearDelegatedEvents` | delete — delegated listeners are scoped to each render root |
 | `vite-plugin-solid` / `jsxImportSource: "solid-js"` | `@solidjs/vite-plugin` / `"jsxImportSource": "@solidjs/web"` |
-| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` | `createRouter({ routes })`, plain `<a href={Router.paths...}>`, `hashHistory()` |
+| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` / `<FileRoutes>` | `createRouter({ routes })`, `fileRoutes(pageRoutes)`, plain `<a href={Router.paths...}>`, `hashHistory()` |
+| `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 |
 | `resource.loading` / `resource.error` | `<Loading>` boundary / `<Errored>` boundary |
@@ -217,6 +285,7 @@ When unsure about any API, verify against the official Solid 2.0 docs — fetcha
 listed in `references/official-docs.md` next to the `solid-2` skill. Do not guess from
 Solid 1.x or React memory.
 
-`createTrackedEffect` and `storePath` exist in Solid 2 but are not defaults: use two-phase
-`createEffect` unless a single tracked callback is required, and draft setters instead of
-`storePath` except while converting 1.x path setters.
+`createTrackedEffect`, `createRenderEffect`, and `storePath` exist in Solid 2 but
+are not defaults: use two-phase `createEffect` unless a single tracked callback is
+required, and draft setters instead of `storePath` except while converting 1.x
+path setters.

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

@@ -67,8 +67,9 @@ 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) |
-| Browser-only widget (charts, maps, `window`) | `clientOnly(() => import("./Chart"))` from `@solidjs/web` |
+| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; prefer over `<Dynamic>`) |
+| Overlay / modal | `<Portal>` — hoist async reads *above* the portal (reads inside start on the client) |
+| Browser-only widget (charts, maps, `window`) | `clientOnly(() => import("./Chart"))` from `@solidjs/web` (`{ lazy: true }` defers the import until first render) |
 | Server vs browser branch | `isServer` / `isDev` from `@solidjs/web` (build-time constants), not `typeof window` |
 | SSR-stable `id` / `for` / `aria-*` pairing | `createUniqueId()` |
 
@@ -149,7 +150,8 @@ the component must **inspect or iterate** them. It returns an accessor with
 `.toArray()`. The helper call belongs in the component body; the read of
 `props.children` is inside the accessor (a tracking scope), so this is not a
 setup-time snapshot. Do not assign `const kids = props.children` and do not
-treat resolved children as a reactive data list for `<For>`:
+treat resolved children as a reactive data list for `<For>` —
+render `{resolved.toArray()}`, not `<For each={resolved()}>`:
 
 ```tsx
 import { children, type ParentProps } from 'solid-js';
@@ -197,7 +199,9 @@ const Result = dynamic(() => (detailed() ? Detailed : Compact));
 
 `dynamic()` returns a **stable** component whose source can be a component, an
 intrinsic tag name, a promise, or empty. Prefer it over swapping a component
-variable in JSX. `<Dynamic>` is the JSX spelling of the same primitive.
+variable in JSX (`const View = tab() ? A : B` freezes the choice at setup).
+`<Dynamic>` is the JSX spelling of the same primitive; application code should
+use `dynamic()` so the component identity stays stable.
 
 ### Two-phase effect (imperative boundary only)
 
@@ -243,15 +247,18 @@ return (
   where the memo was created, and not of page chrome (header/nav) that should stay mounted.
   Boundary placement is purely a UX decision — it does not change when fetches start
   (no waterfalls: nested components set up and fetch in parallel). After first paint the
-  boundary keeps settled content during refetch; `isPending(() => results())` is the
+  boundary keeps settled content during refetch; `isPending(results)` (pass the accessor,
+  not `isPending(results())`) is the
   indicator. Use `on={query()}` (the **value**, not the accessor `on={query}`) only when
   that identity should put the fallback back on screen.
+  Do not use `isPending` as the first-load spinner.
 - Read every reactive input **before the first `await`** in an async computation. A read
   after `await` does not subscribe; production can sit pending with no retry.
 - `<Errored>` function fallbacks receive an error **accessor** and a `reset` callback:
   `fallback={(error, reset) => ...}`.
-- Refetch: `refresh(results)`. In-flight indicator: `isPending(() => results())`.
-  Freshest in-flight value for imperative code: `latest(results)`.
+- Refetch: `refresh(results)`. In-flight indicator: `isPending(results)` (or
+  `isPending(() => results())`). Freshest in-flight value for a preview:
+  `latest(results)`. Do not start `fetch` at component-body top level.
 - Coordinate reveal order of sibling `<Loading>` boundaries with `<Reveal order="sequential" | "together" | "natural">`.
 
 **Never hand-roll these states.** No `[loading, setLoading]` signal, no
@@ -287,7 +294,8 @@ function createSubscriptionQuery<T>(
   const queue: T[] = [];
   let failure: unknown;
   let wake = () => {};
-  // Component-owned setup: unsubscribe is tied to the caller's owner.
+  // Custom primitive: unsubscribe is tied to the caller's owner via onCleanup.
+  // Component bodies use onSettled and return cleanup instead.
   onCleanup(subscribe(
     (value) => { queue.push(value); wake(); },
     (error) => { failure = error; wake(); },
@@ -320,11 +328,23 @@ const addTodo = action(function* (todo: Todo) {
 
 Ordinary signal/store writes inside an action are held until it settles. Never call
 `flush()` inside an action. Invoke actions from handlers, not from component/computation bodies.
+Do not set a `submitted` signal and watch it from an effect — that work belongs in the
+handler or the `action`.
+
+`createOptimistic` / `createOptimisticStore` are for a tentative value during an
+active mutation, not a local editing session (use a writable derivation or a plain
+store for that).
 
 **`yield`, not a bare `await`, is the transaction boundary.** `await api.save()` then
 `setTodos(...)` *runs*, but the write commits immediately and optimistic rollback is lost.
 Either `yield saveTodo(todo)` or, when you need a typed result, `const saved = await api.save(); yield; setTodos(...)`.
 
+Navigation-shaped updates do **not** need core `action`. A plain setter is enough:
+reads pull the async, and downstream async computeds hold previous values until the
+new ones are ready (`isPending` / `latest`). Reach for `action` from `solid-js` only
+when writes happen *after* async work. Router form `action` from `@solidjs/router` is
+a different API (URL + POST) — see [App stack](#app-stack-only-if-the-project-has-these-packages).
+
 ### Lists: `<For>` child signatures per keying mode
 
 ```tsx
@@ -380,7 +400,8 @@ Plain ternaries remain fine when no narrowing is involved (`{open() ? <A /> : <B
 Default `Show` keeps children mounted across truthy changes. Add `keyed` to remount when the
 value's identity changes (child then receives the raw value, like React's `key` reset).
 Prefer the default; use `keyed` only when internal state must reset. Multi-branch:
-`<Switch>` / `<Match>`.
+`<Switch>` / `<Match>` — **first truthy `<Match>` wins**; later matches are skipped,
+even if they are also truthy.
 
 Components must **return once**: never early-return based on a reactive value — the branch
 is picked at setup and frozen. Early returns on non-reactive values (build-time config, a
@@ -426,7 +447,9 @@ function ThemeButton() {
 
 Pass accessors/setters/stores through context — never `value={theme()}` (a dead snapshot).
 No `useMemo` for the value object, no context splitting: the object is created once and
-fine-grained updates flow through the signals inside it.
+fine-grained updates flow through the signals inside it. Context is **subtree scoping**.
+A true app-wide singleton (theme, session, locale) is a module-level signal/store —
+do not invent a root provider for that. Module state is shared across SSR requests.
 
 ### Refs
 
@@ -479,7 +502,9 @@ expect(count()).toBe(2);
 ```
 
 Wait for an async expression to settle in tests: `await resolve(() => value())`.
-Run tests in dev mode first — Solid 2 emits diagnostics for top-level reactive reads,
+`flush()` only drains staged **synchronous** writes — it is not a stand-in for waiting
+on a pending resource. `onSettled` is also a **single** fire (untracked): it is not
+`onMount` that re-runs, and it is not an effect. Run tests in dev mode first — Solid 2 emits diagnostics for top-level reactive reads,
 writes from owned scopes, and async reads outside `<Loading>`. Fix them; don't suppress.
 
 Component tests use `@solidjs/testing-library`. Pass a **function** to `render` so
@@ -554,10 +579,72 @@ export default function App() {
 ```
 
 Create the instance at **module scope**. Nested layouts are `children` arrays
-on the route objects, not nested `<Route>` / nested routers. Navigate with
+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
 plain `<a href={Router.paths.about}>` (or `useNavigate`); there is no `<A>` /
-`<Navigate>` / `<HashRouter>`. Session location is `useLocation` / `useParams`,
-not `Router.paths`. One router per app.
+`<Navigate>` / `<HashRouter>` / `<FileRoutes />`. Do not assign
+`window.location.href` or call `history.pushState` for in-app navigation.
+Session location is `useLocation` / `useParams`,
+not `Router.paths`. A route `preload` result is `props.data` on the matched
+component (and the factory `preload` result is the root render prop's `props.data`).
+Link warming: `preload="false"` skips that link's *data* preload; `preloadLinks: false`
+disables automatic link preloading. Intent values are `"initial"` / `"navigate"` /
+`"native"` / `"preload"`. One router per app.
+
+**Two different `action`s.** Core `action` from `solid-js` is a generator transaction
+(optimistic writes that span an async gap). Router `action` from `@solidjs/router` is
+a URL-addressable POST mutation (`useSubmissions`, `<form action={save} method="post">`).
+Do not import one and use it as the other.
+
+```tsx
+import { action } from '@solidjs/router';
+import { redirect } from '@solidjs/web';
+
+const save = action(async (form: FormData) => {
+  await saveProfile(form);
+  return redirect('/account');
+}, 'update-profile');
+
+<form action={save} method="post">
+  <input name="displayName" />
+  <button type="submit">Save</button>
+</form>
+```
+
+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.
+
+**`query` is the read cache** (optional, only with the router). Wrap a read,
+give it a stable name, and consume it through a Solid async primitive:
+
+```tsx
+import { createMemo } from 'solid-js';
+import { query, revalidate } from '@solidjs/router';
+
+export const getUser = query(async (id: string) => {
+  const response = await fetch(`/api/users/${id}`);
+  return response.json();
+}, 'users');
+
+const user = createMemo(() => getUser(params.id));
+// after a mutation:
+revalidate(getUser.key);
+revalidate(getUser.keyFor('42'));
+```
+
+A bare `createMemo(async () => fetchUser(id()))` still works; it just has no
+shared cache, no preload reuse, and no `revalidate`. Do not wrap mutations in
+`query` — wrapping an undeclared server function makes it GET. `query.get(key)`
+throws if there is no entry; `query.set` does not accept a promise. Cache is
+request-scoped on the server and application-scoped in the browser. After a
+router mutation, `revalidate(...)` — not core `refresh()`, and not
+`reload()` (that is a *server-function return* that asks the integration to
+refresh cached data: `return reload({ revalidate: "todos" })`). `live()` sources
+update through the open stream; do not `revalidate` them. Replace SolidStart /
+Router 0.x leftovers: no `createAsync`, `useSubmission` (singular), `cache()`,
+router `json()`, or `<FileRoutes />` (`fileRoutes(pageRoutes)` instead).
 
 ### Server functions — `"use server"`
 
@@ -570,16 +657,26 @@ export async function findUser(id: string) {
 ```
 
 A function-level server function cannot close over component locals — pass
-values as arguments. Treat every argument as untrusted. During SSR the same
+values as arguments. Treat every argument as untrusted. Read trusted identity
+from `getRequestEvent()`, never from a caller-supplied user id. During SSR the same
 reference runs in-process; in the browser it is HTTP. Mutations that should
 revalidate: `redirect` / `reload` from `@solidjs/web` (see the server-function
 guides). For 404 during SSR: `httpStatus(404)` from `@solidjs/web`.
 `throw new Error("…")` is stripped to `"Internal Server Error"` in production —
 use `markSafeError` or `respond(..., { status })` for intentional client-facing
-failures. `GET()` is only for idempotent reads (URLs leak into logs/history).
+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).
+`GET()` is only for idempotent reads (URLs leak into logs/history);
+import it from `@solidjs/web/server-functions`, never `@solidjs/start`.
 `live()` yields **current state** (each yield replaces the last); do not treat
 it as an append-only event log, and hoist the memo so consumers share one
 connection.
+Unscripted forms: `<form method="post" action={createTodo.url}>` (the reference
+`.url`), not a client `preventDefault` + `fetch`, and not a hand-built
+`/_server/` URL. GET forms (`method="get" action={search.url}`) are only for
+idempotent search — do not use a GET form for a mutation.
 
 ### Document head — no MetaProvider
 
@@ -591,8 +688,12 @@ import { Title, Link, Meta } from '@solidjs/meta';
 ```
 
 Solid Meta 1.x has **no provider**. Render tags anywhere; later wins, unmount
-restores. `useHead` from `@solidjs/web` is the lower-level registry. Do not
-hardcode a second `<title>` in the document shell.
+restores. `useHead` from `@solidjs/web` is the lower-level registry — prefer
+`<Title>` / `<Meta>` / `<Script>` (JSON-LD) for application metadata. Several
+tags that should swap as one unit belong in `<Head>`. A static `<title>`
+in the document shell is the fallback when no `<Title>` is mounted; do not
+hardcode a second `<meta name="description">` (the registry leaves foreign tags
+alone, so both would coexist). Do not hardcode a second `<title>` in the document shell.
 
 ## These still run — write the other form
 
@@ -604,7 +705,7 @@ how to reuse. Prefer the form on the right.
 |---|---|
 | `{todos().map((t) => <Row todo={t} />)}` | `<For each={todos()} keyed={(t) => t.id}>` |
 | `<For each={todos().map(t => t)}>` | derive first, then `<For each={visible()}>` |
-| `class={`btn ${on() ? "on" : ""}`}` | `class={["btn", { on: on() }]}` |
+| `class={`btn ${on() ? "on" : ""}`}` / `clsx("btn", on() && "on")` / `.filter(Boolean).join(" ")` | `class={["btn", { on: on() }]}` |
 | `style={{ width: 80 }}` (no unit) | `style={{ width: `${80}px` }}` |
 | `const rest = { ...props }` | `const rest = omit(props, "label")` |
 | `const user = createMemo(async () => { await fetch(...); return id(); })` | read `id()` **before** `await` |
@@ -632,6 +733,63 @@ how to reuse. Prefer the form on the right.
 | `live()` yields as an event log to append | each yield **replaces** the current answer; yield current state first |
 | `<article innerHTML={html()}>…children…</article>` | `innerHTML` **or** children, not both |
 | `fallback={(error) => <p>{error.message}</p>}` | `error` is an accessor: `error().message` (or `String(error())`) |
+| `import { action } from "solid-js"` on a `<form>` | `import { action } from "@solidjs/router"` + `<form action={save} method="post">` (core `action` is a generator transaction, not a form URL) |
+| `createMemo(async () => fetchUser(id()))` when `@solidjs/router` is present | `query(fetchUser, "users")` + `createMemo(() => getUser(id()))`; after mutations `revalidate(getUser.key)`, not core `refresh()` |
+| `onSubmit={(e) => { e.preventDefault(); fetch(...) }}` for a router/server action | `<form action={save} method="post">` (POST only; `.with(id)` binds args into the URL). `useAction` is JS-only |
+| `query(saveUser, "users")` wrapping a mutation | don't wrap mutations in `query` — an undeclared server function becomes GET |
+| `render(<App />, root)` / Testing Library `render(<Counter />)` | `render(() => <App />, root)` — pass a function so Solid creates the root first |
+| `render` onto SSR HTML / `hydrate` into an empty node | `hydrate(() => <App />, root)` when HTML already exists; `render` for an empty mount |
+| `renderToString(() => <App />)` for an async or lazy-route tree | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`). String render emits `<Loading>` fallbacks |
+| `clientOnly(() => import("./Map"))` for a rarely shown widget | same + `{ lazy: true }` so the import waits until first render (default starts at declaration) |
+| `<NoHydration><Chart /></NoHydration>` to skip SSR of a widget | `clientOnly(() => import("./Chart"))` — `NoHydration`/`Hydration` split ownership, they do not choose visible content |
+| `await flush()` / `flush()` to wait on a pending memo | `await resolve(() => value())` (or Testing Library async queries); `flush()` only drains staged *sync* writes |
+| `action(function* () { setX(v); })` around a navigation-shaped setter | plain setter; async computeds hold previous values. Core `action` only when writes happen *after* async work |
+| `createContext` + a root provider for a true app singleton | module-level signal/store (SSR: shared across requests). Context is subtree scoping |
+| `import { GET } from "@solidjs/start"` / `createAsync` / `useSubmission` / `<FileRoutes />` / `"use client"` | `GET` from `@solidjs/web/server-functions`; `createMemo(() => getUser(id()))`; `useSubmissions`; `fileRoutes(pageRoutes)`; Solid has no `"use client"` |
+| `<Show keyed when={user()}>` by default | default `Show` (keeps children mounted); `keyed` only when internal state must reset |
+| overlapping truthy `<Match>`es all expected to render | first truthy `<Match>` wins; later matches are skipped |
+| missing `<HydrationScript />` / one script for many roots | once, before app markup, when the app owns the document; distinct `renderId` per extra root |
+| `Router.paths` as the current URL; calling `preload()` and using the return as props | `useLocation` / `useParams`; factory/route `preload` result is `props.data` |
+| `query.get(key)` with no guaranteed entry; `query.set(key, promise)` | `query.get` throws if missing; `query.set` does not accept a promise |
+| `onCleanup(() => ...)` in a component body | `onSettled(() => { ...; return cleanup })` — `onCleanup` is for custom primitives |
+| `onSettled` with reactive reads expecting re-runs | each call is a **single** fire; reads are untracked. Ongoing work is `createEffect` |
+| `<Router>` nested inside `<Router>` | one instance; nest `children` arrays (or a lazy children thunk) |
+| `const View = tab() ? A : B; return <View />` | `const View = dynamic(() => (tab() ? A : B))` — the ternary at setup freezes the choice |
+| `<For each={resolved()}>` after `children()` | `{resolved.toArray()}` — resolved children are not a reactive data list |
+| `<input onChange={...}>` for keystrokes | `onInput` — native `onChange` is blur/commit |
+| `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` |
+| `action={"/_server/" + id}` in app JSX | `action={createTodo.url}` or a router `action` |
+| `<form method="get" action={update.url}>` for a mutation | GET forms only for idempotent search; mutations are POST |
+| `window.location.href = ...` / `history.pushState` | `useNavigate()` or `<a href={Router.paths...}>` |
+| `httpStatus(404)` in a click handler | call it bare in the component / error-fallback body (a scope declaration, not a mutation) |
+| `try { user() } catch (e) { /* NotReadyError */ }` | `<Loading>` — app code should not catch `NotReadyError` |
+| `{latest(() => results())}` as the visible list | settled read + `isPending()` for the indicator; `latest` is for previews |
+| `typeof window !== "undefined"` | `isServer` / `isDev` from `@solidjs/web` |
+| `Object.assign({}, props)` / expecting `merge` to skip `undefined` like 1.x `mergeProps` | `omit` / `merge` — explicit `undefined` **overrides** (Object.assign) |
+| `isPending(user())` / `latest(user())` | `isPending(user)` / `latest(user)` — pass the accessor (or `() => user()`). Calling it first evaluates the read before the helper runs |
+| `isPending(...)` as the first-load spinner | `<Loading>` owns first flight; `isPending` is the *refetch* indicator after a settled answer exists |
+| `refresh(getUser.key)` / `revalidate(user)` / `return refresh()` from `"use server"` | three APIs: core `refresh(source)` reruns a reactive source; router `revalidate(getUser.key)` invalidates the query cache; `return reload({ revalidate: "todos" })` asks the integration to refresh cached data |
+| `revalidate(liveSource)` | `live()` updates through the open stream; do not revalidate it |
+| `refresh(user)` without `affects` when the reload should look pending | pair `affects(user)` with `refresh(user)` — a bare `refresh` re-asks quietly |
+| `<Dynamic component={tab() ? A : B} />` | `const View = dynamic(() => (tab() ? A : B))` — `<Dynamic>` is a JSX convenience; app code should use `dynamic()` for stable identity |
+| `<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 |
+| `createRoot(() => ...)` inside a component | let `render` / the component owner own the scope. `createRoot` is for tests, libraries, and non-render entry points |
+| `JSON.stringify(store)` / `structuredClone(store)` | `snapshot(store)` — proxies throw or leak reactivity |
+| `import { env } from "virtual:env/client"` (or `import.meta.env`) for a signing secret | `import { env } from "virtual:env/server"` — client map values are public |
+| `renderToStream(...).pipe(res)` and also `.readable` / `await` on the same result | exactly one consumer: `pipe` / `pipeTo` / `readable` / await |
+| `return Response.json(user, { status: 201 })` from `"use server"` | `return respond(user, { status: 201 })` — scripted callers receive `user`, not a `Response` |
+| `<Portal>{user().name}</Portal>` for an async read | hoist the read above the portal (children start on the client); async UI inside one wants its own `<Loading>` |
+| a client history adapter to pick the SSR location | `<Router url={request.url}>` (or the request event). Client adapters do not select the server URL |
+| `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)` |
 
 ```tsx
 // WRONG — post-await read never subscribes; production can hang pending
@@ -684,6 +842,53 @@ function Page() {
 }
 ```
 
+```tsx
+// WRONG — two different `action`s; the core one is not a form URL
+import { action } from 'solid-js';
+const save = action(async function* (form: FormData) {
+  yield persist(form);
+});
+<form onSubmit={(e) => { e.preventDefault(); void save(new FormData(e.currentTarget)); }}>
+  <button type="submit">Save</button>
+</form>
+
+// CORRECT — router action is POST-addressable (only if `@solidjs/router` is in the project)
+import { action } from '@solidjs/router';
+const save = action(async (form: FormData) => persist(form), 'save');
+<form action={save} method="post">
+  <button type="submit">Save</button>
+</form>
+```
+
+```tsx
+// WRONG — evaluating JSX before the root exists
+import { render } from '@solidjs/web';
+render(<App />, document.getElementById('app')!);
+
+// CORRECT
+render(() => <App />, document.getElementById('app')!);
+```
+
+```tsx
+// WRONG — user() runs before isPending, so the helper never sees the accessor
+<article aria-busy={isPending(user())}>{user().name}</article>
+
+// CORRECT — pass the accessor (or () => user()); <Loading> still owns first flight
+<Loading fallback={<p>Loading…</p>}>
+  <article aria-busy={isPending(user) ? 'true' : 'false'}>{user().name}</article>
+</Loading>
+```
+
+```tsx
+// WRONG — tab() is read once at setup; View never changes
+const View = tab() ? Detailed : Compact;
+return <View value="now" />;
+
+// CORRECT
+const View = dynamic(() => (tab() ? Detailed : Compact));
+return <View value="now" />;
+```
+
 ## Checking the official docs
 
 Solid 2.0 docs: https://v2.solidjs.com/ — the site blocks non-browser fetchers, so from an
@@ -714,8 +919,10 @@ always-applied rules installed alongside this skill.
 - [ ] 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
-      `loading`/`error` signals or `=== undefined` readiness branches; refetch via
-      `refresh`, not counter signals.
+      `loading`/`error` signals or `=== undefined` readiness branches. First load is
+      `<Loading>`; refetch indicator is `isPending(user)` (the accessor, not `user()`).
+      Core `refresh(source)`, router `revalidate(key)`, and `return reload(...)` are
+      different APIs — do not mix them.
 - [ ] External collections reconcile into stores (function-form `createStore` /
       `reconcile`), never wholesale draft assignment or `setTodos((t) => t.filter(...))`
       as the identity-preserving update.
@@ -725,7 +932,16 @@ always-applied rules installed alongside this skill.
 - [ ] Inspect children with `children()`; code-split with `lazy` + `<Loading>`; reactive
       component choice with `dynamic()`. No `React.lazy`, no effects inside ref callbacks.
 - [ ] Browser-only code uses `isServer` / `clientOnly`, not `typeof window`.
+      Component teardown is `onSettled` (return cleanup), not `onCleanup`.
 - [ ] If the project has a router: `createRouter({ routes })`, not JSX `<Route>` / `<A>`.
+      One instance, no nested `<Router>`. Navigate with `useNavigate` / `<a href>`, not
+      `window.location`. Router `action`/`query` come from `@solidjs/router` (POST forms + cache), not
+      core `action`/`refresh`. Forms: `<form action={save} method="post">`.
+- [ ] `render(() => <App />, root)` — a function, not `render(<App />)`. `hydrate` when
+      HTML already exists. Stream async/lazy trees (`await renderToStream(...)`) with
+      exactly one consumer (`pipe` / `pipeTo` / `readable`). Snapshot stores with
+      `snapshot(store)`, not `JSON.stringify`. Secrets live in `virtual:env/server`.
 - [ ] `jsxImportSource` is `@solidjs/web`; Vite plugin is `@solidjs/vite-plugin`.
+      No `@solidjs/start`, `vinxi`, `"use client"`, or Next.js imports.
 - [ ] Single return per component; no early returns on reactive conditions.
 - [ ] `solid2-kit check` and the project's typecheck pass.

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

@@ -98,6 +98,8 @@ read these before writing route JSX.
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/affects.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/on-settled.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/lifecycle-actions/refresh.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/specialized-reactivity/on-cleanup.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/store-advanced/snapshot.md
 
 ## Reference: components and JSX (solid-js)
 
@@ -113,6 +115,7 @@ read these before writing route JSX.
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/components-context/children.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/components-context/lazy.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/components-context/create-unique-id.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/manual-hydration/no-hydration.md
 
 ## Reference: @solidjs/web
 
@@ -135,9 +138,13 @@ read these before writing route JSX.
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/jsx-properties/text-content.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/jsx-properties/inner-html.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/server-functions.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/server-functions/get.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/server-functions/rich-arguments.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/get-request-event.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/redirect.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/reload.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/respond.md
 
 ## Reference: @solidjs/router, @solidjs/meta, @solidjs/vite-plugin
 
@@ -145,9 +152,12 @@ read these before writing route JSX.
 - 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/navigation.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/data.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/history.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-router/filesystem.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-meta/title.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-meta/meta.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-meta/link.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-meta/script.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-meta/head.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/vite-plugin-solid.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/vite-plugin-solid/options.md

package/package.json

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