solid2-agent-kit 0.4.4 → 0.7.0

package/README.md

@@ -16,7 +16,12 @@ 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`/`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) |
+| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), and `<Dynamic>` (use `dynamic()`) |
+| Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
+| Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
+| Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |
+| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a 1.x `solid-js` range, `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
+| Review command | `.cursor/commands/solid2-review.md` | `.claude/commands/solid2-review.md` | `/solid2-review` — on-demand deep review: runs both gates, then walks the diff against the skill checklist targeting the semantic failure classes regexes cannot see (post-`await` reads, effect misuse, unkeyed server rows, boundary placement, context snapshots) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything
 outside them is yours. Kit-owned files (`solid-2.mdc`, the skill directories) are overwritten
@@ -35,11 +40,16 @@ npx github:lightsound/solid2-agent-kit init
 npx github:lightsound/solid2-agent-kit init --cursor
 npx github:lightsound/solid2-agent-kit init --claude
 
-# run the mechanical pattern gate (default source dir: src)
+# run the mechanical pattern gate (default source dir: src; or name files)
 npx github:lightsound/solid2-agent-kit check
 npx github:lightsound/solid2-agent-kit check --dir app
+npx github:lightsound/solid2-agent-kit check src/App.tsx
 
-# pull in kit updates later (idempotent; replaces managed blocks and kit-owned files)
+# check the project wiring (deps, tsconfig, root configs)
+npx github:lightsound/solid2-agent-kit doctor
+
+# pull in kit updates later (idempotent; replaces managed blocks, kit-owned
+# files, and hook entries)
 npx github:lightsound/solid2-agent-kit sync
 ```
 
@@ -58,6 +68,71 @@ Update later with `bun update solid2-agent-kit` (or the npm/pnpm equivalent) fol
 `npx solid2-agent-kit sync`. Outside a project that has the kit installed, prefer the
 `npx github:...` form — it always tracks this repo directly.
 
+## Edit-time hooks (automatic enforcement)
+
+The rules and skill teach; `check` verifies — but only if someone runs it. The hook layer
+closes that gap: `init`/`sync` wire `solid2-kit hook` into both agents' hook systems, so the
+mechanical gate runs on **every file the agent edits** and violations come back as feedback
+the agent must act on, in the same turn it introduced them:
+
+- **Cursor** — a `postToolUse` entry in `.cursor/hooks.json`; findings are injected into the
+  conversation as `additional_context` right after the tool result.
+- **Claude Code** — a `PostToolUse` entry in `.claude/settings.json` (matcher
+  `Edit|MultiEdit|Write|Bash`); findings go to stderr with exit 2, which Claude Code feeds
+  back to the model as a correction prompt.
+
+Agents also edit files *through the shell* (sed, heredocs, `mv`, codemod scripts), which
+never hits the Edit/Write tools — so shell-shaped tool payloads are scanned for source
+paths mentioned in the command, and those files are checked after the command ran.
+
+Claude Code additionally gets a **turn-end gate**: a `Stop` hook re-runs the whole
+mechanical check (over `src`/`app`/`lib`) plus `doctor` when the agent tries to finish its
+turn, and blocks the stop while findings remain. `stop_hook_active` is honored, so an agent
+that cannot satisfy the gate is forced to continue exactly once, never looped forever.
+(Cursor's `stop` hook cannot feed back to the agent, so there the last line of defense is
+the always-attached rules plus CI.)
+
+Both agents also get a **pre-execution guard** (Claude: `PreToolUse`; Cursor: `preToolUse`
+and `beforeShellExecution`). A blocked agent's classic next move is to decide the gate
+itself is wrong — edit the rules file, delete the skill, or strip the hook entries. The
+guard denies, before the tool call runs: writes to kit-owned files (rules `.mdc`, skill
+directories, review commands, the kit under `node_modules`); edits to `.cursor/hooks.json`
+/ `.claude/settings.json` / `AGENTS.md` / `CLAUDE.md` that would remove the kit's entries
+or managed blocks (marker-preserving edits pass — agents can still add the user's own
+hooks and sections); shell rewrites of those files (`sed`/`rm`/redirects — uninspectable,
+so the deny message redirects to the Edit tool); and package-manager installs of
+dependencies `doctor` bans (exact token match, so `react` is denied but `react-aria` is
+not). The deny message always tells the agent what to do instead — fix the flagged code,
+run `solid2-kit sync`, or stop and ask the user. Pre-execution events never run the
+content check itself: fixing a currently-bad file is always allowed.
+
+When the kit is installed as a devDependency, `init` also wires a `lint:solid` script
+(`solid2-kit check && solid2-kit doctor`) into the project's `package.json` (only if the
+script does not already exist), so agents and CI can run both gates by name.
+
+The hook command is `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs hook <agent>`,
+so it only works when the kit is installed as a devDependency (see above); `init` skips the
+wiring and prints a note otherwise. Merging is idempotent — kit entries are refreshed in
+place on `sync`, user entries are preserved. Opt out with `init --no-hooks`. Hooks never
+break the agent loop: clean edits, read tools, and malformed payloads exit silently, and
+reports are capped at 40 findings.
+
+Note on gate precision: `check` (and therefore the hooks) matches against
+**comment-stripped** source, so prose like `// migrated off createResource` never trips
+the gate, while string checks (`"use client"`) still work.
+
+## CI for consuming projects
+
+Run both gates on every PR so nothing an agent (or human) merges can reintroduce React or
+Solid 1.x patterns:
+
+```yaml
+- uses: actions/setup-node@v4
+  with: { node-version: 22 }
+- run: npm ci
+- run: npx solid2-agent-kit check && npx solid2-agent-kit doctor
+```
+
 ## Why not eslint-plugin-solid?
 
 `eslint-plugin-solid` was built for Solid 1.x. Its analyzer predates the Solid 2 model and
