solid2-agent-kit 0.12.0 → 0.14.0

package/bin/solid2-kit.mjs

@@ -270,6 +270,26 @@ function init() {
   console.log(`solid2-agent-kit v${VERSION} — installed for ${[wantCursor && 'Cursor', wantClaude && 'Claude Code'].filter(Boolean).join(' + ')}:`);
   for (const path of written.filter(Boolean)) console.log(`  ${relative(target, path) || '.'}`);
   if (hooksNote) console.log(`  note: ${hooksNote}`);
+  if (!hasDiagnosticsDependency(target)) {
+    console.log(
+      '  note: the solid-2 skill\'s development loop drives the dev server\'s /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).',
+    );
+  }
+}
+
+// Whether the consuming project declares @solidjs/diagnostics — the signal
+// @solidjs/vite-plugin uses to auto-enable the diagnostics endpoint. An
+// informational note only: `doctor` does not fail without it.
+function hasDiagnosticsDependency(target) {
+  const filePath = join(target, 'package.json');
+  if (!existsSync(filePath)) return true;
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return true;
+  }
+  return '@solidjs/diagnostics' in { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.optionalDependencies };
 }
 
 // --- check ------------------------------------------------------------------

package/files/commands/solid2-review.md

@@ -34,6 +34,9 @@ Steps:
      `[ASYNC_STORE_SETTER]`), store setters called at component-body top level, and
      `latest()` used as a null-safe read of an unsettled source;
    - nested fetches assumed to waterfall, or `<Loading>` lifted along with a lifted fetch;
+   - mutations on a value read through `live()` that settle on `yield save()` alone or
+     `refresh()` the live-derived store, instead of `yield until(predicate, { timeout })`
+     for the stream's echo (the old value flashes back when the overlay drops);
    - rewriting App with loading/error branches, or snapshot/restore, when wrapping
      a client store in server functions; disabling optimistic rows until ack;
    - tRPC / type-gen around `"use server"`, a client `fetch` after a mutation,
@@ -57,7 +60,14 @@ Steps:
      attribution-only store/list/effect costs) left unaddressed;
    - context values passed as snapshots instead of accessors/setters/stores;
    - components with conditional/early returns on reactive values.
-5. Verify any API you are not certain about against the official docs mirror
+5. If the change set touches stores, lists, async computations, actions, or effects, run
+   the skill's development loop against the dev server: `/__solid/diagnostics` `begin` →
+   exercise the changed UI → `whyDidRun` for the changed scopes / `costs` → `end`
+   (`@solidjs/diagnostics` installed), or an `isDev`-guarded
+   `attribution.enable({ log: false })` + `why()` / `costs()` / `feedback()`. Report
+   every coded warning, the silent holds in `feedback().sources`, and the top
+   `costs().scopes` entries as findings.
+6. Verify any API you are not certain about against the official docs mirror
    (`https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt`); never trust Solid 1.x or
    React memory.
 

package/files/shared/agents-section.md

@@ -5,4 +5,4 @@
 - After editing TSX, run the `solid2-kit check` mechanical gate — it fails on React/Solid 1.x tokens and props destructuring. Use the project's `lint:solid` script if one exists; otherwise `npx solid2-agent-kit check` (with the kit as a devDependency) or `npx github:lightsound/solid2-agent-kit check`. An edit-time hook may also run this gate automatically after each file edit — treat its findings as errors to fix immediately, not warnings. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
 - After editing `package.json`, `tsconfig*.json`, or root config files (Vite, ESLint), run `solid2-kit doctor` — it fails on React/Solid 1.x wiring: `react`/`vite-plugin-solid`/`eslint-plugin-solid`/SolidStart dependencies, 1.x `solid-js` ranges, and `jsx`/`jsxImportSource` values other than `preserve`/`@solidjs/web`.
 - The kit's guidance and gate files (`.cursor/rules/solid-2.mdc`, the `solid-2` skill directories, hook entries, managed blocks in this file and `CLAUDE.md`) are guardrails, not obstacles. Never edit, weaken, bypass, or delete them to make a failure go away — fix the flagged code. If a guardrail seems wrong, stop and tell the user.
-- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource` on the memo/signal/derived store (`client`/`hybrid`), not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Fire-and-forget confirmations wait with `yield until(predicate, {timeout})`. Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or `render(..., { onError })`), not a side effect inside `<Errored fallback>`. `<Dynamic>` is deprecated — use `dynamic()`.
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource` on the memo/signal/derived store (`client`/`hybrid`), not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or `render(..., { onError })`), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.

