rsc-universal 0.1.1

package/skills/railway/references/config-as-code.md

@@ -0,0 +1,120 @@
+# railway.json / railway.toml — full field reference
+
+Config as code lives in `railway.json` **or** `railway.toml` at the service root. The fields a
+file sets **override the dashboard**; per-environment overrides nest under `environments.<name>`
+and take precedence over the base config. Schema: `https://railway.com/railway.schema.json`.
+
+Precedence, highest to lowest: `environments.<active>.*` → base file config → dashboard.
+
+## Build section
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `builder` | `RAILPACK` \| `DOCKERFILE` | Default `RAILPACK` (successor to Nixpacks). A Dockerfile is auto-detected; `DOCKERFILE` forces it. |
+| `buildCommand` | string | Overrides the inferred build step. |
+| `watchPatterns` | string[] | Glob paths that, when changed, trigger a rebuild on auto-deploy (e.g. `["src/**"]`). |
+| `dockerfilePath` | string | Path to the Dockerfile when not at root (with `builder: DOCKERFILE`). |
+| `railpackVersion` | string | Pin the Railpack version for reproducible builds. |
+
+## Deploy section
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `startCommand` | string | Command to run the service. Set this if Railpack can't infer it. |
+| `preDeployCommand` | string | Runs once before the new version goes live (e.g. DB migration). |
+| `healthcheckPath` | string | Path Railway polls before marking the deploy healthy (e.g. `/healthz`). Must return 2xx. |
+| `healthcheckTimeout` | number (s) | How long to wait for the healthcheck to pass before failing the deploy. |
+| `restartPolicyType` | `ON_FAILURE` \| `ALWAYS` \| `NEVER` | What to do when the container exits. |
+| `restartPolicyMaxRetries` | number | Cap on restart attempts under `ON_FAILURE`. |
+| `numReplicas` | number | Horizontal replica count. Incompatible with an attached volume (volume pins to 1). |
+| `multiRegionConfig` | object | Per-region replica config for multi-region deploys. |
+| `cronSchedule` | string (cron) | Run the service as a cron job on this schedule instead of long-running. |
+| `overlapSeconds` | number | Seconds the old + new versions overlap during a deploy (zero-downtime tuning). |
+| `drainingSeconds` | number | Grace period to drain in-flight requests before the old version is killed. |
+
+## JSON variant
+
+```jsonc
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "RAILPACK",
+    "buildCommand": "npm run build",
+    "watchPatterns": ["src/**", "package.json"]
+  },
+  "deploy": {
+    "startCommand": "node dist/server.js",
+    "preDeployCommand": "npm run migrate:deploy",
+    "healthcheckPath": "/healthz",
+    "healthcheckTimeout": 300,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 10,
+    "overlapSeconds": 20,
+    "drainingSeconds": 15
+  },
+  "environments": {
+    "production": {
+      "deploy": { "numReplicas": 2 }
+    },
+    "staging": {
+      "build": { "buildCommand": "npm run build:staging" },
+      "deploy": { "numReplicas": 1 }
+    }
+  }
+}
+```
+
+## TOML variant (same fields)
+
+```toml
+"$schema" = "https://railway.com/railway.schema.json"
+
+[build]
+builder = "RAILPACK"
+buildCommand = "npm run build"
+watchPatterns = ["src/**", "package.json"]
+
+[deploy]
+startCommand = "node dist/server.js"
+preDeployCommand = "npm run migrate:deploy"
+healthcheckPath = "/healthz"
+healthcheckTimeout = 300
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 10
+overlapSeconds = 20
+drainingSeconds = 15
+
+[environments.production.deploy]
+numReplicas = 2
+
+[environments.staging.build]
+buildCommand = "npm run build:staging"
+
+[environments.staging.deploy]
+numReplicas = 1
+```
+
+## Dockerfile builds
+
+```jsonc
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "docker/Dockerfile.prod"
+  },
+  "deploy": { "startCommand": "" }
+}
+```
+
+With `DOCKERFILE`, the image's `CMD`/`ENTRYPOINT` drives startup; leave `startCommand` empty
+unless you intend to override it. For Dockerfile authoring itself, see the `docker` and
+`deployment` skills — this reference only covers wiring it into Railway.
+
+## Notes
+
+- Never inline secrets here. Anything sensitive belongs in variables, referenced as
+  `${{Service.VAR}}`. The config file is committed to the repo.
+- `cronSchedule` turns a service into a scheduled job; it should exit when done rather than
+  staying resident.
+- A volume forces a single replica — do not set `numReplicas > 1` on a service with a volume.