@@ -88,12 +163,13 @@ markdown with an `.md` suffix).
 ## Layout
 
 ```
-bin/solid2-kit.mjs                 CLI: init / sync / check
+bin/solid2-kit.mjs                 CLI: init / sync / check / doctor / hook
 files/shared/rules-body.md         hard rules (rendered into .mdc and CLAUDE.md)
 files/shared/agents-section.md     AGENTS.md managed-block content
 files/skills/solid-2/              SKILL.md + references/official-docs.md
+files/commands/solid2-review.md    /solid2-review command (Cursor + Claude Code)
 scripts/check-docs-drift.mjs       weekly docs cross-check
-tests/                             mechanical-gate fixtures (`npm test`)
+tests/                             check/doctor fixtures + hook and init-merge tests (`npm test`)
 ```
 
 ## Publishing (npm)

package/bin/solid2-kit.mjs

@@ -2,12 +2,15 @@
 // solid2-agent-kit CLI — installs and maintains Solid 2.0 guidance for AI
 // coding agents (Cursor and Claude Code), and runs a mechanical pattern gate.
 //
-//   solid2-kit init  [--cursor] [--claude] [--target <dir>]
-//   solid2-kit sync  [--cursor] [--claude] [--target <dir>]   (alias of init)
-//   solid2-kit check [--dir <srcdir>] [--target <dir>]
+//   solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]
+//   solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]   (alias of init)
+//   solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]
+//   solid2-kit doctor [--target <dir>]
+//   solid2-kit hook (claude|cursor)          (stdin: agent hook JSON payload)
 //
