@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/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/shared/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/shared/react/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: react
+description: "Use when building or reviewing a client-side React SPA bundled by Vite (React 19.2): components, where state lives, hooks, server data fetching, client routing, re-render and effect bugs. NOT App Router / server components / SSR (that is `nextjs`); NOT native screens (that is `react-native`)."
+tags: [react, vite, spa, frontend, hooks, tanstack-query]
+recommends: [typescript, design, testing-web]
+origin: ai-hub
+---
+
+# React + Vite SPA — Components, State, Data Fetching (React 19.2, 2026)
+
+**Hand-off — picking dependencies.** Which library to reach for (UI primitives, command menus,
+toasts, OTP inputs, charts, virtualization, drag and drop, state, styling, theming) is
+`../ui-engineering/SKILL.md`'s — build vs adopt is decided there, before hand-rolling a component. The look of a page
+or screen, and its motion layer, is `../design/SKILL.md`'s.
+
+
+> Build or review a fast, typed, correctly-architected **client-side** React single-page app bundled by Vite. No server runtime, no React Server Components tree, no framework router. Server-rendered React (App Router, server actions, SSR/SSG) is not this skill — that is `../nextjs/SKILL.md`.
+
+**SDD gate — before writing feature code.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, stop and hand off to `../specify/SKILL.md`: it runs brainstorm → spec → plan → tasks, then routes back here once the plan is approved. Build directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
+
+## First: confirm it's a Vite SPA, not a framework
+
+Read `package.json` before giving any advice — it stops you applying SSR/React Server Components patterns to a client SPA.
+
+| Signal in package.json                | Read it as            | Where                  |
+| ------------------------------------- | --------------------- | ---------------------- |
+| `vite` + `react`, no `next`           | Vite SPA              | here                   |
+| `next`                                | metaframework / React Server Components   | `../nextjs/SKILL.md`   |
+| `@react-router/dev`                   | RR framework mode/SSR (Remix successor) | `../nextjs/SKILL.md`-shape |
+| `react-router` only                   | RR library mode       | here (Routing)         |
+| `expo` / `react-native`               | native                | `../react-native/SKILL.md` |
+
+Then pick the data layer (**TanStack Query**, always) and the router (React Router v7 library mode *or* TanStack Router).
+
+Adjacent jobs route out: 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`.
+
+## 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)                        |
+
+```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. 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 (useSuspenseQuery, below)
+```
+
+- **`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.
+- Query-key factory, `invalidateQueries` vs `setQueryData`, infinite queries, prefetch, Zustand store + selectors, the full Bad→Good set → `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.
+- Nested/lazy routes, client loaders, protected-route wrapper, `useSearchParams`-as-state → `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. Profiler workflow, React Compiler Vite setup, bundle analysis, re-render map → `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
+
+| Anti-pattern                                          | 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                                 |
+
+## 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**. 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.
+
+## 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/`.

package/skills/shared/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/shared/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 / React Server Components — 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)"

package/skills/shared/react/references/data-and-state.md