package/skills/railway/scripts/verify.sh

@@ -0,0 +1,162 @@
+#!/usr/bin/env bash
+set -eu
+
+# Usage: bash scripts/verify.sh [DIR]
+# Structurally lints a railway.json (or railway.toml) in DIR (default: cwd).
+# Read-only: never writes, never installs, never calls the Railway API.
+#
+# Behavior:
+#   - No railway.json AND no railway.toml present -> PASS (no-op). Using Railway purely
+#     via CLI/dashboard is valid; absence is not a failure.
+#   - railway.json present -> validate it parses as JSON, that build.builder is an allowed
+#     enum, deploy.restartPolicyType is allowed, healthcheck fields are well-typed, and WARN
+#     (non-fatal) on values that look like inlined secrets (secrets belong in variables).
+#   - railway.toml present (and no json) -> shallow secret/enum sanity scan only (no TOML parser
+#     assumed). Never fails on toml structure.
+# Exit non-zero ONLY on JSON parse error or an invalid enum value. Warnings never fail.
+# Portable to stock macOS bash 3.2.
+
+DIR="${1:-.}"
+
+if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
+  YELLOW="$(tput setaf 3)"; RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; RESET="$(tput sgr0)"
+else
+  YELLOW=""; RED=""; GREEN=""; RESET=""
+fi
+
+rc=0
+warn() { printf '%s[WARN]%s %s\n' "$YELLOW" "$RESET" "$1" >&2; }
+info() { printf '[INFO] %s\n' "$1"; }
+fail() { printf '%s[FAIL]%s %s\n' "$RED" "$RESET" "$1" >&2; rc=1; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+JSON="$DIR/railway.json"
+TOML="$DIR/railway.toml"
+
+if [ ! -f "$JSON" ] && [ ! -f "$TOML" ]; then
+  info "no railway.json or railway.toml in '$DIR'; nothing to lint (CLI/dashboard-only use is valid)"
+  printf '%sverify.sh: OK%s\n' "$GREEN" "$RESET"
+  exit 0
+fi
+
+# --- secret heuristic: warn if a value looks like a credential ---------------
+# postgres:// or mysql:// or redis:// or mongodb:// URLs with creds, sk- keys, long base64.
+secret_scan() {
+  f="$1"
+  if grep -Eq '(postgres(ql)?|mysql|redis|mongodb)(\+srv)?://[^"[:space:]]*:[^"@[:space:]]+@' "$f"; then
+    warn "$f: a value looks like a connection string with credentials — secrets belong in variables, not config"
+  fi
+  if grep -Eq '(sk-[A-Za-z0-9]{16,}|AKIA[0-9A-Z]{12,}|ghp_[A-Za-z0-9]{20,})' "$f"; then
+    warn "$f: a value looks like an API key/token — move it to a Railway variable"
+  fi
+}
+
+# --- JSON path ---------------------------------------------------------------
+if [ -f "$JSON" ]; then
+  info "linting $JSON"
+
+  # 1. Parse + enum checks via python3 (preferred) or fall back to lenient grep.
+  # Python ALWAYS exits 0 and reports outcome on a leading STATUS: line, so the
+  # command substitution never trips `set -e`. STATUS is OK | PARSE | ENUM.
+  if have python3; then
+    py_out="$(python3 - "$JSON" <<'PY'
+import json, sys
+path = sys.argv[1]
+try:
+    with open(path) as fh:
+        cfg = json.load(fh)
+except Exception as e:
+    print("STATUS:PARSE")
+    print("  %s" % e)
+    sys.exit(0)
+
+if not isinstance(cfg, dict):
+    print("STATUS:PARSE")
+    print("  top-level value is not an object")
+    sys.exit(0)
+
+errs = []
+build = cfg.get("build") or {}
+deploy = cfg.get("deploy") or {}
+
+b = build.get("builder")
+if b is not None and b not in ("RAILPACK", "DOCKERFILE"):
+    errs.append("build.builder=%r not in {RAILPACK, DOCKERFILE}" % b)
+
+r = deploy.get("restartPolicyType")
+if r is not None and r not in ("ON_FAILURE", "ALWAYS", "NEVER"):
+    errs.append("deploy.restartPolicyType=%r not in {ON_FAILURE, ALWAYS, NEVER}" % r)
+
+hp = deploy.get("healthcheckPath")
+if hp is not None and not isinstance(hp, str):
+    errs.append("deploy.healthcheckPath must be a string")
+
+for nf in ("healthcheckTimeout", "restartPolicyMaxRetries", "numReplicas",
+           "overlapSeconds", "drainingSeconds"):
+    v = deploy.get(nf)
+    if v is not None and (isinstance(v, bool) or not isinstance(v, (int, float))):
+        errs.append("deploy.%s must be a number" % nf)
+
+if errs:
+    print("STATUS:ENUM")
+    for e in errs:
+        print("  " + e)
+    sys.exit(0)
+print("STATUS:OK")
+sys.exit(0)
+PY
+)" || py_out="STATUS:PARSE
+  python3 invocation failed"
+    pstatus="$(printf '%s\n' "$py_out" | head -1)"
+    pdetail="$(printf '%s\n' "$py_out" | tail -n +2)"
+    case "$pstatus" in
+      STATUS:OK)
+        info "$JSON: parses; builder and restartPolicyType enums OK" ;;
+      STATUS:PARSE)
+        fail "$JSON: invalid JSON"
+        [ -n "$pdetail" ] && printf '%s\n' "$pdetail" >&2 ;;
+      STATUS:ENUM)
+        [ -n "$pdetail" ] && printf '%s\n' "$pdetail" >&2
+        fail "$JSON: invalid enum / field type (see above)" ;;
+      *)
+        fail "$JSON: unexpected lint output: $py_out" ;;
+    esac
+  elif have jq; then
+    if ! jq empty "$JSON" >/dev/null 2>&1; then
+      fail "$JSON: invalid JSON (jq could not parse)"
+    else
+      b="$(jq -r '.build.builder // empty' "$JSON" 2>/dev/null || true)"
+      case "$b" in ""|RAILPACK|DOCKERFILE) : ;; *) fail "$JSON: build.builder=$b not in {RAILPACK, DOCKERFILE}";; esac
+      r="$(jq -r '.deploy.restartPolicyType // empty' "$JSON" 2>/dev/null || true)"
+      case "$r" in ""|ON_FAILURE|ALWAYS|NEVER) : ;; *) fail "$JSON: deploy.restartPolicyType=$r not in {ON_FAILURE, ALWAYS, NEVER}";; esac
+      [ "$rc" -eq 0 ] && info "$JSON: parses (jq); enums OK"
+    fi
+  else
+    warn "neither python3 nor jq found; skipping JSON parse/enum checks (run on a host with one)"
+  fi
+
+  secret_scan "$JSON"
+fi
+
+# --- TOML path (only if no JSON) ---------------------------------------------
+if [ ! -f "$JSON" ] && [ -f "$TOML" ]; then
+  info "linting $TOML (shallow: no TOML parser assumed)"
+  b="$(grep -E '^[[:space:]]*builder[[:space:]]*=' "$TOML" | head -1 | sed 's/.*=[[:space:]]*//; s/"//g; s/[[:space:]]*$//' || true)"
+  case "$b" in
+    ""|RAILPACK|DOCKERFILE) [ -n "$b" ] && info "builder=$b OK" || : ;;
+    *) fail "$TOML: builder=$b not in {RAILPACK, DOCKERFILE}";;
+  esac
+  r="$(grep -E '^[[:space:]]*restartPolicyType[[:space:]]*=' "$TOML" | head -1 | sed 's/.*=[[:space:]]*//; s/"//g; s/[[:space:]]*$//' || true)"
+  case "$r" in
+    ""|ON_FAILURE|ALWAYS|NEVER) [ -n "$r" ] && info "restartPolicyType=$r OK" || : ;;
+    *) fail "$TOML: restartPolicyType=$r not in {ON_FAILURE, ALWAYS, NEVER}";;
+  esac
+  secret_scan "$TOML"
+fi
+
+if [ "$rc" -ne 0 ]; then
+  printf '%sverify.sh: FAILED%s\n' "$RED" "$RESET" >&2
+  exit "$rc"
+fi
+printf '%sverify.sh: OK%s\n' "$GREEN" "$RESET"
+exit 0