-// `init`/`sync` are idempotent: kit-owned files are overwritten and managed
-// blocks in AGENTS.md / CLAUDE.md are replaced in place.
+// `init`/`sync` are idempotent: kit-owned files are overwritten, managed
+// blocks in AGENTS.md / CLAUDE.md are replaced in place, and hook entries in
+// .cursor/hooks.json / .claude/settings.json are merged without duplicates.
 
 import {
   cpSync,
@@ -32,6 +35,20 @@ function flagValue(name, fallback) {
   return index === -1 || index + 1 >= args.length ? fallback : args[index + 1];
 }
 
+const VALUE_FLAGS = new Set(['--dir', '--target']);
+
+function positionalArgs() {
+  const out = [];
+  for (let i = 1; i < args.length; i += 1) {
+    if (args[i].startsWith('--')) {
+      if (VALUE_FLAGS.has(args[i])) i += 1;
+      continue;
+    }
+    out.push(args[i]);
+  }
+  return out;
+}
+
 // --- init / sync ------------------------------------------------------------
 
 function countOccurrences(haystack, needle) {
@@ -74,6 +91,104 @@ function writeKitOwnedFile(filePath, body) {
   return filePath;
 }
 
+// Hook commands run from the project root without node_modules/.bin on PATH,
+// so they invoke the locally installed kit through node directly. `init` only
+// wires hooks when that file exists (kit installed as a dependency).
+const KIT_LOCAL_BIN = 'node_modules/solid2-agent-kit/bin/solid2-kit.mjs';
+
+function readJsonConfig(filePath) {
+  if (!existsSync(filePath)) return {};
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    console.warn(
+      `solid2-kit — warning: ${filePath} is not valid JSON. File left untouched; fix it and re-run sync to wire the edit hook.`,
+    );
+    return null;
+  }
+}
+
+function writeJsonConfig(filePath, config) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`);
+  return filePath;
+}
+
+// Replace the existing kit-owned entry (identified by the marker in its
+// command) or append a fresh one — sync then updates matchers/commands that
+// changed between kit versions while leaving user entries untouched.
+function upsertHookEntry(entries, marker, entry, matches) {
+  const index = entries.findIndex((existing) => matches(existing, marker));
+  if (index === -1) entries.push(entry);
+  else entries[index] = entry;
+}
+
+const cursorEntryMatches = (entry, marker) =>
+  typeof entry?.command === 'string' && entry.command.includes(marker);
+const claudeEntryMatches = (entry, marker) =>
+  (entry?.hooks ?? []).some((item) => typeof item?.command === 'string' && item.command.includes(marker));
+
+// Cursor hooks: postToolUse (post-edit check injected as additional_context)
+// plus preToolUse / beforeShellExecution (pre-execution guard: guardrail
+// tampering and banned-dependency installs are denied before they run).
+function upsertCursorHook(target) {
+  const filePath = join(target, '.cursor/hooks.json');
+  const config = readJsonConfig(filePath);
+  if (config === null) return null;
+  config.version ??= 1;
+  config.hooks ??= {};
+  const command = `node ${KIT_LOCAL_BIN} hook cursor`;
+  for (const event of ['postToolUse', 'preToolUse', 'beforeShellExecution']) {
+    upsertHookEntry((config.hooks[event] ??= []), 'solid2-kit.mjs hook cursor', { command }, cursorEntryMatches);
+  }
+  return writeJsonConfig(filePath, config);
+}
+
+// Claude Code hooks: PostToolUse (`hook claude` prints findings to stderr and
+// exits 2, which Claude Code feeds back into the model as correction context;
+// Bash is matched so shell edits via sed/heredocs are gated too), PreToolUse
+// (pre-execution guard, may deny) and Stop (whole-project final gate — the
+// agent cannot end its turn with findings).
+function upsertClaudeHook(target) {
+  const filePath = join(target, '.claude/settings.json');
+  const config = readJsonConfig(filePath);
+  if (config === null) return null;
+  config.hooks ??= {};
+  const command = `node ${KIT_LOCAL_BIN} hook claude`;
+  const toolMatcher = 'Edit|MultiEdit|Write|Bash';
+  upsertHookEntry(
+    (config.hooks.PreToolUse ??= []),
+    'solid2-kit.mjs hook claude',
+    { matcher: toolMatcher, hooks: [{ type: 'command', command, timeout: 30 }] },
+    claudeEntryMatches,
+  );
+  upsertHookEntry(
+    (config.hooks.PostToolUse ??= []),
+    'solid2-kit.mjs hook claude',
+    { matcher: toolMatcher, hooks: [{ type: 'command', command, timeout: 30 }] },
+    claudeEntryMatches,
+  );
+  upsertHookEntry(
+    (config.hooks.Stop ??= []),
+    'solid2-kit.mjs hook claude',
+    { hooks: [{ type: 'command', command, timeout: 60 }] },
+    claudeEntryMatches,
+  );
+  return writeJsonConfig(filePath, config);
+}
+
+// Wire a `lint:solid` script (referenced by the AGENTS.md guidance) into the
+// consuming project so agents and CI can run both gates by name.
+function upsertLintScript(target) {
+  const filePath = join(target, 'package.json');
+  if (!existsSync(filePath)) return null;
+  const pkg = readJsonConfig(filePath);
+  if (pkg === null) return null;
+  if (pkg.scripts?.['lint:solid']) return null;
+  (pkg.scripts ??= {})['lint:solid'] = 'solid2-kit check && solid2-kit doctor';
+  return writeJsonConfig(filePath, pkg);
+}
+
 function copySkill(targetSkillDir) {
   // The skill directory is kit-owned: remove it first so files deleted in
   // newer kit versions do not linger after a sync.
@@ -92,6 +207,7 @@ function init() {
 
   const rulesBody = readFileSync(join(KIT_ROOT, 'files/shared/rules-body.md'), 'utf8');
   const agentsSection = readFileSync(join(KIT_ROOT, 'files/shared/agents-section.md'), 'utf8');
+  const reviewCommand = readFileSync(join(KIT_ROOT, 'files/commands/solid2-review.md'), 'utf8');
   const written = [];
 
   if (wantCursor) {
@@ -109,10 +225,12 @@ function init() {
     ].join('\n');
     written.push(writeKitOwnedFile(join(target, '.cursor/rules/solid-2.mdc'), mdc));
     written.push(copySkill(join(target, '.cursor/skills/solid-2')));
+    written.push(writeKitOwnedFile(join(target, '.cursor/commands/solid2-review.md'), reviewCommand));
   }
 
   if (wantClaude) {
     written.push(copySkill(join(target, '.claude/skills/solid-2')));
+    written.push(writeKitOwnedFile(join(target, '.claude/commands/solid2-review.md'), reviewCommand));
     // Claude Code has no glob-attached rules mechanism; CLAUDE.md is always
     // loaded, so the full rules body lives there in a managed block.
     written.push(
@@ -134,8 +252,24 @@ function init() {
     ),
   );
 
+  // Edit-time hooks: run the mechanical gate automatically on every agent
+  // file edit, so enforcement does not depend on the agent remembering to
+  // run `solid2-kit check`.
+  let hooksNote = null;
+  if (!args.includes('--no-hooks')) {
+    if (existsSync(join(target, KIT_LOCAL_BIN))) {
+      if (wantCursor) written.push(upsertCursorHook(target));
+      if (wantClaude) written.push(upsertClaudeHook(target));
+      written.push(upsertLintScript(target));
+    } else {
+      hooksNote =
+        'edit-time hooks not wired: install the kit as a devDependency ("solid2-agent-kit": "github:lightsound/solid2-agent-kit") so `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs` resolves, then re-run sync. Pass --no-hooks to silence this note.';
+    }
+  }
+
   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}`);
 }
 
 // --- check ------------------------------------------------------------------
@@ -351,10 +485,75 @@ 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.
-const SOURCE_FILE = /(?<!\.d)\.tsx?$/;
+// .ts / .tsx / .jsx sources, excluding .d.ts declaration files.
+const SOURCE_FILE = /(?<!\.d)\.(?:tsx?|jsx)$/;
+
+// Blank comment interiors (preserving newlines and offsets) so banned tokens
+// mentioned in comments ("migrated off createResource") do not trip the gate.
+// String and template contents are preserved — some checks match string
+// literals ("use client"). This is a heuristic scanner, not a JS lexer: a
+// regex literal containing escaped slashes or `//` in JSX text can blank the
+// remainder of that one line (false negatives only, never false positives).
+function stripComments(content) {
+  let out = '';
+  let state = 'code';
+  for (let i = 0; i < content.length; i += 1) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (state === 'code') {
+      if (ch === '/' && (next === '/' || next === '*')) {
+        state = next === '/' ? 'line' : 'block';
+        out += '  ';
+        i += 1;
+      } else {
+        if (ch === "'") state = 'single';
+        else if (ch === '"') state = 'double';
+        else if (ch === '`') state = 'template';
+        out += ch;
+      }
+    } else if (state === 'line') {
+      if (ch === '\n') state = 'code';
+      out += ch === '\n' ? ch : ' ';
+    } else if (state === 'block') {
+      if (ch === '*' && next === '/') {
+        state = 'code';
+        out += '  ';
+        i += 1;
+      } else {
+        out += ch === '\n' ? ch : ' ';
+      }
+    } else {
+      out += ch;
+      if (ch === '\\') {
+        out += next ?? '';
+        i += 1;
+      } else if (
+        (state === 'single' && ch === "'") ||
+        (state === 'double' && ch === '"') ||
+        (state === 'template' && ch === '`')
+      ) {
+        state = 'code';
+      }
+    }
+  }
+  return out;
+}
 
 function* walk(dir) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -364,36 +563,435 @@ function* walk(dir) {
   }
 }
 