package/files/shared/rules-body.md

@@ -129,7 +129,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     Granularity is the expression (`isPending(() => item.quantity)` with
     `affects(item, "quantity")`). A hold with no feedback at all is `[SILENT_HOLD]`
     under attribution — always pair a held write with one of these questions, an
-    optimistic value, or `affects()`.
+    optimistic value, or `affects()`. When a change touches stores, lists, async,
+    actions, or effects, run the skill's development loop before finishing: dev console
+    free of `[CODE]` findings, then an attribution session (`/__solid/diagnostics`
+    `begin` → interact → `whyDidRun` / `costs` → `end`, or `isDev`-guarded
+    `attribution.enable({ log: false })`). `vite dev` is always the dev build;
+    `solid({ observe: true })` is the production-observability opt-in, not a dev step.
     "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.
@@ -191,6 +196,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     failures no global handler sees reach `configureClientErrors({ onError })` from
     `solid-js` (or `render(..., { onError })` per root) and `configureServerErrors({ onError })`
     from `@solidjs/web` — do not call `captureException` inside `<Errored fallback>`.
+    The server hook's return value replaces the sanitized error on the wire: return
+    nothing or a reference id, never the error itself (message/stack/secrets would
+    reach the browser).
     Making a client store "real" is additive: same setters, wrap mutations in
     `action`, swap `createOptimisticStore` and a file of server functions — do
     not rewrite `App.tsx` with loading/error branches.
@@ -234,9 +242,16 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `pending` on the record rather than a second copy of state. Do not snapshot
     and restore, disable optimistic rows until ack, mutex rapid clicks, or freeze
     unrelated writes because one action is in flight; failed-action replay is
-    optional. Fire-and-forget confirmations wait with `yield until(predicate,
-    { timeout })` — the predicate reads authoritative state. Except reactive clients (e.g. Convex) whose subscriptions already push authoritative
-    state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
+    optional. Confirmations that arrive on another channel wait with `yield until(predicate,
+    { timeout })` — the predicate reads authoritative state, so the overlay cannot satisfy it.
+    That covers fire-and-forget sends **and** request/response mutations whose result is
+    read through a `live()` source: `live()` takes no part in revalidation or single-flight,
+    so after `yield save()` alone the overlay drops before the stream echoes the write and
+    the old value flashes back. Follow it with `yield until(...)`, not `refresh(liveStore)`
+    (that re-runs the derivation — the stream closes and the source reconnects — so each
+    mutation costs a reconnect, and the flash remains whenever the new connection's first
+    value predates the write). Skip `until` only for reactive clients (e.g. Convex)
+    whose subscriptions already carry the write when the mutation resolves. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
     Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`) — run `solid2-kit doctor`
     after touching `package.json` / tsconfig / root configs; it fails on React and Solid 1.x
     wiring. Server vs browser:
@@ -338,7 +353,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     components from `"use server"` unless the project already enabled the
     experimental `serverFunctions.components` flag. JSON-encodable server-function arguments
     only, unless `enableRichArguments()` was called once in the client entry
-    (`Date` / `Map` / `Set` throw without it). `live()` connection state is
+    (`Date` / `Map` / `Set` throw without it). Declare live reads as `live(GET(fn))` —
+    `live()` outermost. A plain `async function*` server function is an event stream on
+    one connection (no reconnect when it drops); `live()` is one value that changes over
+    time and reconnects. `live()` connection state is
     `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`), never a
     field in the yielded value. Sibling `<Loading>` reveal order is `<Reveal>`
     (`collapsed` suppresses tail skeletons under sequential order).

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

@@ -429,11 +429,31 @@ import { configureServerErrors } from '@solidjs/web';
 configureClientErrors({
   onError: (error, { ownerPath, boundaryPath }) => report(error, { ownerPath, boundaryPath }),
 });
-// server side (SSR renders and server functions); its return value, if any, is the
-// sanitized value the client receives instead of the original error
-configureServerErrors({ onError: (error, { kind, handling }) => report(error, { kind, handling }) });
+// server side (SSR renders and server functions); runs inside the request scope, so
+// getRequestEvent() works here. Return nothing, or a reference the user can quote —
+// NEVER the error itself: the return value replaces the sanitized value on the wire
+configureServerErrors({
+  onError(error, { kind, handling, ownerPath, boundaryPath, functionId, direct }) {
+    const ref = report(error, { site: `${kind}/${handling}`, ownerPath, boundaryPath, functionId, direct });
+    return new Error(`Something went wrong (ref ${ref})`);
+  },
+});
 ```
 