@@ -0,0 +1,152 @@
+# Data & state — TanStack Query v5 + client state
+
+The SPA rule: **server data lives in the TanStack Query cache, client data lives in `useState`/store/URL.** Never put fetched data in `useState` synced by `useEffect`.
+
+## Query-key factory
+
+Keep keys consistent so invalidation hits exactly what you mean. A small factory beats stringly-typed keys scattered across files.
+
+```ts
+export const userKeys = {
+  all: ["users"] as const,
+  list: (filters: UserFilters) => [...userKeys.all, "list", filters] as const,
+  detail: (id: string) => [...userKeys.all, "detail", id] as const,
+};
+```
+
+## useQuery
+
+```tsx
+const { data, isPending, isError, error, refetch } = useQuery({
+  queryKey: userKeys.list(filters),
+  queryFn: () => api.listUsers(filters),
+  staleTime: 60_000,        // fresh for 1 min → no refetch on remount/focus within window
+  gcTime: 5 * 60_000,        // unused cache evicted after 5 min
+  placeholderData: (prev) => prev, // keep prior page visible while the next loads (pagination)
+});
+```
+
+- `staleTime` is the single biggest lever against over-fetching. Default `0` means refetch on every mount/focus.
+- Render states explicitly: `isPending` (no data yet) → spinner; `isError` → message + retry; else data.
+
+## Mutations: invalidate vs setQueryData
+
+```tsx
+const qc = useQueryClient();
+
+// Simplest correct pattern: invalidate, let the query refetch the truth.
+const create = useMutation({
+  mutationFn: api.createUser,
+  onSuccess: () => qc.invalidateQueries({ queryKey: userKeys.all }),
+});
+
+// When you already have the server's response, write it directly (one less round-trip).
+const update = useMutation({
+  mutationFn: api.updateUser,
+  onSuccess: (saved) => qc.setQueryData(userKeys.detail(saved.id), saved),
+});
+```
+
+Rule of thumb: **invalidate** when the server is the source of truth and a refetch is cheap; **`setQueryData`** when the mutation already returns the canonical object.
+
+## Optimistic update (delete with rollback)
+
+```tsx
+const remove = useMutation({
+  mutationFn: api.deleteUser,
+  onMutate: async (id: string) => {
+    await qc.cancelQueries({ queryKey: userKeys.all });      // stop in-flight refetches
+    const prev = qc.getQueryData<User[]>(userKeys.list(filters));
+    qc.setQueryData<User[]>(userKeys.list(filters),
+      (old) => old?.filter((u) => u.id !== id) ?? []);        // optimistic write
+    return { prev };                                           // context for rollback
+  },
+  onError: (_e, _id, ctx) => {
+    if (ctx?.prev) qc.setQueryData(userKeys.list(filters), ctx.prev); // rollback
+  },
+  onSettled: () => qc.invalidateQueries({ queryKey: userKeys.all }),  // reconcile with server
+});
+```
+
+The trio is non-negotiable: `onMutate` (snapshot + write), `onError` (restore the snapshot), `onSettled` (refetch the truth).
+
+## useSuspenseQuery + boundaries
+
+Move loading/error out of the component body.
+
+```tsx
+function Users() {
+  const { data } = useSuspenseQuery({ queryKey: userKeys.all, queryFn: api.listUsers });
+  return <List items={data} />; // data is never undefined here
+}
+
+<ErrorBoundary fallback={<Failed />}>
+  <Suspense fallback={<Skeleton />}>
+    <Users />
+  </Suspense>
+</ErrorBoundary>
+```
+
+This is also the correct promise source for a bare `use()` call — the cache owns a stable promise, so render doesn't loop.
+
+## Infinite & prefetch
+
+```tsx
+const q = useInfiniteQuery({
+  queryKey: userKeys.all,
+  queryFn: ({ pageParam }) => api.listUsers({ cursor: pageParam }),
+  initialPageParam: null,
+  getNextPageParam: (last) => last.nextCursor ?? undefined,
+});
+
+// Warm the cache before navigation (e.g. on hover):
+await qc.prefetchQuery({ queryKey: userKeys.detail(id), queryFn: () => api.getUser(id) });
+```
+
+## Client state — Zustand with narrow selectors
+
+```ts
+const useCart = create<CartState>((set) => ({
+  items: [],
+  add: (item) => set((s) => ({ items: [...s.items, item] })),
+}));
+
+// Bad: subscribes to the whole store → re-renders on any change
+const store = useCart();
+// Good: subscribe to one slice → re-renders only when count changes
+const count = useCart((s) => s.items.length);
+```
+
+## Context — wide reads, low write frequency
+
+```tsx
+const ThemeContext = createContext<Theme>("light");
+// React 19: the context value IS the provider
+<ThemeContext value={theme}>{children}</ThemeContext>
+```
+
+Do not put rapidly-changing values (mouse position, form keystrokes) in context — every consumer re-renders. Use a store with selectors instead.
+
+## Bad → Good catalog
+
+```tsx
+// Bad: derived state mirrored into useState + effect
+const [total, setTotal] = useState(0);
+useEffect(() => setTotal(items.reduce((s, i) => s + i.price, 0)), [items]);
+// Good
+const total = items.reduce((s, i) => s + i.price, 0);
+```
+
+```tsx
+// Bad: fetch on mount with effect (race + no cache + Strict-Mode double-fire)
+useEffect(() => { fetch(url).then(r => r.json()).then(setData); }, [url]);
+// Good
+const { data } = useQuery({ queryKey: [url], queryFn: () => fetch(url).then(r => r.json()) });
+```
+
+```tsx
+// Bad: resetting child state on prop change with an effect
+useEffect(() => setDraft(initial), [initial]);
+// Good: remount the subtree with a key
+<Editor key={initial.id} initial={initial} />
+```