solid2-agent-kit 0.4.2 → 0.4.4

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`, and `render(<App />)` (pass a function) |
 
 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 ? ... : ...`).

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. 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,35 @@ 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 `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 indicator). "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 +114,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 +125,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
@@ -143,10 +159,25 @@ 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`.
+    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.
 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,7 +186,20 @@ 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
+    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. Document head is
     `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`.
 
 ## Lint heritage: eslint-plugin-solid (Solid 1.x) intents carried into this file
@@ -208,7 +252,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 |

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

@@ -68,7 +68,7 @@ Most React `useEffect` code should NOT become `createEffect`:
 | 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` |
+| 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 +149,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 +198,8 @@ 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.
 
 ### Two-phase effect (imperative boundary only)
 
@@ -287,7 +289,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 +323,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 +395,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 +442,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 +497,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 +574,69 @@ 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()`. Replace SolidStart /
+Router 0.x leftovers: no `createAsync`, `useSubmission` (singular), `cache()`,
+router `json()`, or `<FileRoutes />` (`fileRoutes(pageRoutes)` instead).
 
 ### Server functions — `"use server"`
 
@@ -570,16 +649,22 @@ 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. `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
 
@@ -604,7 +689,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 +717,42 @@ 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 })` as the default first-flight UI | `<Loading>` for first flight; `loadingValue` is an escape hatch |
+| `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) |
 
 ```tsx
 // WRONG — post-await read never subscribes; production can hang pending
@@ -684,6 +805,43 @@ 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 — 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
@@ -725,7 +883,14 @@ 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(...)`).
 - [ ] `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,7 @@ 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
 
 ## Reference: components and JSX (solid-js)
 
@@ -113,6 +114,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,6 +137,7 @@ 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/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
@@ -145,6 +148,7 @@ 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/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

package/package.json

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