+**The server hook's return value goes on the wire.** What the client normally receives
+is the runtime's sanitized value (a generic `Error` outside the dev build). Returning
+the error object hands its `message`, stack, and whatever secret they carry to the
+browser. `kind`/`handling` name the road: `render` / `fallback` (an `<Errored>`
+rendered), `render` / `client` (a `<Loading>` fragment rejected, client re-renders),
+`render` / `failed` (request fails; return ignored), `render` / `serialize` (a
+hydration value would not serialize), `server-function` / `thrown` (`direct: true` for
+an in-process call during SSR), `server-function` / `channel` (a rejection or throw
+escaping through the result graph — a promise, an iterable, or a stream — after the
+head committed). A monitoring SDK's `init()` that
+registers this hook must load before the server graph — put it in the plugin's
+`start: { instrument: "./src/instrument.ts" }`, not at the top of an entry (see
+[Production observability](#production-observability-the-observe-build)).
+
 `render` / `hydrate` accept a per-root `onError` that wins over the ambient hook.
 Uncaught errors (`REACTIVITY_HALTED`) go to the platform's `reportError`, which every
 monitor already listens on — do not report them twice. `renderToStream` /
@@ -612,6 +632,38 @@ only the echo can. Timeout rejects with `TimeoutError` (strongly recommended on
 droppable transports; abort via `signal`). Outside actions, `await until(() => user())`
 waits for a value before continuing.
 
+The same hold applies when the mutation *does* answer but the value is read through a
+`live()` source. A live source updates only through its open stream — it takes no part
+in revalidation or single-flight mutation data — so the mutation's response and the
+stream's echo race. Settle on `yield saveBid(...)` alone and the overlay is discarded
+first: the old bid flashes back until the stream catches up.
+
+```tsx
+import { action, createOptimisticStore, until } from 'solid-js';
+import { liveAuction, saveBid } from '../data/auction';
+
+function Auction(props: { id: string }) {
+  const [auction, setAuction] = createOptimisticStore(() => liveAuction(props.id), { highBid: 0 });
+
+  const bid = action(function* (amount: number) {
+    setAuction((a) => { a.highBid = amount; });                    // overlay
+    yield saveBid(props.id, amount);                                 // the write goes up
+    yield until(() => auction.highBid >= amount, { timeout: 10_000 }); // hold for the echo
+  });
+
+  return <button onClick={() => bid(auction.highBid + 1)}>Bid {auction.highBid + 1}</button>;
+}
+```
+
+Do not `refresh(auction)` in place of `until`: on a store derived from a live source it
+re-runs the derivation — the current stream is closed and `liveAuction()` opens a new
+connection. That costs a reconnect per mutation and hides the flash only when the new
+connection's first value already includes the write; when the read side lags the write,
+the old value still flashes back before the echo. Reactive clients whose
+subscriptions already carry the write when the mutation resolves (e.g. Convex) need
+neither. The server side of `liveAuction` / `saveBid` is in
+[Server functions](#server-functions--use-server).
+
 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
@@ -850,8 +902,20 @@ an agent sneaks in fails the suite instead of scrolling by.
 
 ### Dev diagnostics and attribution
 
-Diagnostics come in two layers, both dev-build only (production strips them and `DEV`
-is `undefined` there). Always-on findings include misplaced reads
+Solid ships **three builds** of every runtime package, selected by export condition:
+
+| Build | Condition | Carries | `OBSERVE` | `DEV` |
+|---|---|---|---|---|
+| prod | default | the runtime + the two error hooks | `undefined` | `undefined` |
+| observe | `observe` | prod + records channel, diagnostics channel, attribution slot, server trace slot; no console output, no checks | object | `undefined` |
+| dev | `development` | observe + the development checks and the console reporter; unminified | object | object |
+
+`vite dev` is **always the dev build** (the `development` condition wins), so everything
+below works there with no configuration. The observe build is a *production* opt-in —
+see [Production observability](#production-observability-the-observe-build) — not a
+dev setting. Diagnostics come in two layers: **findings** (facts about a render, present
+in observe and dev) and **checks** (dev-only guidance printed by the console reporter).
+Always-on dev checks include misplaced reads
 (`[STRICT_READ_UNTRACKED]`, `[PENDING_ASYNC_UNTRACKED_READ]`), misplaced writes
 (`[REACTIVE_WRITE_IN_OWNED_SCOPE]` — since rc.9 also for store setters called in a
 component or root body, `[ASYNC_STORE_SETTER]` for a store setter callback that returns
@@ -873,8 +937,11 @@ Cost and responsiveness findings need the opt-in attribution engine, which recor
 every scope that re-ran, what changed to cause it, and how long it took. Since
 `solid-js` 2.0.0-rc.8 the engine lives behind its own subpath — `DEV.attribution`
 no longer exists (it is a type error; `DEV` holds only devtools hooks, graph
-traversal, and console reporting), and the low-level hook slot on `OBSERVE` is for
-engines and devtools, not app code. Since 2.0.0-rc.9 the folds, queries, and
+traversal, and console reporting). `OBSERVE` is the public observability surface on
+the observe and dev builds — `OBSERVE.records`, `OBSERVE.diagnostics`,
+`OBSERVE.exclude`, `OBSERVE.server.trace` are for app and tool code; only the
+`OBSERVE.attribution` hook slot (`install` / `withInteraction` / `withOrigin`) belongs
+to engines, routers, and devtools. Since 2.0.0-rc.9 the folds, queries, and
 formatters are **named exports** of that subpath, not methods of `attribution`
 (`attribution.why` / `.costs` / `.feedback` / `.subscriptions` / `.format` are type
 errors); `attribution` keeps `enable`, `disable`, `subscribe`, `markFlight`, and the
@@ -895,11 +962,15 @@ for (const event of why(total)) {
 (`log: true`); pass `{ log: false }` when you only want the coded findings and plan
 to query the tables yourself. Name the scopes you intend to interrogate
 (`createMemo(..., { name: "total" })`) — chains refer to nodes by name, and
-anonymous nodes print as `computed` / `effect` / `signal`. In production the import
-resolves to an inert same-surface twin whose `enable()` is a no-op, so
-with the `isDev` guard the cost is zero and the import can stay in the code. The
-split is pay-for-use: importing `costs` or `feedback` is what turns their tables on,
-so a records-only consumer (`attribution.subscribe(...)`) ships neither.
+anonymous nodes print as `computed` / `effect` / `signal`; component labels
+(`<Checkout>`) are always present under `vite dev` and survive minification only with
+the compiler's `componentNames` option (`solid({ observe: true })` turns it on). On the
+**prod build** the import resolves to an inert same-surface twin whose `enable()` is a
+no-op, so the import can stay in the code. On the **observe build** it is the real
+engine and an unguarded `enable()` records in production — keep the `isDev` guard
+unless recording in production is the intent. The split is pay-for-use: importing
+`costs` or `feedback` is what turns their tables on, so a records-only consumer
+(`attribution.subscribe(...)`) ships neither.
 
 While attribution is enabled, Solid also warns on its own about over-subscription,
 chained async waterfalls (`[ASYNC_WATERFALL]`), memos whose fresh-but-equal output
@@ -910,7 +981,10 @@ row-rebuilding lists (`[UNSTABLE_LIST_IDENTITY]` — key by id or reconcile into
 store), and silent holds (`[SILENT_HOLD]` — a write held on async work with no
 `isPending()` / `latest()` reader, optimistic value, `affects()` mark, or effect that
 ran while held; info from 100ms, warning from 200ms, tunable via
-`enable({ holds: { infoMs, warnMs } })`). `costs()`, `feedback()` (named imports), and
+`enable({ holds: { infoMs, warnMs } })`). A hold that *was* acknowledged but still ran
+long is `[LONG_HOLD]` (info from 500ms, warning from 1000ms;
+`enable({ longHolds: { infoMs, warnMs } })`) — the suggestion is a `<Loading on={...}>`
+boundary, never removing the hold. `costs()`, `feedback()` (named imports), and
 `attribution.holds()` rank the session worst-first; `attribution.waterfalls()`,
 `attribution.navigations()`, and `attribution.interactions()` hold the fact tables
 behind the verdicts.
@@ -920,6 +994,7 @@ against what it uses.
 For regression tests, `@solidjs/diagnostics` turns the same channels into assertions:
 
 ```ts
+import '@solidjs/diagnostics/vitest'; // registers the matchers (or list it in vitest `setupFiles`)
 import { captureArtifact } from '@solidjs/diagnostics';
 
 const { artifact } = await captureArtifact(() => {
@@ -939,22 +1014,113 @@ verification loops: capture until the channel is quiet, scenario budgets as the
 definition of done, and hold/latency gates. See the debugging-reactivity guide in
 [references/official-docs.md](references/official-docs.md).
 
-With `@solidjs/diagnostics` in `devDependencies`, the Vite plugin's `diagnostics`
-option (auto-on; dev server only) injects the capture bridge and serves
-`POST /__solid/diagnostics`, so a live page can be interrogated with curl alone —
-no test harness:
-
-```sh
-curl -X POST localhost:3000/__solid/diagnostics -d '{"method":"begin"}'
-# ... interact with the app in the browser ...
-curl -X POST localhost:3000/__solid/diagnostics -d '{"method":"whyDidRun","params":{"name":"TodoRow"}}'
-curl -X POST localhost:3000/__solid/diagnostics -d '{"method":"costs"}'
-curl -X POST localhost:3000/__solid/diagnostics -d '{"method":"feedback"}'
-curl -X POST localhost:3000/__solid/diagnostics -d '{"method":"end"}'
+### Development loop: self-diagnose before finishing
+
+Enable observability in development **by default** and lean on it. The dev build
+already prints every check; the attribution engine is the part you turn on. Run the
+loop whenever a change touches **stores, lists, async computations, actions, or
+effects** — a pure markup or styling change does not need it.
+
+1. **Dev console is clean.** Reproduce the change in `vite dev`; zero `[CODE]` entries
+   is the bar (`[STRICT_READ_UNTRACKED]`, `[REACTIVE_WRITE_IN_OWNED_SCOPE]`,
+   `[ASYNC_STORE_SETTER]`, `[ASYNC_OUTSIDE_LOADING_BOUNDARY]`, …). Fix, do not silence.
+2. **Name the scopes you changed** (`createMemo(fn, { name: "total" })`,
+   `createStore(v, { name: "cart" })`) so chains and tables refer to them by name.
+3. **Record the interaction and ask.** First choice — no app code — is the diagnostics
+   endpoint: with `@solidjs/diagnostics` in `devDependencies`, the Vite plugin's
+   `diagnostics` option (auto-on when the package is declared; dev server only, never
+   under vitest, `vite build`, or preview) injects the capture bridge and serves
+   `/__solid/diagnostics`. `begin` enables attribution with `log: false` for the
+   session; `end` disables it and returns the artifact (`diagnostics`,
+   `attribution.{reruns, costs, holds, feedback}`, `records`):
+
+   ```sh
+   curl -X POST localhost:5173/__solid/diagnostics -d '{"method":"begin"}'
+   # ... perform the interaction in the browser ...
+   curl -X POST localhost:5173/__solid/diagnostics -d '{"method":"whyDidRun","params":{"name":"total"}}'
+   curl -X POST localhost:5173/__solid/diagnostics -d '{"method":"costs"}'
+   curl -X POST localhost:5173/__solid/diagnostics -d '{"method":"end"}'   # holds + feedback tables are in the result
+   ```
+
+   `GET` the endpoint for status and the method list (`begin` / `end` / `active` /
+   `whyDidRun` / `costs` — `feedback` and `holds` come back from `end`). With several
+   open tabs the first responder wins, so keep one page under test. Without
+   `@solidjs/diagnostics`, the in-code alternative is an `isDev`-guarded
+   `attribution.enable({ log: false })` in the client entry, then `why(scope)` /
+   `costs()` / `feedback()` from the console or a scratch effect — never `log: true`
+   left on (one collapsed `[why-run]` group per re-run) and never unguarded (on the
+   observe build it records in production).
+4. **Read the verdicts, then the tables.** Fix every coded warning the session raised
+   (`[SILENT_HOLD]`, `[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`,
+   `[EFFECT_RELAY_TEAR]`, `[EFFECT_WRITES_OWN_SOURCE]`, `[ASYNC_WATERFALL]`,
+   `[HOT_SCOPE_RERUNS]`). Then `costs().scopes` (self time, `wastedMs` for runs whose
+   result did not change), `costs().writes` (root writes by downstream work),
+   `feedback().sources` / `.interactions` / `.flights` / `.fallbacks` (silent holds,
+   held time per interaction, abandoned requests, fallback flashes). A scope that
+   re-runs more than its inputs change is a `why(scope)` question — the chain names the
+   write, the changed dependency, and the time.
+5. **Make it a test when it is worth keeping**: `captureArtifact` +
+   `toHaveNoDiagnostics()` / `toHaveNoSilentHolds()` / `toStayWithinRerunBudget(n,
+   { scope })` is the definition of done for the scenario you just tuned.
+
+The bundled `agent-loops` skill (`node_modules/@solidjs/diagnostics/skills/agent-loops/SKILL.md`)
+is the long form of this loop; `solid2-kit init` prints the devDependency note when it
+runs in a project.
+
+### Production observability: the observe build
+
+Everything above is the dev build. Records, traces, and attribution in **production**
+need the observe build, opted into per project — and it changes nothing under `vite dev`:
+
+```ts
+// vite.config.ts
+import solid from '@solidjs/vite-plugin';
+
+export default { plugins: [solid({ ssr: true, observe: true })] };
 ```
 
-`GET` the endpoint for status. With several open tabs the first responder wins,
-so keep one page under test.
+`observe: true` adds the `observe` condition to every environment (client and server,
+`vite build` and preview) and turns on the compiler's `componentNames` option so
+`ownerPath` / `boundaryPath` name components instead of `computed`. Without the plugin,
+set `resolve.conditions` (or `node --conditions=observe` for an unbundled server) and
+`componentNames` yourself. Cost in Solid's size suite: ~16.8 KB against ~15.3 KB brotli
+for a small client app; importing the attribution engine on top raises the cap to
+~27 KB (a separate entry — an observe build that never imports it never ships it). The
+two error hooks are **not** part of this: they fire on every build, prod included, only
+the paths are `undefined` there.
+
+- **Instrumentation order.** A monitoring SDK's `init()` (and `configureServerErrors`)
+  must run before the modules it patches load. `import "./instrument"` at the top of an
+  entry does not achieve that in ESM (static imports are hoisted in dependency order);
+  the plugin's `start: { instrument: "./src/instrument.ts" }` awaits that server-only
+  module before anything else in the server graph.
+- **Tracing.** The server continues an incoming W3C `traceparent` or originates one;
+  `getTraceContext()` from `@solidjs/web` reads it during the request (in-process
+  server-function calls included) — forward it downstream with
+  `headers: { ...getTraceContext()?.entries }`. The browser is told which trace the page
+  belongs to on `Server-Timing` and `<meta>` tags, but only when the incoming trace was
+  sampled or a provider answered; a page with no tracing tool sees no wire change. On
+  the observe build a tracing SDK supplies the trace with
+  `OBSERVE?.server.trace.provide((request) => ({ traceId, spanId, entries }))`, once per
+  request. Do not write middleware to inject trace headers.
+- **Records.** `OBSERVE?.records.subscribe(type, (event, live) => …)` delivers one plain
+  record per `"boundary"` (a `<Loading>` that waited on the server), `"invocation"`
+  (server-function execution), `"call"` (server-function call from the page — shares
+  `id` with its invocation), and `"frame"` (produced / applied). Records are
+  serializable data; live handles (request, args, the error as thrown) ride in the
+  second argument. Listeners run synchronously inside the runtime, **must not write
+  signals**, and should subscribe from a module that loads before the app.
+- **Interactions.** `attribution.enable()` then
+  `attribution.subscribe("interaction", (event) => …)` says what each click waited on
+  (`event.settledMs`, `event.holds[].blockers`, `event.holds[].holdMs`); a hold nothing acknowledged
+  is the dead click. The fold tables stay separate imports.
+- **What leaves the process.** Beyond names, four record fields carry page data —
+  `target` (element as `tag#id "text"`, 30 chars), `prev` / `value` previews (40 chars),
+  navigation `to` / `from` / `params`, and `data.error` on server render findings — an
+  exporter decides what to do with each. A tool that renders inside the app it watches
+  (devtools panel) marks its root with `OBSERVE?.exclude(getOwner()!)` inside its
+  `createRoot` so its own effects and stores never become findings; do not route its
+  writes through `runWithOwner` (that is a write in an owned scope).
 
 ## Client mode: no server HTML, no hydration reflexes
 
@@ -1233,8 +1399,42 @@ export const fetchStory = GET(async (id: number) => {
 });
 ```
 
+A value that changes over time is `live(GET(fn))` — **`live()` outermost**: `GET()`
+chooses the read transport and `live()` wraps the call behavior around it. `live()`
+does not imply `GET()`; without it the source streams over POST, which is fine when a
+cacheable URL is of no use.
+
+```ts
+// src/data/auction.ts
+import { GET, live } from '@solidjs/web/server-functions';
+
+export const liveAuction = live(
+  GET(async function* (id: string) {
+    'use server';
+    yield await db.auctions.find(id); // current state first, from storage
+    for await (const _change of db.auctions.subscribe(id)) {
+      yield await db.auctions.find(id);
+    }
+  }),
+);
+
+export async function saveBid(id: string, amount: number) {
+  'use server';
+  await db.bids.place(id, amount);
+}
+```
+
+A plain `async function*` server function (no `live()`) is a different tool: an
+**event sequence** on one connection, consumed with `for await` and accumulated. When
+that connection drops, the iteration ends with an error and nothing reopens it; ending
+the iteration in the browser aborts the request and fires the server's
+`request.signal`. Use it for an order's status history; use `live()` when each value
+replaces the previous one.
+
 `live()` yields **current state** (each yield replaces the last); do not treat
-it as an append-only event log. Until the first yield it is unsettled
+it as an append-only event log. A reconnect calls the function again and its first
+yield replaces the stale answer, so read that first value from the state mutations write
+to (database, shared server state) — not from generator locals or per-connection memory. Until the first yield it is unsettled
 (`<Loading>`), same as a Promise; later yields are updates — the fallback does
 not return.
 Wire status is a side channel on the **iterable the `live()` call returns**,
@@ -1335,7 +1535,10 @@ how to reuse. Prefer the form on the right.
 | `throw new Error("expired")` from a server function (prod) | `throw markSafeError(...)` or `throw respond(body, { status })` |
 | `const r = await api.x(); if (!r.ok) ...` result-object checks at every read | throw unusable responses; contain each region with `<Errored>` |
 | `GET(async (id) => { "use server"; await db.delete(id) })` | mutations stay on POST; `GET()` is for idempotent reads |
-| `live()` yields as an event log to append | each yield **replaces** the current answer; yield current state first |
+| `live()` yields as an event log to append | each yield **replaces** the current answer; yield current state first, read from the state mutations write to — a reconnect calls the function again, so generator locals or per-connection memory are not the source |
+| `GET(live(async function* () { ... }))` | `live(GET(async function* () { ... }))` — `live()` outermost; `live()` alone streams over POST |
+| a plain `async function*` `"use server"` stream for a value that must survive a dropped connection | `live()` — a plain stream is an event sequence on one connection (`for await`, accumulate); nothing reopens it when it drops |
+| `yield saveBid(...)` then `refresh(auction)` on a store derived from `live()` | `yield saveBid(...); yield until(() => auction.highBid >= amount, { timeout })` — `live()` is outside revalidation/single-flight; `refresh` re-runs the derivation (closes the stream, calls the source again): a reconnect per mutation, and the old value still flashes back whenever the new first value predates the write |
 | `<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) |
@@ -1406,6 +1609,12 @@ how to reuse. Prefer the form on the right.
 | `fallback={(err) => { captureException(err()); return <Fallback />; }}` | `configureClientErrors({ onError })` from `solid-js` (or `render(..., { onError })`), `configureServerErrors({ onError })` from `@solidjs/web` — once per error, with `ownerPath` / `boundaryPath` |
 | `latest(user) ?? placeholder` in a handler as a null-safe read | `latest()` throws `NotReadyError` before the first value in every scope; read settled values under `<Loading>`, or `await until(() => user())` |
 | `attribution.why(total)` / `attribution.format(e)` / `attribution.costs()` | named imports from `solid-js/attribution`: `why(total)`, `formatRerun(e)`, `costs()`, `feedback()`, `subscriptions(scope)` (rc.9) |
+| `attribution.enable()` unguarded in app code, or `enable()` with the default `log: true` left on | `if (isDev) attribution.enable({ log: false })` — on the observe build an unguarded `enable()` records in production; prefer the `/__solid/diagnostics` session (`begin` enables, `end` disables) so app code carries nothing |
+| `solid({ observe: true })` added "to see diagnostics in dev" | `vite dev` is always the dev build; `observe: true` is the production-observability opt-in (observe condition + `componentNames` for `vite build`/preview) |
+| `configureServerErrors({ onError: (e) => { report(e); return e; } })` | return nothing or a reference (`new Error(\`ref ${id}\`)`) — the return value replaces the sanitized wire value; the error itself leaks message/stack/secrets |
+| `import "./instrument"` at the top of the server entry for a monitoring SDK | `start: { instrument: "./src/instrument.ts" }` — ESM hoists static imports in dependency order, so the entry's own deps load first |
+| Express/middleware injecting `traceparent` / trace headers into responses | the runtime carries a sampled or provided trace on `Server-Timing` + `<meta>`; forward downstream with `getTraceContext()?.entries`; SDKs use `OBSERVE?.server.trace.provide` |
+| `OBSERVE.records.subscribe("call", (e) => setStats(...))` | listeners run synchronously inside the runtime and must not write signals; collect into a plain buffer and drain from outside |
 | `import { storePath } from "solid-js"` | gone from `solid-js` (rc.9); write draft setters `setState((d) => { d.user.name = "Grace"; })` |
 | `<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 |
@@ -1586,7 +1795,9 @@ always-applied rules installed alongside this skill.
       setters + `action` + server functions): do not rewrite App with
       loading/error branches, disable optimistic rows until ack, or refetch in
       `hydrate` / `onSettled`. HTTP does not enforce TypeScript — validate
-      inside `"use server"`; do not invent tRPC. `live()` owns the client connection.
+      inside `"use server"`; do not invent tRPC. `live()` owns the client connection,
+      is declared `live(GET(fn))`, and a mutation on a live-read value holds with
+      `yield until(...)` for the echo instead of `refresh()`.
       A server bundle uses `handleRequest` from `dist/server/server.js`; client-only start
       is static `dist/client`. Do not delay `renderToStream` for visual order
       (`<Reveal>` does).
@@ -1609,9 +1820,12 @@ always-applied rules installed alongside this skill.
       writes paired with `isPending` / `latest` / optimistic values / `affects()`
       (no `[SILENT_HOLD]`). Attribution-only costs
       (`[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`, `[EFFECT_*]`)
-      checked via `attribution` + the named folds (`why`, `costs`, `feedback`) from
-      `solid-js/attribution` when touching stores, lists, or effects. Name
-      interrogated scopes (`{ name: "total" }`).
+      checked via the [development loop](#development-loop-self-diagnose-before-finishing)
+      (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end`, or an
+      `isDev`-guarded `attribution.enable({ log: false })` + `why` / `costs` /
+      `feedback`) whenever the change touched stores, lists, async, actions, or
+      effects. Name interrogated scopes (`{ name: "total" }`). `observe: true` is a
+      production opt-in, not a dev step.
 - [ ] 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

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

@@ -67,6 +67,9 @@ read these before writing route JSX.
 
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/avoid-unnecessary-effects.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/debugging-reactivity.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/performance.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/observability.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/guides/observability-adapters.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/lists.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/data-fetching-patterns.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/guides/forms.md
@@ -117,9 +120,17 @@ verify API names against the reference pages above.
 - 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: diagnostics (dev builds only)
+## Reference: diagnostics, attribution, and observability
+
+`DEV` is dev builds only; `OBSERVE` and attribution exist on observe and dev builds;
+the error hooks fire on every build.
 
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/diagnostics-dev-hooks/dev.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/diagnostics-dev-hooks/observe.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/diagnostics-dev-hooks/attribution.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/diagnostics-dev-hooks/configure-client-errors.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/configure-server-errors.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/get-trace-context.md
 
 ## Reference: components and JSX (solid-js)
 
@@ -151,7 +162,6 @@ verify API names against the reference pages above.
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/head/use-head.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/components/portal.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/components/dynamic.md
-- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/components/dynamic-component.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/jsx-properties/ref.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/jsx-properties/class.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/jsx-properties/style.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Teach AI coding agents (Cursor, Claude Code) to write correct Solid 2.0 instead of React or Solid 1.x — always-applied rules, an agent skill, and a mechanical pattern gate.",
   "type": "module",
   "license": "MIT",