package/skills/react/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: react
+description: "Use when building or reviewing a client-side React SPA on Vite (React 19.2 — components, where state lives, hooks, client routing, server data fetching) and NOT server-rendered React. Triggers: 'React + Vite app', 'I'm fetching in useEffect and it fires twice', 'where should this filter state live', 'my list flickers and the wrong row updates', 'set up React Router', 'cómo hago data fetching en React sin useEffect', 'per què es re-renderitza tot l'arbre'. NOT App Router / server components / SSR (that is nextjs); NOT mobile screens (that is react-native)."
+tags: [react, vite, spa, frontend, hooks, tanstack-query]
+recommends: [typescript, design, testing-web]
+origin: risco
+---
+
+# React + Vite SPA — Components, State, Data Fetching (React 19.2, 2026)
+
+> Build or review a fast, typed, correctly-architected **client-side** React single-page app bundled by Vite. No server runtime, no RSC tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is `../nextjs/SKILL.md`.
+
+## When to use
+
+- A repo with `vite.config.{ts,js}` + `react` + `react-dom` and **no** `next` and **no** `@react-router/dev` framework mode — i.e. an SPA.
+- Creating components and deciding **where state lives** (local / lifted / URL / context / store).
+- Wiring **server data**: queries, mutations, caching, optimistic UI.
+- Client routing (React Router v7 *library mode* or TanStack Router).
+- Fixing re-render storms, stale closures, effect misuse, `key` bugs.
+- Setting up the Vite project (aliases, env vars, code-splitting, `dist/` build).
+
+## When NOT to use — route it
+
+- Server Components, server actions, App Router, SSR/SSG, `app/` dir → `../nextjs/SKILL.md`.
+- React Native / Expo / native screens → `../react-native/SKILL.md`.
+- The type system itself (generics, discriminated unions, `tsconfig` theory) with no React shape → `../typescript/SKILL.md`.
+- Visual design, tokens, spacing, button states → `../design/SKILL.md`.
+- Writing the Vitest/RTL or E2E suite as the task → `../testing-web/SKILL.md`.
+- Hosting the built `dist/` → `../deployment/SKILL.md`.
+
+## First: confirm it's a Vite SPA, not a framework
+
+Do this before giving any advice — it stops you applying SSR/RSC patterns to a client SPA.
+
+1. Read `package.json`. `vite` + `react` present? Good.
+2. Is `next` present? → stop, use `../nextjs/SKILL.md`.
+3. Is `@react-router/dev` present (React Router **framework mode** = SSR, Remix successor)? → that is out of scope, closer to nextjs-shape. Library mode (`react-router` / `react-router-dom` alone) stays here.
+4. Pick the data layer (**TanStack Query**, always — see §6) and the router (React Router v7 library mode *or* TanStack Router).
+
+| Signal in package.json                | Read it as            | Where                  |
+| ------------------------------------- | --------------------- | ---------------------- |
+| `vite` + `react`, no `next`           | Vite SPA              | here                   |
+| `next`                                | metaframework / RSC   | `../nextjs/SKILL.md`   |
+| `@react-router/dev`                   | RR framework mode/SSR | `../nextjs/SKILL.md`-shape |
+| `react-router` only                   | RR library mode       | here (§7)              |
+| `expo` / `react-native`               | native               | `../react-native/SKILL.md` |
+
+## Component & state architecture
+
+- **Colocate state** next to where it's used; only **lift** when two siblings must share it. Lifting earlier than needed is the #1 cause of re-render spread.
+- **Derive, don't duplicate.** If a value is computable from props/state, compute it in render — never mirror it into another `useState` synced by an effect.
+- **Context for low-frequency, wide values** (theme, current user, locale). It re-renders every consumer on every change.
+- **External store (Zustand) for high-frequency global state** read by many components; subscribe with **narrow selectors** so only readers of a slice re-render.
+- **URL is state too.** Filters, tabs, pagination belong in search params so they're shareable and survive reload.
+
+| Where does this state live?            | Trigger                                                        |
+| -------------------------------------- | ------------------------------------------------------------- |
+| Local `useState`/`useReducer`          | only one component cares                                       |
+| Lifted to nearest common parent        | a few siblings share it                                       |
+| URL search params                       | it should be shareable / bookmarkable / survive reload         |
+| Context                                 | wide read, **low** write frequency (theme, auth user)          |
+| External store (Zustand) + selectors    | wide read, **high** write frequency, or deep prop-drilling     |
+| TanStack Query cache                    | it's **server** data (anything fetched) — see §6               |
+
+```tsx
+// Bad: syncing a derived value into state with an effect → stale + extra render
+const [fullName, setFullName] = useState("");
+useEffect(() => { setFullName(`${first} ${last}`); }, [first, last]);
+
+// Good: derive in render
+const fullName = `${first} ${last}`;
+```
+
+## Hooks discipline (React 19.2)
+
+- `useState` for one or two independent values; `useReducer` when the next state depends on the previous one or several fields move together.
+- **The `useEffect` rule:** effects exist to *synchronize with a non-React external system* (a subscription, a DOM node, a non-React widget). They are **not** for transforming data and **not** for fetching server data (§6). If you can compute it in render or in an event handler, do that instead.
+- **`useEffectEvent`** (stable in 19.2): extract the non-reactive part of an effect so it reads the latest props/state without being a dependency. Fixes the stale-closure / over-firing class of effect bug.
+
+```tsx
+// Effect re-subscribes only when roomId changes, but still logs the latest theme.
+const onConnected = useEffectEvent(() => log("connected", theme));
+useEffect(() => {
+  const c = connect(roomId);
+  c.on("open", onConnected);
+  return () => c.close();
+}, [roomId]); // theme is NOT a dependency
+```
+
+- **`use(promise)`** reads a promise during render under `<Suspense>` + an error boundary. The promise **must** come from a cache (TanStack Query, a stable module cache) — never created inline, or you make a new promise every render and suspend forever.
+
+```tsx
+// Bad: new promise each render → infinite suspense loop
+function Profile({ id }: { id: string }) {
+  const user = use(fetch(`/api/users/${id}`).then(r => r.json())); // ❌
+}
+// Good: the promise is owned by a cache (see §6 useSuspenseQuery)
+```
+
+- **`useTransition` / `useDeferredValue`** keep the UI responsive: mark a slow state update non-urgent so typing/clicks stay live.
+- **`ref` is a plain prop** in React 19 — no `forwardRef`. The provider is `<Context value={...}>` (no `.Provider`). Refs may return a cleanup function.
+
+## Data fetching — TanStack Query, not useEffect (the headline rule)
+
+Fetching server data in `useEffect` gives you waterfalls, race conditions, no caching, no dedupe, and double-fires under Strict Mode. Use **TanStack Query v5** for *all* server state.
+
+```tsx
+// Bad: the effect-as-fetch anti-pattern — races, no cache, refetches on every mount
+const [user, setUser] = useState<User | null>(null);
+useEffect(() => {
+  fetch(`/api/users/${id}`).then(r => r.json()).then(setUser); // ❌ stale id, race, no error/loading
+}, [id]);
+
+// Good
+const { data: user, isPending, isError } = useQuery({
+  queryKey: ["user", id],          // identity + cache key + dedupe
+  queryFn: () => getUser(id),       // typed fetcher
+  staleTime: 60_000,                // 1 min "fresh" → no needless refetch
+});
+```
+
+- **Mutations** invalidate the cache so reads refetch:
+
+```tsx
+const qc = useQueryClient();
+const remove = useMutation({
+  mutationFn: deleteUser,
+  onSuccess: () => qc.invalidateQueries({ queryKey: ["users"] }),
+});
+```
+
+- **`useSuspenseQuery`** + `<Suspense fallback>` + an error boundary moves loading/error out of the component body and is the correct source for `use()`-style reads.
+- **Optimistic delete**: `onMutate` snapshots + writes the expected state, `onError` rolls back, `onSettled` invalidates. Full pattern (infinite, prefetch, query-key factory, optimistic) → `references/data-and-state.md`.
+
+## Routing (client-side)
+
+**React Router v7 — library mode** is the default SPA router:
+
+```tsx
+const router = createBrowserRouter([
+  { path: "/", element: <Layout />, children: [
+    { index: true, element: <Home /> },
+    { path: "users/:id", lazy: () => import("./routes/user") }, // code-split route
+  ]},
+]);
+// <RouterProvider router={router} />
+```
+
+- Use **lazy routes** so each route is its own chunk.
+- **TanStack Router** is the type-safe alternative — fully typed params/search, first-class loaders. Pick it when route/search typing matters.
+- `@react-router/dev` **framework mode** is SSR → treat like nextjs, out of scope.
+- Protected routes, `useSearchParams`-as-state, nested loaders → `references/routing.md`.
+
+## Performance
+
+**Measure first** with the React DevTools Profiler — guessing wastes effort. Then:
+
+- **Correct `key`**: a stable id, never the array index when the list can reorder/insert/delete (index keys leak state and update the wrong row — see anti-patterns).
+- **Virtualize** lists past ~50–100 rows with `@tanstack/react-virtual`.
+- **Code-split** routes and heavy components with `lazy()` + `<Suspense>`; Vite splits automatically on dynamic `import()`.
+- **React Compiler on** ⇒ delete manual `useMemo`/`useCallback`/`React.memo` — it auto-memoizes; leaving them in is dead noise.
+- **Narrow store selectors** so a slice change doesn't re-render the whole subtree.
+- Targets: LCP < 2.5s, INP < 200ms, CLS < 0.1. Deep dive → `references/performance.md`.
+
+## TypeScript + Vite project setup
+
+- Type props explicitly; no `any`. Turn on `strict` and `noUncheckedIndexedAccess` so `arr[i]` is `T | undefined`.
+- **Env & the secret-leak warning:** only `VITE_`-prefixed vars reach the client via `import.meta.env.VITE_*` — and **everything `VITE_` ships in the browser bundle**. A `VITE_API_SECRET` is public. Proxy real secrets through a backend.
+- Declare custom env vars in `vite-env.d.ts`.
+- Define path aliases in **both** `vite.config.ts` (`resolve.alias`) and `tsconfig.json` (`paths`) or imports break in one place.
+- `vite build` emits `dist/` — the deployable artifact. Deep types → `../typescript/SKILL.md`.
+
+## Anti-patterns → STOP
+
+| Rationalization                                       | Reality                                                                 | Do instead                                          |
+| ----------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
+| "Fetch in `useEffect`, it's simpler"                  | Waterfalls, races, double-fire, no cache/dedupe                          | `useQuery` / `useSuspenseQuery`                     |
+| "Create the promise inline for `use()`"               | New promise every render → suspends forever                              | Promise owned by a cache (TanStack Query)           |
+| "Index as `key`, the list looks fine"                 | On reorder/delete, state sticks to the wrong row, list flickers          | Stable id as `key`                                  |
+| "Put it in context so anyone can read it"             | High-write context re-renders the whole consumer tree                    | Zustand + narrow selector                           |
+| "Sync the prop into state with an effect"             | Duplicated, stale state + an extra render                                | Derive in render, or `key` to reset a subtree       |
+| "`useMemo`/`useCallback` everywhere for speed"        | Noise; with React Compiler it's redundant                                | Measure first; let the compiler memoize             |
+| "`VITE_API_SECRET` is fine, it's an env var"          | It ships in the browser bundle — fully public                            | Proxy the secret through a backend                  |
+| "`useEffect` to compute a derived value"              | Extra render + a stale window                                            | Recompute in render                                 |
+
+## Quick reference
+
+| Task                                | API / tool                                  | Note                                  |
+| ----------------------------------- | ------------------------------------------- | ------------------------------------- |
+| Server data                         | `useQuery`                                  | `queryKey` + `queryFn` + `staleTime`  |
+| Mutation                            | `useMutation` + `invalidateQueries`         | or optimistic `onMutate/onError/onSettled` |
+| Read a promise in render            | `use()` + `<Suspense>` + error boundary     | promise from a cache, never inline    |
+| High-frequency global state         | Zustand + selector                          | narrow the selector                   |
+| Wide, low-write state               | `<Context value>`                           | theme/auth, not server data           |
+| Keep UI responsive                  | `useTransition` / `useDeferredValue`        | mark slow update non-urgent           |
+| Non-reactive logic inside an effect | `useEffectEvent`                            | reads latest, not a dependency        |
+| Client route                        | `createBrowserRouter` + `RouterProvider`    | lazy routes for splitting             |
+| Code-split                          | `lazy()` + `<Suspense>`                      | Vite splits on dynamic `import()`     |
+| Build                               | `vite build`                                | emits `dist/`                         |
+
+## Verify
+
+`scripts/verify.sh` runs from the project root: **ESLint → `tsc --noEmit` → Vitest → `vite build`**, in that order. Each tool is detected and **skipped with a warning (never a failure) if absent** — a repo without a tool can't fail a command it doesn't have. The final `vite build` writes `dist/`; the lint/type/test steps are read-only. No installs, no network mutations, safe to re-run. It exits non-zero only on a real tool failure, and exits 0 on a clean/empty target.
+
+## References
+
+- `references/data-and-state.md` — TanStack Query v5 in depth (query-key factory, mutations, `invalidateQueries` vs `setQueryData`, optimistic with `onMutate/onError/onSettled`, `useSuspenseQuery`, infinite, prefetch), Zustand store + selectors, context patterns, full Bad→Good set.
+- `references/routing.md` — React Router v7 library mode (nested/lazy routes, client loaders, protected-route wrapper, `useSearchParams` as state) and the TanStack Router type-safe alternative; framework mode → defer.
+- `references/performance.md` — Profiler workflow, `key` bugs, `react-virtual`, code-splitting, React Compiler Vite setup, bundle analysis, narrow-selector re-render map.
+
+## Project grounding (02-DOCS)
+
+If the workspace has `02-DOCS/`, record stack-specific React conventions (chosen router, store, query defaults) in `02-DOCS/wiki/stack/react.md` and index it from `CLAUDE.md`. Recorded, not gated — skip silently if there is no `02-DOCS/`.
+
+## See also
+
+- `../nextjs/SKILL.md` — the SSR / RSC / App Router sibling (server-rendered React).
+- `../react-native/SKILL.md` — native mobile React.
+- `../typescript/SKILL.md` — the type system itself.
+- `../design/SKILL.md` — visual design, tokens, component states.
+- `../testing-web/SKILL.md` — Vitest/RTL test authoring.
+- `../deployment/SKILL.md` — hosting the built `dist/`.