+// One formatted finding per pattern match: "path:line [id] message\n  > source".
+// Patterns run against comment-stripped content (same offsets); the quoted
+// source line comes from the original file.
+function fileFindings(file, relativeTo) {
+  const raw = readFileSync(file, 'utf8');
+  const content = stripComments(raw);
+  const lines = raw.split('\n');
+  const findings = [];
+  for (const rule of CHECKS) {
+    for (const match of content.matchAll(rule.pattern)) {
+      const lineNumber = content.slice(0, match.index).split('\n').length;
+      findings.push(
+        `${relative(relativeTo, file) || file}:${lineNumber} [${rule.id}] ${rule.message}\n  > ${lines[lineNumber - 1].trim()}`,
+      );
+    }
+  }
+  return findings;
+}
+
 function check() {
   const target = resolve(flagValue('--target', '.'));
-  const srcDir = resolve(target, flagValue('--dir', 'src'));
-  if (!existsSync(srcDir)) {
-    console.error(`solid2-kit check — source directory not found: ${srcDir} (use --dir)`);
-    process.exit(2);
+  const fileArgs = positionalArgs();
+
+  let files;
+  if (fileArgs.length > 0) {
+    // Explicit file mode (used by agent hooks): check only the named sources.
+    files = fileArgs.map((file) => resolve(target, file)).filter((file) => SOURCE_FILE.test(file));
+  } else {
+    const srcDir = resolve(target, flagValue('--dir', 'src'));
+    if (!existsSync(srcDir)) {
+      console.error(`solid2-kit check — source directory not found: ${srcDir} (use --dir)`);
+      process.exit(2);
+    }
+    files = [...walk(srcDir)];
   }
 
   let findings = 0;
-  let files = 0;
-  for (const file of walk(srcDir)) {
-    files += 1;
-    const content = readFileSync(file, 'utf8');
-    const lines = content.split('\n');
-    for (const rule of CHECKS) {
-      for (const match of content.matchAll(rule.pattern)) {
-        findings += 1;
-        const lineNumber = content.slice(0, match.index).split('\n').length;
-        console.error(
-          `${relative(target, file)}:${lineNumber} [${rule.id}] ${rule.message}\n  > ${lines[lineNumber - 1].trim()}`,
+  for (const file of files) {
+    for (const finding of fileFindings(file, target)) {
+      findings += 1;
+      console.error(finding);
+    }
+  }
+
+  if (findings > 0) {
+    console.error(`\nsolid2-kit check — ${findings} finding(s) in ${files.length} file(s).`);
+    process.exit(1);
+  }
+  console.log(`solid2-kit check — OK (${files.length} files scanned).`);
+}
+
+// --- hook -------------------------------------------------------------------
+// Edit-time gate wired by `init` into the agents' hook systems. Reads the
+// hook JSON payload from stdin, runs the mechanical checks on the edited
+// source files, and feeds findings back through each agent's channel:
+//   claude — Claude Code PostToolUse: findings on stderr + exit 2 (Claude
+//            sees the stderr and fixes; other exit codes are ignored). Also
+//            handles the Stop event as a whole-project final gate: exit 2
+//            blocks the agent from ending its turn with violations in place.
+//   cursor — Cursor postToolUse: findings as {"additional_context"} JSON on
+//            stdout (injected into the conversation after the tool result).
+// Both agents also edit files through shell commands (sed, heredocs, mv,
+// codemods), which never hit the Edit/Write tools — so shell-shaped tool
+// payloads are scanned for source paths mentioned in the command and those
+// files are checked after the command ran.
+// Hooks must never break the agent loop: malformed payloads exit 0 silently.
+
+const WRITE_TOOL = /write|edit|replace|apply|patch/i;
+const SHELL_TOOL = /shell|bash|terminal|command|exec/i;
+const MAX_REPORTED = 40;
+
+function formatReport(header, findings) {
+  const shown = findings.slice(0, MAX_REPORTED);
+  const more = findings.length - shown.length;
+  return `${header}\n\n${shown.join('\n')}${more > 0 ? `\n…and ${more} more finding(s).` : ''}`;
+}
+
+function isCheckableSource(path) {
+  return SOURCE_FILE.test(path) && !path.includes('\n') && !path.includes('node_modules');
+}
+
+function collectSourcePaths(value, found = new Set()) {
+  if (typeof value === 'string') {
+    if (isCheckableSource(value) && existsSync(value)) found.add(value);
+  } else if (Array.isArray(value)) {
+    for (const item of value) collectSourcePaths(item, found);
+  } else if (value && typeof value === 'object') {
+    for (const item of Object.values(value)) collectSourcePaths(item, found);
+  }
+  return found;
+}
+
+// Path-shaped tokens ending in a source extension, resolved against the
+// command's cwd. Existence filtering keeps false positives at zero.
+function collectCommandPaths(command, cwd, found = new Set()) {
+  if (typeof command !== 'string') return found;
+  for (const match of command.matchAll(/[^\s'"`;|&()<>=]+\.(?:tsx?|jsx)\b/g)) {
+    const token = match[0];
+    if (!isCheckableSource(token)) continue;
+    const path = resolve(cwd, token);
+    if (existsSync(path)) found.add(path);
+  }
+  return found;
+}
+
+// --- pre-execution guard (self-defense + proactive denial) -------------------
+// Agents that keep getting blocked by a gate tend to conclude the gate is
+// wrong and edit or delete it. Pre-execution hooks (Claude PreToolUse,
+// Cursor preToolUse / beforeShellExecution) can deny a tool call before it
+// runs, so this guard refuses:
+//   - edits/deletes of kit-owned guardrail files (rules, skill, commands,
+//     the kit itself under node_modules),
+//   - edits that would remove the kit's markers from hook configs or the
+//     AGENTS.md / CLAUDE.md managed blocks,
+//   - shell rewrites of those files (sed/rm/redirects — uninspectable),
+//   - installing dependencies doctor would flag anyway (react,
+//     vite-plugin-solid, eslint-plugin-solid, SolidStart, ...).
+// Everything else is allowed; this gate never inspects file *content* being
+// written (that is the post-edit hook's job).
+
+const GUARDRAIL_PATH =
+  /\.cursor\/rules\/solid-2\.mdc|(?:\.cursor|\.claude)\/skills\/solid-2|(?:\.cursor|\.claude)\/commands\/solid2-review\.md|node_modules\/solid2-agent-kit\//;
+const MARKER_FILE = /(?:\.claude\/settings\.json|\.cursor\/hooks\.json|AGENTS\.md|CLAUDE\.md)$/;
+const KIT_MARKER = 'solid2-agent-kit';
+const SHELL_WRITE = /\b(?:rm|mv|cp|sed|tee|truncate|unlink|chmod|perl|python[\d.]*)\b|>>?/;
+const INSTALL_CMD = /\b(?:npm|pnpm|yarn|bun)\s+(?:-\S+\s+)*(?:install|add|i)\b/;
+
+const TAMPER_MESSAGE =
+  'solid2-agent-kit guardrail: this file is kit-managed Solid 2.0 guidance/enforcement. Do not edit, weaken, or delete it — fix the flagged code instead. Kit files update via `solid2-kit sync`. If you believe the guardrail itself is wrong, or the user explicitly wants it removed, stop and tell the user.';
+
+function bannedInstall(command) {
+  if (!INSTALL_CMD.test(command)) return null;
+  for (const raw of command.split(/\s+/)) {
+    const token = raw.replace(/^['"]|['"]$/g, '');
+    const name = token.replace(/(?!^)@.*$/, '');
+    if (name in BANNED_DEPS) return name;
+  }
+  return null;
+}
+
+function preToolGate(agent, payload) {
+  const deny = (agentMessage) => {
+    if (agent === 'claude') {
+      console.error(agentMessage);
+      process.exit(2);
+    }
+    console.log(
+      JSON.stringify({
+        permission: 'deny',
+        agent_message: agentMessage,
+        user_message: 'solid2-agent-kit guardrail blocked this action.',
+      }),
+    );
+    process.exit(0);
+  };
+
+  let toolInput = payload.tool_input;
+  if (typeof toolInput === 'string') {
+    try {
+      toolInput = JSON.parse(toolInput);
+    } catch {
+      toolInput = undefined;
+    }
+  }
+  const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+
+  // Shell commands: beforeShellExecution carries `command` at the top level,
+  // PreToolUse(Bash) inside tool_input.
+  const command =
+    typeof payload.command === 'string'
+      ? payload.command
+      : SHELL_TOOL.test(toolName) && typeof toolInput?.command === 'string'
+        ? toolInput.command
+        : null;
+  if (command !== null) {
+    const banned = bannedInstall(command);
+    if (banned) {
+      deny(
+        `solid2-agent-kit guardrail: do not install "${banned}". ${BANNED_DEPS[banned]} (\`solid2-kit doctor\` fails on it.)`,
+      );
+    }
+    if (SHELL_WRITE.test(command)) {
+      if (GUARDRAIL_PATH.test(command)) deny(TAMPER_MESSAGE);
+      if (/(?:\.claude\/settings\.json|\.cursor\/hooks\.json)/.test(command)) {
+        deny(
+          'solid2-agent-kit guardrail: rewriting hook configs through the shell cannot be verified. Use the Edit tool (keeping the solid2-agent-kit hook entries), or ask the user.',
         );
       }
     }
+    process.exit(0);
   }
 
-  if (findings > 0) {
-    console.error(`\nsolid2-kit check — ${findings} finding(s) in ${files} file(s).`);
+  if (!WRITE_TOOL.test(toolName)) process.exit(0);
+  const filePath = typeof toolInput?.file_path === 'string' ? toolInput.file_path : toolInput?.path;
+  if (typeof filePath !== 'string') process.exit(0);
+
+  if (GUARDRAIL_PATH.test(filePath)) deny(TAMPER_MESSAGE);
+
+  if (MARKER_FILE.test(filePath)) {
+    // Editing these files is fine (users add their own hooks/sections through
+    // agents) as long as the kit's entries/managed blocks survive the edit.
+    const removalMessage = `solid2-agent-kit guardrail: this edit removes the ${KIT_MARKER} entries/managed block from ${filePath}. Keep them intact; run \`solid2-kit sync\` to update them. If the user explicitly wants the kit removed, stop and tell the user to do it.`;
+    if (typeof toolInput.content === 'string') {
+      let existing = '';
+      try {
+        existing = readFileSync(resolve(typeof payload.cwd === 'string' ? payload.cwd : process.cwd(), filePath), 'utf8');
+      } catch {
+        // New file — nothing to preserve.
+      }
+      if (existing.includes(KIT_MARKER) && !toolInput.content.includes(KIT_MARKER)) deny(removalMessage);
+    } else if (
+      typeof toolInput.old_string === 'string' &&
+      toolInput.old_string.includes(KIT_MARKER) &&
+      !String(toolInput.new_string ?? '').includes(KIT_MARKER)
+    ) {
+      deny(removalMessage);
+    }
+  }
+
+  process.exit(0);
+}
+
+// Claude Code Stop hook: the per-edit hooks catch violations file by file,
+// but the agent can still end a turn with violations introduced through
+// uncovered paths (git operations, scripts writing files, moved code). The
+// Stop gate re-runs the whole mechanical check plus the wiring doctor and
+// refuses to let the turn end while findings remain. `stop_hook_active`
+// marks a turn that is already continuing because of this gate — allow it
+// through then, so an agent that cannot satisfy the gate never loops forever.
+function stopGate(payload) {
+  if (payload.stop_hook_active) process.exit(0);
+  const target = process.cwd();
+
+  const findings = [];
+  for (const dir of ['src', 'app', 'lib']) {
+    const abs = join(target, dir);
+    if (!existsSync(abs)) continue;
+    for (const file of walk(abs)) findings.push(...fileFindings(file, target));
+  }
+  if (existsSync(join(target, 'package.json'))) {
+    findings.push(...doctorFindings(target).map(({ id, message }) => `[${id}] ${message}`));
+  }
+  if (findings.length === 0) process.exit(0);
+
+  console.error(
+    formatReport(
+      'solid2-kit — React/Solid 1.x patterns are still in the project; fix them before finishing:',
+      findings,
+    ),
+  );
+  process.exit(2);
+}
+
+function hook(agent) {
+  if (agent !== 'claude' && agent !== 'cursor') {
+    console.error('solid2-kit hook — expected agent: claude | cursor');
+    process.exit(2);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+  if (!payload || typeof payload !== 'object') process.exit(0);
+
+  const event = typeof payload.hook_event_name === 'string' ? payload.hook_event_name : '';
+  if (agent === 'claude' && event === 'Stop') stopGate(payload);
+  // Pre-execution events (PreToolUse / preToolUse / beforeShellExecution)
+  // only run the guard — never the content check (the file has not been
+  // written yet, so checking would block edits based on pre-edit state).
+  if (/^(?:pre|before)/i.test(event)) preToolGate(agent, payload);
+
+  // afterFileEdit-style payloads carry file_path at the top level; tool-use
+  // payloads carry the edited path(s) inside tool_input. Only write-shaped
+  // and shell-shaped tools are gated, so reads/searches never are.
+  const files = new Set();
+  if (typeof payload.file_path === 'string') collectSourcePaths(payload.file_path, files);
+  if (payload.tool_input !== undefined) {
+    const toolName = typeof payload.tool_name === 'string' ? payload.tool_name : '';
+    let toolInput = payload.tool_input;
+    if (typeof toolInput === 'string') {
+      try {
+        toolInput = JSON.parse(toolInput);
+      } catch {
+        toolInput = undefined;
+      }
+    }
+    if (toolName === '' || WRITE_TOOL.test(toolName)) {
+      collectSourcePaths(toolInput, files);
+    } else if (SHELL_TOOL.test(toolName)) {
+      const cwd = typeof payload.cwd === 'string' ? payload.cwd : process.cwd();
+      collectCommandPaths(toolInput?.command, cwd, files);
+    }
+  }
+  if (files.size === 0) process.exit(0);
+
+  const findings = [];
+  for (const file of files) {
+    try {
+      findings.push(...fileFindings(file, process.cwd()));
+    } catch {
+      // File disappeared between the edit and the hook — nothing to check.
+    }
+  }
+  if (findings.length === 0) process.exit(0);
+
+  const report = formatReport(
+    'solid2-kit check — React/Solid 1.x patterns in this edit; fix them now:',
+    findings,
+  );
+  if (agent === 'claude') {
+    console.error(report);
+    process.exit(2);
+  }
+  console.log(JSON.stringify({ additional_context: report }));
+  process.exit(0);
+}
+
+// --- doctor -----------------------------------------------------------------
+// Project-config gate: `check` covers TSX sources, `doctor` covers the wiring
+// around them — dependencies, tsconfig, and root config files — where agents
+// also reach for React / Solid 1.x tooling (vite-plugin-solid,
+// eslint-plugin-solid, jsxImportSource: "solid-js", ...).
+
+const BANNED_DEPS = {
+  react: 'React does not belong in a Solid 2.0 project.',
+  'react-dom': 'React does not belong in a Solid 2.0 project.',
+  next: 'Next.js does not belong in a Solid 2.0 project.',
+  'vite-plugin-solid': 'Solid 1.x Vite plugin. Use @solidjs/vite-plugin.',
+  'eslint-plugin-solid':
+    'Built for Solid 1.x; its analyzer misreads Solid 2 idioms (two-phase createEffect, writable derivations, draft setters). Remove it — solid2-kit check carries the still-valid intents.',
+  '@solidjs/start': 'SolidStart 1.x. Solid 2 start mode lives in @solidjs/vite-plugin (start: true).',
+  'solid-start': 'SolidStart 0.x. Solid 2 start mode lives in @solidjs/vite-plugin (start: true).',
+  'solid-app-router': 'Pre-1.0 router. Use @solidjs/router 2 (createRouter({ routes })).',
+  vinxi: 'SolidStart 1.x toolchain. Solid 2 uses @solidjs/vite-plugin directly.',
+};
+
+const CONFIG_SOURCE = /\.(?:m|c)?[jt]s$/;
+
+// Files installed by this kit that carry a version marker. When the kit
+// dependency is updated but `sync` is not re-run, the installed guidance
+// keeps teaching agents the older content — silent drift doctor can catch.
+const GUIDANCE_FILES = ['.cursor/rules/solid-2.mdc', 'CLAUDE.md', 'AGENTS.md'];
+
+function doctorFindings(target) {
+  const findings = [];
+  const report = (id, message) => findings.push({ id, message });
+
+  const pkg = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8'));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  for (const [name, message] of Object.entries(BANNED_DEPS)) {
+    if (name in deps) report(`dep-${name.replace(/[@/]/g, '')}`, `package.json depends on "${name}". ${message}`);
+  }
+  const solidRange = deps['solid-js'];
+  if (typeof solidRange === 'string' && /^[\s^~=v]*[01]\./.test(solidRange)) {
+    report('solid-js-version', `package.json pins solid-js "${solidRange}" — this kit teaches Solid 2.x; upgrade to ^2.`);
+  }
+
+  for (const entry of readdirSync(target, { withFileTypes: true })) {
+    if (!entry.isFile()) continue;
+    const path = join(target, entry.name);
+
+    if (/^tsconfig.*\.json$/.test(entry.name)) {
+      // tsconfig is JSONC; extract the two relevant keys with regexes.
+      const content = readFileSync(path, 'utf8');
+      const jsx = content.match(/"jsx"\s*:\s*"([^"]+)"/)?.[1];
+      if (jsx && jsx !== 'preserve') {
+        report('tsconfig-jsx', `${entry.name} sets "jsx": "${jsx}". Solid 2 compiles its own JSX: use "preserve".`);
+      }
+      const importSource = content.match(/"jsxImportSource"\s*:\s*"([^"]+)"/)?.[1];
+      if (importSource && importSource !== '@solidjs/web') {
+        report(
+          'tsconfig-jsx-import-source',
+          `${entry.name} sets "jsxImportSource": "${importSource}". Solid 2 JSX types live in "@solidjs/web".`,
+        );
+      }
+      continue;
+    }
+
+    if (CONFIG_SOURCE.test(entry.name)) {
+      const content = readFileSync(path, 'utf8');
+      if (/['"]vite-plugin-solid['"]/.test(content)) {
+        report('config-vite-plugin-solid', `${entry.name} references vite-plugin-solid (Solid 1.x). Import solid from "@solidjs/vite-plugin".`);
+      }
+      if (/jsxImportSource['"]?\s*[:=]\s*['"](?:solid-js|react)['"]/.test(content)) {
+        report('config-jsx-import-source', `${entry.name} sets jsxImportSource to solid-js/react. Solid 2 uses "@solidjs/web".`);
+      }
+    }
+
+    if (/^(?:\.eslintrc|eslint\.config\.)/.test(entry.name)) {
+      const content = readFileSync(path, 'utf8');
+      if (content.includes('eslint-plugin-solid')) {
+        report('eslint-plugin-solid', `${entry.name} wires eslint-plugin-solid (Solid 1.x analyzer; false-positives on Solid 2 idioms). Remove it.`);
+      }
+    }
+  }
+
+  for (const guidance of GUIDANCE_FILES) {
+    const path = join(target, guidance);
+    if (!existsSync(path)) continue;
+    const installed = readFileSync(path, 'utf8').match(/solid2-agent-kit v(\d[\w.-]*)/)?.[1];
+    if (installed && installed !== VERSION) {
+      report(
+        'stale-guidance',
+        `${guidance} was installed by solid2-agent-kit v${installed} but v${VERSION} is running — run \`solid2-kit sync\` so agents read current guidance.`,
+      );
+    }
+  }
+
+  return findings;
+}
+
+function doctor() {
+  const target = resolve(flagValue('--target', '.'));
+  if (!existsSync(join(target, 'package.json'))) {
+    console.error(`solid2-kit doctor — no package.json at ${target} (use --target)`);
+    process.exit(2);
+  }
+
+  const findings = doctorFindings(target);
+  for (const { id, message } of findings) console.error(`[${id}] ${message}`);
+
+  if (findings.length > 0) {
+    console.error(`\nsolid2-kit doctor — ${findings.length} finding(s). Fix the project wiring above.`);
     process.exit(1);
   }
-  console.log(`solid2-kit check — OK (${files} files scanned).`);
+  console.log('solid2-kit doctor — OK (dependencies, tsconfig, root configs, and installed guidance look like Solid 2).');
 }
 
 // --- entry ------------------------------------------------------------------
@@ -406,15 +1004,23 @@ switch (command) {
   case 'check':
     check();
     break;
+  case 'doctor':
+    doctor();
+    break;
+  case 'hook':
+    hook(args[1]);
+    break;
   default:
     console.log(
       [
         `solid2-agent-kit v${VERSION}`,
         '',
         'Usage:',
-        '  solid2-kit init  [--cursor] [--claude] [--target <dir>]  install/update guidance (default: both tools)',
-        '  solid2-kit sync  [--cursor] [--claude] [--target <dir>]  alias of init (idempotent)',
-        '  solid2-kit check [--dir <srcdir>] [--target <dir>]       mechanical React/Solid 1.x pattern gate (default dir: src)',
+        '  solid2-kit init  [--cursor] [--claude] [--no-hooks] [--target <dir>]  install/update guidance + edit hooks (default: both tools)',
+        '  solid2-kit sync  [--cursor] [--claude] [--no-hooks] [--target <dir>]  alias of init (idempotent)',
+        '  solid2-kit check [--dir <srcdir>] [--target <dir>] [files...]         mechanical React/Solid 1.x pattern gate (default dir: src)',
+        '  solid2-kit doctor [--target <dir>]                                    project-wiring gate: deps, tsconfig, root configs',
+        '  solid2-kit hook (claude|cursor)                                       edit-time gate for agent hooks (stdin: hook JSON payload)',
       ].join('\n'),
     );
     process.exit(command ? 2 : 0);

package/files/commands/solid2-review.md

@@ -0,0 +1,30 @@
+Review the current change set for Solid 2.0 correctness. This project bans React patterns
+and Solid 1.x APIs; the mechanical gates catch tokens, but several failure classes are
+semantic and need your judgment.
+
+Steps:
+
+1. Run the gates and fix anything they report first:
+   - `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs check`
+   - `node node_modules/solid2-agent-kit/bin/solid2-kit.mjs doctor`
+2. Read the `solid-2` skill (`.cursor/skills/solid-2/SKILL.md` or
+   `.claude/skills/solid-2/SKILL.md`) and its final review checklist.
+3. Collect the diff under review: staged/uncommitted changes if any, otherwise the branch
+   diff against the default branch.
+4. Review every changed `.tsx`/`.jsx`/`.ts` file against the checklist, prioritizing what
+   regexes cannot see:
+   - reactive reads at component-body top level, or extracted into plain `const`s;
+   - async computations reading reactive inputs **after** the first `await`;
+   - effects that copy state instead of deriving it, or reading stores in the apply phase;
+   - `<For>` over server/refetched rows without a stable-id key function;
+   - `<Loading>`/`<Errored>` wrapping page chrome instead of the data slot, or async memos
+     passed as values (`user={user()}`) instead of accessors;
+   - store updates that rebuild objects/arrays instead of mutating the draft or reconciling;
+   - 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
+   (`https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt`); never trust Solid 1.x or
+   React memory.
+
+Report each finding as `file:line — problem — Solid 2 replacement`, then fix them. Finish
+by re-running the gates and the project's typecheck.

package/files/shared/agents-section.md

@@ -2,5 +2,7 @@
 
 - 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>`. 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`.
+- 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 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

@@ -78,10 +78,14 @@ 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. Do not `try/catch` `NotReadyError` around a read, and do not
+    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 indicator). "Prop with local edits" = writable derivation:
+    `<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 }}>`
@@ -139,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
@@ -157,7 +165,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     cross an async gap default to `action` + `createOptimistic`/`createOptimisticStore` —
     except reactive clients (e.g. Convex) whose subscriptions already push authoritative
     state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
-    Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`). Server vs browser:
+    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:
     `isServer` / `isDev` from `@solidjs/web`, or `clientOnly(() => import("./Widget"))` for
     browser-only components — never `typeof window` as the SSR boundary. Default
     `clientOnly` starts loading at declaration; `{ lazy: true }` defers until first
@@ -175,9 +185,13 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     fallback body), not event-time mutations. `JSON.stringify(store)`
     / `structuredClone(store)` without `snapshot(store)` can throw or leak proxies. Async SSR
     without `<Loading>` *works* but blocks the HTML shell until every read settles — wrap
-    reads, or stream with `renderToStream`.
-    Navigation-shaped updates (a setter, then async computeds holding previous values)
+    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>` —
@@ -199,8 +213,17 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `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`.
+    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
 
@@ -264,6 +287,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,7 +67,8 @@ 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) |
+| 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()` |
@@ -199,7 +200,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 (`const View = tab() ? A : B` freezes the choice at setup).
-`<Dynamic>` is the JSX spelling of the same primitive.
+`<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)
 
@@ -245,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
@@ -524,6 +529,10 @@ test('increments on click', () => {
 `jsxImportSource` for tests and app code is `"@solidjs/web"`, not `"solid-js"`.
 Vite plugin is `@solidjs/vite-plugin`, not `vite-plugin-solid`.
 
+To turn those dev diagnostics into a hard gate, patch `console.warn` in the test setup
+file to rethrow unexpected warnings — then any top-level reactive read or unowned write
+an agent sneaks in fails the suite instead of scrolling by.
+
 ## App stack (only if the project has these packages)
 
 This kit's always-applied rules cover `solid-js` + `@solidjs/web` TSX. Official
@@ -634,7 +643,10 @@ 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 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).
 
@@ -656,7 +668,11 @@ 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
@@ -676,8 +692,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
 
@@ -742,7 +762,7 @@ how to reuse. Prefer the form on the right.
 | `<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 |
+| `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` |
@@ -753,6 +773,27 @@ how to reuse. Prefer the form on the right.
 | `{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
@@ -832,6 +873,16 @@ render(<App />, document.getElementById('app')!);
 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;
@@ -872,8 +923,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.
@@ -889,8 +942,11 @@ always-applied rules installed alongside this skill.
       `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(...)`).
+      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.
+- [ ] `solid2-kit check` and the project's typecheck pass; `solid2-kit doctor` too if
+      `package.json`, tsconfig, or root config files changed.

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

@@ -99,6 +99,7 @@ read these before writing route JSX.
 - 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)
 
@@ -138,9 +139,12 @@ read these before writing route JSX.
 - 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
 
@@ -148,10 +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.4",
+  "version": "0.7.0",
   "description": "Teach AI coding agents (Cursor, Claude Code) to write correct Solid 2.0 instead of React or Solid 1.x — always-applied rules, an agent skill, and a mechanical pattern gate.",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "check:drift": "node scripts/check-docs-drift.mjs",
-    "test": "node tests/check.test.mjs"
+    "test": "node tests/check.test.mjs && node tests/hook.test.mjs && node tests/doctor.test.mjs && node tests/init.test.mjs"
   },
   "engines": {
     "node": ">=18"