package/skills/react/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — react
+
+These cases document the trigger boundary for the `react` skill: a **client-side React SPA on Vite**, as distinct from server-rendered React (`nextjs`), native mobile (`react-native`), pure type theory (`typescript`), visual design (`design`), and test authoring (`testing-web`). Read `cases.yaml` as the routing contract, or feed `should_trigger` / `should_not_trigger` prompts through your skill-eval harness to check that selection lands here for SPA work and routes elsewhere otherwise. The `capability` case is graded by a human (or a judge model) against its `must_include` rubric — it is not auto-run; the rubric is the bar for a correct answer (TanStack Query over useEffect, explicit loading/error states, optimistic mutation, stable keys, typed data).

package/skills/react/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: react
+
+should_trigger:
+  - prompt: "Build a product list component in my React + Vite app"
+    why: "Core case — composing components in a client-side Vite SPA."
+  - prompt: "I'm fetching the user in a useEffect and it fires twice and races"
+    why: "The headline smell — server fetching in useEffect; route to TanStack Query."
+  - prompt: "Where should this filter state live — local, context, or a store?"
+    why: "State-location decision, the architecture spine of the skill."
+  - prompt: "My list flickers and the wrong row updates when I delete one"
+    why: "Non-obvious: an index-as-key / state bug, with no React or 'key' mentioned in the prompt."
+  - prompt: "Set up client-side routing with React Router in my Vite SPA"
+    why: "React Router v7 library mode setup, in scope."
+  - prompt: "Cómo hago data fetching en React sin useEffect"
+    why: "Spanish phrasing of the headline rule (TanStack Query, not useEffect)."
+  - prompt: "Per què es re-renderitza tot l'arbre quan canvio un sol camp del context?"
+    why: "Catalan; high-write context re-render problem → store with selectors."
+
+should_not_trigger:
+  - prompt: "Add a server action and revalidate the cache in my app/ route"
+    route_to: nextjs
+    why: "Server actions / App Router / RSC — server-rendered React, not a Vite SPA."
+  - prompt: "Build the profile screen in my Expo app"
+    route_to: react-native
+    why: "Native mobile rendering, not the DOM."
+  - prompt: "How do I make this generic discriminated-union type narrow properly"
+    route_to: typescript
+    why: "Pure type theory with no React component shape."
+  - prompt: "Design the hover, active and disabled states and spacing for our buttons"
+    route_to: design
+    why: "Visual design system / tokens, not React architecture."
+  - prompt: "Write a Vitest + RTL test suite for these components"
+    route_to: testing-web
+    why: "Test authoring is the task; this skill only notes testability."
+
+capability:
+  - scenario: "Build a paginated users list in a Vite React app: fetch from /api/users with loading and error states, plus an optimistic delete button per row."
+    must_include:
+      - "useQuery (or useSuspenseQuery) with queryKey + queryFn and a staleTime"
+      - "NO server data fetching inside useEffect"
+      - "useMutation with invalidateQueries OR optimistic onMutate/onError/onSettled"
+      - "explicit loading + error handling (isPending/isError, or Suspense + error boundary)"
+      - "typed props/data and a stable key (user id, not array index)"