rsc-universal 0.1.1

package/skills/performance/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: performance
+description: "Use when one page or route is slow for a single user and the fix has to start with a measurement — failing Core Web Vitals (LCP, INP, CLS), a bloated JS bundle, too many re-renders, slow hydration, or a profiler showing where the time actually goes. Triggers: 'my LCP is 4 seconds', 'the page feels janky, typing lags', 'First Load JS is huge', 'INP is failing in Search Console', the non-obvious 'we import the whole library for one function' and 'a use client boundary is shipping the server tree to the browser', and Catalan/Spanish 'la pàgina carrega lenta i no passa els Core Web Vitals' / 'el bundle pesa demasiado, hay que analizarlo antes de tocar nada'. NOT surviving a concurrent traffic spike with caches, replicas and load tests (that is scaling), NOT fixing the slow SQL query or N+1 itself (that is postgresdb)."
+tags: [performance, core-web-vitals, lcp, inp, cls, bundle-size, profiling, react, web-vitals]
+recommends: [scaling, postgresdb, redis, nextjs, react, observability, monitoring]
+profiles: []
+origin: risco
+---
+
+# Performance: make one thing fast
+
+Performance makes a single request, page, or interaction faster for one user. Scaling makes many requests survive at the same time. Different problem, different toolbox — if the system is fine for you and only bends under concurrent load, that is `../scaling/SKILL.md`, not this.
+
+The whole job in one line: **measure with a profiler → attribute the cost to one specific phase → apply the one fix that moves that phase → re-measure against a number.** Repeat until you clear the threshold, then stop.
+
+**Prime directive: no fix without a profile first.** A waterfall, a flame chart, a bundle treemap, or a field CWV number comes before you touch code. The fix you guess is almost never the fix the measurement points at, and a "fast" change that moves a phase nobody was waiting on is wasted work that you then have to maintain.
+
+Where the deep fix lives elsewhere — cross-reference, don't duplicate:
+
+- TTFB is the bottleneck because of a slow query or an N+1 → name it here, fix it in `../postgresdb/SKILL.md`.
+- You decided *what* to cache to cut a phase, now make the cache race-free → `../redis/SKILL.md`.
+- The problem only appears under concurrent load → `../scaling/SKILL.md`.
+- You need the canonical App-Router / component data pattern, not the perf loop → `../nextjs/SKILL.md`, `../react/SKILL.md`.
+
+## Decision table — symptom to first move
+
+| Symptom | Metric / phase | First probe | First lever | Deep fix lives in |
+|---|---|---|---|---|
+| Slow load, hero appears late | LCP | Lighthouse + DevTools trace | attribute to a subpart, then fix that one | this skill / `../postgresdb/SKILL.md` if TTFB |
+| Janky scroll, laggy typing/click | INP | DevTools Performance trace (long-task bars) | break the >50 ms task, yield | this skill |
+| Layout jumps as it loads | CLS | Lighthouse layout-shift trace | reserve space (dimensions / aspect-ratio) | this skill |
+| "First Load JS is huge" | bundle bytes | `@next/bundle-analyzer` / `source-map-explorer` | kill/replace the heavy dep, then dynamic import | this skill |
+| Component re-renders constantly | render time | React DevTools Profiler ("why did this render") | fix the unstable ref / boundary | `../react/SKILL.md` for the pattern |
+| `'use client'` drags server work down | First Load JS | bundle analyzer server/client trace | push the boundary to a leaf | `../nextjs/SKILL.md` |
+| Slow **only** under concurrent load | throughput, not latency | load test | — not this skill — | `../scaling/SKILL.md` |
+| TTFB dominated by one query | server time | query plan / `EXPLAIN` | — not this skill — | `../postgresdb/SKILL.md` |
+
+## Step 0 — measure first: field vs lab
+
+You have two kinds of measurement and they answer different questions. Use both, in this order.
+
+- **Field data (CrUX, RUM via the `web-vitals` library) at the 75th percentile** tells you *what real users actually feel*. A metric passes when ≥75% of page views hit "good". This is the only number that matters for "is it actually a problem".
+- **Lab data (Lighthouse, the Chrome DevTools Performance trace)** tells you *why* — it reproduces one load under controlled conditions so you can read the waterfall and flame chart.
+
+**Rule: never optimize a lab number that no real user ever hits, and never report the mean — report the 75th percentile.** A lab Lighthouse run on a throttled cold cache can show an LCP your field p75 never sees; chasing it burns time on a phantom. Conversely a field INP failure with a clean lab run means you have not reproduced the slow interaction yet — go find it.
+
+The output of Step 0 is **one sentence naming the bottleneck**: "LCP is 3.8 s and 2.1 s of it is resource load delay because the hero image is lazy-loaded." Do not proceed without that sentence. Tool runbooks (Lighthouse CI flags, reading a flame chart, the Profiler workflow, wiring `web-vitals` for RUM) live in `references/profiling-playbook.md`.
+
+## CWV "good" thresholds (field p75)
+
+| Metric | Good | Needs improvement | Poor |
+|---|---|---|---|
+| LCP | ≤ 2.5 s | 2.5–4.0 s | > 4.0 s |
+| INP | ≤ 200 ms | 200–500 ms | > 500 ms |
+| CLS | ≤ 0.1 | 0.1–0.25 | > 0.25 |
+
+INP replaced FID as a Core Web Vital in March 2024 and is still a CWV — it measures the full interaction-to-next-paint, so a fast event handler with a slow paint still fails. As of 2025, ~62% of mobile pages hit good LCP (up from 44% in 2022), and LCP remains the hardest CWV to pass and the most common overall bottleneck — so start there when the symptom is "slow load".
+
+## LCP — attribute to a subpart before fixing
+
+LCP is not one thing. It decomposes into four sequential phases, and **each phase has a different fix**. Attribute first, then fix only the dominant phase.
+
+| Subpart | What it is | The fix that moves it |
+|---|---|---|
+| TTFB | server + network to first byte | server work — punt to `../postgresdb/SKILL.md` (slow query) or `../scaling/SKILL.md` (under load); cache the response |
+| Resource load delay | gap between TTFB and the LCP resource *starting* to load | discoverability — `<link rel="preload">`, `fetchpriority="high"`, never lazy-load the hero |
+| Resource load duration | time to actually download the LCP resource | smaller/next-gen image, CDN, right dimensions, `priority` on `next/image` |
+| Element render delay | resource downloaded but not yet painted | unblock the main thread / render-blocking CSS/JS, font readiness |
+
+A text-node LCP rendered in a system font has zero load delay and zero load duration — its budget is all TTFB and render delay, so don't go hunting for an image to preload.
+
+The single most common LCP mistake is lazy-loading the largest element. Make it eager and high priority:
+
+```html
+<!-- Bad: the hero is the LCP element and you just deferred it -->
+<img src="/hero.webp" loading="lazy" alt="Product" />
+
+<!-- Good: eager + high priority + reserved dimensions (also kills CLS) -->
+<link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />
+<img src="/hero.webp" fetchpriority="high" width="1200" height="630" alt="Product" />
+```
+
+```tsx
+// Next.js: `priority` sets fetchpriority=high and disables lazy-loading for the LCP image
+import Image from "next/image";
+<Image src="/hero.webp" width={1200} height={630} priority alt="Product" />;
+```
+
+## INP — kill the long task
+
+INP is dominated by **long tasks**: any main-thread task over **50 ms** blocks every interaction for its full duration. The fix is to break long work into chunks under 50 ms and yield to the main thread between them so a queued click or keypress can run.
+
+```ts
+// Bad: one 400ms loop blocks every click/keypress while it runs
+function processAll(items: Item[]) {
+  for (const item of items) heavyWork(item); // one long task
+}
+
+// Good: chunk + yield. scheduler.yield() resumes at the FRONT of the queue,
+// so your continuation isn't starved behind newly-queued work.
+async function processAll(items: Item[]) {
+  for (let i = 0; i < items.length; i++) {
+    heavyWork(items[i]);
+    if (i % 50 === 0 && "scheduler" in globalThis) {
+      await (globalThis as any).scheduler.yield();
+    }
+  }
+}
+```
+
+Other INP levers, in order of payoff:
+
+- **Move third-party JS off the main thread** (analytics, chat widgets, tag managers) — defer, load on interaction, or sandbox in a worker. Third-party scripts are the usual hidden long-task source.
+- **Defer non-urgent handler work.** Do the visible state update now; push the expensive recompute behind `requestIdleCallback`, a debounce, or `startTransition`.
+- **Measure the actual interaction** — the field INP failure names *which* interaction; reproduce it in a DevTools trace and read the long-task bar, don't guess.
+
+## CLS — reserve the space
+
+CLS comes from space that was not reserved before content arrived: images/video/ads/embeds without dimensions, content injected above existing content, and font swaps (FOUT). Fix by reserving the box up front.
+
+```html
+<!-- Bad: no dimensions, image reflows everything below it on load -->
+<img src="/card.webp" alt="" />
+
+<!-- Good: explicit box, zero shift -->
+<img src="/card.webp" width="400" height="300" alt="" />
+```
+
+```css
+/* Reserve space for ratio-based media and swap fonts without reflow */
+.media { aspect-ratio: 16 / 9; }                 /* box exists before load */
+@font-face { font-family: Inter; font-display: optional; size-adjust: 100%; }
+```
+
+Rules: give every image/embed explicit `width`/`height` or an `aspect-ratio`; render skeleton boxes the size of the real content; never insert banners/notices above content the user is already reading (push them below or overlay); use `font-display: optional` (or `swap` + `size-adjust`) so a font swap doesn't reflow text.
+
+## Bundle size — analyze before you cut
+
+Never guess what's heavy. Generate a treemap, read it, then cut the biggest box.
+
+```bash
+# Next.js: interactive treemap with server/client import tracing (Turbopack module graph)
+ANALYZE=true npm run build      # with @next/bundle-analyzer wired in next.config
+
+# Any webpack/Vite build: attribute bytes back to source via source maps
+npx source-map-explorer 'dist/**/*.js'
+```
+
+Levers in order of payoff:
+
+1. **Kill or replace the heavy dependency.** The treemap usually shows one or two boxes dwarfing everything (a date library, an icon set, a charting lib). Replace with a lighter one or a few lines of your own.
+2. **Dynamic `import()` for non-critical UI.** Modals, editors, charts, anything below the fold or behind an interaction loads on demand instead of in First Load JS.
+3. **Fix tree-shaking — stop importing the whole library for one function.** `import _ from "lodash"` pulls the entire library; import the one function (or use the native equivalent).
+
+```tsx
+// Bad: whole library in the initial bundle for one helper
+import _ from "lodash";
+const fn = _.debounce(save, 300);
+
+// Good: named import (tree-shakeable) — or just write the 6-line debounce
+import debounce from "lodash-es/debounce";
+const fn = debounce(save, 300);
+```
+
+```tsx
+// Bad: heavy editor in First Load JS even though it's behind a button
+import { RichEditor } from "@org/rich-editor";
+
+// Good: split it out, load on demand
+import dynamic from "next/dynamic";
+const RichEditor = dynamic(() => import("@org/rich-editor"), { ssr: false });
+```
+
+## Render cost — React 19, the compiler, and the boundary
+
+**React 19 with the React Compiler auto-memoizes**, so blanket defensive `useMemo`/`useCallback`/`memo` is now an anti-pattern, not a best practice — it adds noise and the compiler already handles the common cases. Manual memo is the exception, and you justify it with a profile.
+
+- Profile with the **React DevTools Profiler**: record an interaction, find the component that re-rendered, read "why did this render" and its render time.
+- **The 16 ms rule:** one frame at 60 fps is ~16 ms. If a manual memo saves less than that, skip it — you can't see it and you're paying for the cache.
+- The compiler **cannot** fix a new object/array/function reference created in render and passed as a prop — that's a fresh identity every time. Hoist it or derive it stably; that's the real fix, not wrapping the consumer in `memo`.
+
+**RSC boundary discipline.** React Server Components ship zero JS for non-interactive trees; teams report 50–70% First-Load-JS cuts from full RSC adoption. The `'use client'` directive is a *boundary*: everything imported below it becomes client code. So push interactivity into the smallest leaf component and keep data fetching and layout on the server.
+
+```tsx
+// Bad: 'use client' at the top of the route — the whole tree ships to the browser
+"use client";
+export default function ProductPage({ data }) {
+  /* layout, data display, and one tiny button all client-side */
+}
+
+// Good: server component holds data/layout; only the interactive leaf is a client component
+export default function ProductPage({ data }) {       // server: zero JS
+  return (
+    <article>
+      <ProductDetails data={data} />                  {/* server */}
+      <AddToCartButton id={data.id} />                {/* the only 'use client' file */}
+    </article>
+  );
+}
+```
+
+Use **streaming SSR with `<Suspense>`** to flush the static shell immediately and stream slow subtrees in parallel — multiple independent boundaries stream concurrently, cutting time-to-first-paint when one section is data-bound. The canonical App-Router data and component patterns are `../nextjs/SKILL.md` and `../react/SKILL.md`; bring the perf loop here, take the idioms there.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Optimizing on a hunch, no profile | you fix a phase nobody waits on | measure → attribute → fix the dominant phase |
+| Chasing a lab score no real user hits | lab cold-cache LCP ≠ field p75 | optimize the field 75th-percentile number |
+| Reporting the mean, not p75 | the average hides the tail users feel | always read/report the 75th percentile |
+| Blanket `useMemo`/`useCallback` in React 19 | the compiler already memoizes; you add noise | memo only what the Profiler proves >16 ms |
+| Lazy-loading the LCP / hero image | you defer the very element LCP measures | `priority` / `fetchpriority=high`, eager |
+| `import _ from "lodash"` for one function | the whole library lands in First Load JS | named import or a few lines of your own |
+| `'use client'` at the top of the tree | the entire subtree ships to the browser | push the boundary to the interactive leaf |
+| Images/embeds with no reserved space | content reflows on load → CLS | explicit width/height or `aspect-ratio` |
+| Micro-optimizing a non-bottleneck phase | effort moves a number off the critical path | fix only the phase the trace points at |
+| "Done" without re-measuring | the fix may not have moved the metric | re-measure against the threshold, then stop |
+
+## Stop rule
+
+You are done when the **field 75th percentile clears the "good" threshold** (LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1) and your bundle is under its budget — re-measure to confirm, then stop. Going from "good" to "slightly better good" is gold-plating: it costs maintenance and moves a number no user notices. Commit the threshold as a budget so it can't silently regress (`scripts/verify.sh` lints that budget; see `references/profiling-playbook.md` for the field-RUM wiring that keeps the p75 honest in production).

package/skills/performance/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — performance
+
+These cases are routing and trigger fixtures, not an automated test harness. `should_trigger` lists prompts the `performance` description and body must claim — including the non-obvious ones (whole-library import, a `'use client'` boundary shipping the server tree) and the Catalan/Spanish phrasings. `should_not_trigger` lists near-miss prompts that belong to a real sibling, each tagged with the `route_to` id it should defer to (`scaling`, `postgresdb`, `redis`, `nextjs`, `react`). `capability` is one "slow product page" scenario with a `must_include` rubric covering the measure → attribute → fix → re-measure loop. To run them, read each prompt against `../SKILL.md` and confirm by hand that the triggers fire, the non-triggers route to the named sibling rather than being grabbed, and a real answer to the capability scenario hits every rubric line — or feed this file to the repo's eval runner if one is present. The committed performance budget the skill tells you to author is checked separately by `../scripts/verify.sh`.

package/skills/performance/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: performance
+
+should_trigger:
+  - prompt: "My LCP is 4.2s on mobile in Search Console — how do I fix it?"
+    why: "Direct Core Web Vitals failure at the field level; the canonical reason to reach for performance and attribute LCP to a subpart."
+  - prompt: "First Load JS is 800KB — what's making the bundle so big?"
+    why: "Bundle-size analysis; the body's analyze-before-cut loop with the treemap is exactly this."
+  - prompt: "Typing in this search box feels laggy and our INP is failing."
+    why: "INP / long-task; non-obvious because it reads as a UI complaint, but it's the >50ms task model."
+  - prompt: "The page content jumps around while it loads and it's annoying."
+    why: "CLS described by symptom without naming the metric — performance reserves space to fix it."
+  - prompt: "We import all of lodash just to use debounce — is that why the bundle is huge?"
+    why: "Non-obvious tree-shaking / whole-library trap; a named anti-pattern in the body."
+  - prompt: "A 'use client' at the top of our route is shipping the whole server tree to the browser — how do we cut First Load JS?"
+    why: "Non-obvious RSC boundary discipline; performance owns the measure-cut loop, framework idioms defer to nextjs."
+  - prompt: "La pàgina carrega molt lenta i no passa els Core Web Vitals, per on començo?"
+    why: "Catalan — slow load failing CWV, the heart of the skill (measure field p75 first)."
+  - prompt: "El bundle pesa demasiado, hay que analizarlo antes de tocar nada."
+    why: "Spanish — analyze-before-cutting the bundle, the skill's prime directive applied to bundle size."
+
+should_not_trigger:
+  - prompt: "Will the site survive the launch traffic spike on Monday?"
+    route_to: scaling
+    why: "Concurrency / capacity survival for many requests at once, not single-request speed."
+  - prompt: "This query does a sequential scan in production — how do I index it?"
+    route_to: postgresdb
+    why: "Query plan / index fix itself; performance only attributes 'TTFB is the bottleneck' and names the query."
+  - prompt: "Our cache stampedes the origin on every deploy — make it single-flight."
+    route_to: redis
+    why: "Cache correctness / race-freedom; performance decides what to cache, redis makes it race-free."
+  - prompt: "What's the idiomatic way to structure data fetching in the App Router?"
+    route_to: nextjs
+    why: "Framework-canonical data pattern, not the cross-cutting measure-fix-remeasure loop."
+  - prompt: "When should I reach for useReducer vs useState in this component?"
+    route_to: react
+    why: "Idiomatic React state design, not a profiled render-cost problem with a measured target."
+
+capability:
+  - scenario: "A product page has a field LCP of 3.8s and First Load JS of 600KB on mobile. Make it fast."
+    must_include:
+      - "Measures first — reads field CWV at the 75th percentile (CrUX/RUM) for the real problem, then a Lighthouse/DevTools lab trace for the why, before changing code."
+      - "Attributes LCP to a specific subpart (TTFB / load delay / load duration / render delay) and names the dominant one in one sentence before fixing."
+      - "Names a concrete LCP fix tied to that subpart — e.g. preload + fetchpriority=high / next-image priority / stop lazy-loading the hero — not a generic 'optimize images'."
+      - "Analyzes the bundle with a named tool (@next/bundle-analyzer or source-map-explorer) and reads the treemap before cutting anything."
+      - "Proposes a concrete bundle cut — replace/remove a heavy dep, dynamic import() for non-critical UI, or fix a whole-library import — in payoff order."
+      - "Does NOT blanket-memoize React components (notes React 19 compiler auto-memoizes) and does not guess fixes without the profile."
+      - "Re-measures against the numeric targets (LCP ≤ 2.5s field p75 and a bundle budget) and stops at 'good' rather than gold-plating."

package/skills/performance/references/profiling-playbook.md

@@ -0,0 +1,54 @@
+# Profiling playbook
+
+Tool-specific runbooks the SKILL body points to. Pick the tool that matches the phase you're attributing; each one answers a different question.
+
+## Field data — the only number that decides "is it a problem"
+
+Field = real users, 75th percentile. Two sources:
+
+- **CrUX / PageSpeed Insights** — `https://pagespeed.web.dev/` gives you the field CWV for any public URL (28-day rolling p75) plus a lab Lighthouse run side by side. Read the field section first; the lab section is for the *why*.
+- **RUM via the `web-vitals` library** — for your own real traffic, especially routes CrUX doesn't have enough data for.
+
+```ts
+// web-vitals: report each metric to your analytics endpoint (field RUM)
+import { onLCP, onINP, onCLS } from "web-vitals";
+
+function send(metric: { name: string; value: number; rating: string }) {
+  navigator.sendBeacon("/rum", JSON.stringify(metric));
+}
+onLCP(send);
+onINP(send);
+onCLS(send);
+```
+
+Aggregate these at the 75th percentile per route. The mean lies — a p50 of 1.5 s with a p75 of 4 s is a failing route the average calls fine. Dashboards/alerting for this stream are `../../monitoring/SKILL.md` / observability's job; here you only need the p75 to know whether you've cleared the threshold.
+
+## Lighthouse — the lab "why" for load
+
+- Run from Chrome DevTools → Lighthouse panel, or CLI `npx lighthouse <url> --view`. Use **mobile + simulated throttling** (the default) — desktop hides the bottleneck most users hit.
+- In CI, gate a build with Lighthouse CI (`lhci autorun`) and an assertion budget so a regression fails the PR. Treat the budget file as the source of truth (see `verify.sh`).
+- Lighthouse is a single throttled lab load. If its LCP is far worse than field p75, trust the field — don't chase the lab phantom.
+
+## Chrome DevTools Performance trace — read the flame chart
+
+1. DevTools → Performance → record, reload or perform the interaction, stop.
+2. **LCP/CLS markers** sit on the Timings track — the LCP marker tells you the element and the timestamp; hover for the subpart breakdown (TTFB / load delay / load duration / render delay).
+3. **Main-thread track** is the flame chart. Wide bars = expensive functions. Bars flagged with a red corner are **long tasks (>50 ms)** — these are your INP suspects. Click one to see the call stack and which script owns it (often third-party).
+4. Attribute before fixing: name the dominant subpart (LCP) or the owning script (INP). One sentence, then fix that one thing.
+
+## React DevTools Profiler — re-render cost
+
+1. Install React DevTools, open the **Profiler** tab, record an interaction, stop.
+2. The flamegraph colors components by render time; the ranked chart lists the slowest. Click a component → **"Why did this render?"** shows hooks/props that changed.
+3. Apply the **16 ms rule**: a manual `useMemo`/`useCallback` is only worth it if it saves more than one 60 fps frame (~16 ms). React 19's compiler already memoizes the common cases — don't add manual memo the Profiler can't justify.
+4. The usual real cause is an unstable reference (new object/array/function created in render and passed as a prop). The compiler can't fix that — hoist or stabilize it; don't wrap the child in `memo` to paper over it.
+
+## Bundle treemap — what's actually heavy
+
+- **Next.js:** wire `@next/bundle-analyzer` into `next.config`, then `ANALYZE=true npm run build`. It opens an interactive treemap and (current Next) uses the Turbopack module graph to trace which `'use client'` boundary pulled a module into the client bundle.
+- **Any webpack/Vite build:** `npx source-map-explorer 'dist/**/*.js'` attributes bytes back to source files via source maps.
+- Reading it: box area = bytes. One or two boxes usually dwarf the rest — that's your first cut (replace the dep). Then look for whole-library imports (a giant box for a lib you use one function from) and for heavy UI that could be a dynamic `import()`.
+
+## Order of attack
+
+Field p75 says *which metric* fails → lab trace says *which phase/script* → fix that one phase → re-measure field p75. Stop at "good".

package/skills/performance/scripts/verify.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# verify.sh — budget-validity gate for the performance skill's artifacts.
+#
+# The skill tells you to commit a performance budget (a Core Web Vitals target
+# + a bundle-size budget) so the thresholds can't silently drift. This script
+# statically lints any such budget file it finds. It does NOT run a live
+# Lighthouse audit — that needs a real URL and a browser and is non-hermetic;
+# the behavioral rigor lives in ../evals/. This only checks the committed
+# artifact.
+#
+# Read-only: it never writes, never makes a network request.
+# Exits 0 on a clean/empty target (no budget file found is NOT a failure).
+# Exits 1 only when a budget file that DOES exist is malformed or carries a
+# Core Web Vitals threshold that contradicts the canonical "good" numbers:
+#   LCP 2500 ms, INP 200 ms, CLS 0.1.
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+fail=0
+checked=0
+
+# Canonical CWV "good" thresholds (field 75th percentile).
+LCP_MS=2500
+INP_MS=200
+CLS=0.1
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Extract a numeric value for a key from a JSON file. Prefer jq; fall back to a
+# grep/sed scrape so the check works with zero dependencies.
+json_num() {
+  local file="$1" key="$2"
+  if have jq; then
+    jq -r ".. | objects | .\"$key\"? // empty | select(type==\"number\")" "$file" 2>/dev/null | head -n1
+  else
+    grep -Eo "\"$key\"[[:space:]]*:[[:space:]]*[0-9.]+" "$file" 2>/dev/null \
+      | head -n1 | grep -Eo '[0-9.]+$'
+  fi
+}
+
+# A budget is "LCP-shaped" if it mentions LCP at all; only then do we lint it.
+looks_like_budget() {
+  grep -Eqi '"?lcp"?|core[ _-]?web[ _-]?vitals|first[ _-]?load[ _-]?js|bundle' "$1" 2>/dev/null
+}
+
+check_budget() {
+  local file="$1"
+  looks_like_budget "$file" || return 0
+  checked=$((checked + 1))
+
+  # Must be valid JSON when jq is available.
+  if have jq && ! jq empty "$file" >/dev/null 2>&1; then
+    echo "FAIL  $file (invalid JSON)"
+    fail=1
+    return 0
+  fi
+
+  local missing=() bad=()
+  local lcp inp cls
+  lcp="$(json_num "$file" lcp)"
+  inp="$(json_num "$file" inp)"
+  cls="$(json_num "$file" cls)"
+
+  [ -n "$lcp" ] || missing+=("lcp")
+  [ -n "$inp" ] || missing+=("inp")
+  [ -n "$cls" ] || missing+=("cls")
+
+  # A budget threshold must not be LOOSER than the canonical "good" number.
+  [ -n "$lcp" ] && awk "BEGIN{exit !($lcp > $LCP_MS)}" && bad+=("lcp=$lcp ms looser than $LCP_MS")
+  [ -n "$inp" ] && awk "BEGIN{exit !($inp > $INP_MS)}" && bad+=("inp=$inp ms looser than $INP_MS")
+  [ -n "$cls" ] && awk "BEGIN{exit !($cls > $CLS)}"   && bad+=("cls=$cls looser than $CLS")
+
+  if [ "${#missing[@]}" -ne 0 ] || [ "${#bad[@]}" -ne 0 ]; then
+    echo "FAIL  $file"
+    [ "${#missing[@]}" -ne 0 ] && printf '      missing metric: %s\n' "${missing[@]}"
+    [ "${#bad[@]}" -ne 0 ]     && printf '      drifted: %s\n' "${bad[@]}"
+    fail=1
+  else
+    echo "OK    $file (LCP/INP/CLS budget within canonical good thresholds)"
+  fi
+}
+
+# Lint every JSON budget candidate under the skill dir (bash 3.x safe — no mapfile).
+while IFS= read -r f; do
+  [ -n "$f" ] || continue
+  check_budget "$f"
+done < <(find "$SKILL_DIR" -type f \( -name 'budget*.json' -o -name '*budget.json' \
+            -o -name '.lighthouserc.json' -o -name 'perf-budget.json' \) 2>/dev/null || true)
+
+if [ "$checked" -eq 0 ]; then
+  echo "No performance budget file found — nothing to verify (clean)."
+fi
+
+exit "$fail"

package/skills/phoenix/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: phoenix
+description: "Use when building an Elixir web app with Phoenix — contexts, Ecto schemas/changesets/migrations, LiveView, channels, generators and Phoenix-flavored tests — or wiring up the boundary between domain logic and the web layer. Triggers: 'mix phx.new', 'phx.gen.live', 'phx.gen.auth', 'build a LiveView CRUD', 'Ecto changeset', 'Phoenix channel / PubSub', 'how do I structure a context', non-obvious 'my LiveView re-renders the whole list every time one row is added', 'every post fires a separate query for its author' (N+1), Catalan 'crea un context Comandes i un LiveView per gestionar-les amb acces per usuari', Spanish 'autenticacion sin contrasena con phx.gen.auth / como separo el contexto del controlador'. NOT pure OTP — GenServers, supervision trees, releases with no web/Ecto layer (that is elixir)."
+tags: [phoenix, elixir, liveview, ecto, channels, contexts, web, beam]
+recommends: [elixir, postgresdb, docker]
+origin: risco
+---
+
+# Phoenix
+
+You are building a web application on the BEAM with Phoenix. There is one mental model that keeps a Phoenix app coherent as it grows: **contexts are the public API of your domain; the web layer (controllers, LiveViews, channels) is a thin caller of contexts.** A LiveView that reaches into `Repo` directly, or a controller stuffed with business rules, is the first crack. Push logic down into a context function and the web layer stays a presentation shell you can swap (HTML → JSON → LiveView) without rewriting the domain.
+
+Target the current stack: **Phoenix 1.8.7** (1.8.0 shipped 2025-08-05), **LiveView 1.1** (1.1.x patch line; 1.0 shipped 2024-12-03), **Ecto** as the data layer, **Erlang/OTP 25+**. The headline 1.8 change is **scopes**: generators thread the current actor (user/org) through every context function and into the query, so *secure-by-default data access is the norm, not something you bolt on later*. New apps ship daisyUI + Tailwind theming, a single root layout, and an `AGENTS.md` for LLM-assisted work.
+
+If the question has no web, Ecto or LiveView in it — it is a GenServer, a supervision tree, a `mix release` — that is the runtime, route to `../elixir/SKILL.md`.
+
+## Where does this code go — generator decision
+
+Pick the layer first, then the generator. Getting this wrong means rewriting the boundary later.
+
+| You are building | Use | Generator |
+|---|---|---|
+| Stateless page or JSON endpoint, request→response | Controller + view | `mix phx.gen.html` / `phx.gen.json` |
+| Stateful interactive UI, server-rendered, live updates | LiveView | `mix phx.gen.live` |
+| Raw bidirectional WebSocket / fan-out to many clients | Channel + PubSub | hand-wire, no generator |
+| Domain logic with no UI yet (just the boundary) | Context only | `mix phx.gen.context` |
+| Login, sessions, password reset, scopes | Auth scaffold | `mix phx.gen.auth` |
+
+Rule: **generate the context first, then the web layer on top of it.** `phx.gen.live` and `phx.gen.html` already produce a context — don't hand-write a controller that calls `Repo` and skip the context.
+
+## Contexts — the domain boundary
+
+A context is a module like `Accounts`, `Catalog`, `Orders` that owns a slice of the domain. The web layer calls `Catalog.list_products(scope)`; it never calls `Repo` and never builds an `Ecto.Query`.
+
+Rule: **the public contract is plain data and functions, not Ecto schemas.** Schemas are an implementation detail. Leak them and every caller couples to your column names. Why: you can refactor the table without touching controllers.
+
+Rule: **thread the scope through every context function** (1.8). The scope carries the current actor; the context filters every query by it. Why: a forgotten `where: user_id ==` is a data leak — scoping makes the safe path the default path.
+
+```elixir
+# Bad — Repo + business logic in the controller, no scope, anyone reads anyone's data.
+def index(conn, _params) do
+  products = Repo.all(Product)            # raw Repo in web layer
+  render(conn, :index, products: products)
+end
+
+# Good — controller calls a context function that takes the scope.
+def index(conn, _params) do
+  products = Catalog.list_products(conn.assigns.current_scope)
+  render(conn, :index, products: products)
+end
+
+# In lib/my_app/catalog.ex — the boundary owns the query and the scope filter.
+def list_products(%Scope{} = scope) do
+  Product
+  |> where(org_id: ^scope.org.id)         # secure by default
+  |> Repo.all()
+end
+```
+
+Depth on defining and threading scopes, magic-link auth, sudo mode and query-level enforcement lives in `references/auth-and-scopes.md`.
+
+## Ecto — the data layer
+
+Ecto gives you `Repo`, schemas, `Ecto.Changeset` (cast + validate), `Ecto.Multi` (transactional pipelines) and `Ecto.Query`.
+
+Rule: **validate at the boundary with a changeset, never with `try/rescue`.** A changeset casts external params, applies validations and constraints, and hands you `{:ok, struct}` or `{:error, changeset}` you can render straight into a form. Why: validation errors are expected data flow, not exceptions.
+
+Rule: **multi-write operations go through `Ecto.Multi`** so they commit or roll back as a unit. Why: a half-written order with no payment row is corruption.
+
+Rule: **preload associations — never trigger a query per row.** Why: the N+1 is the single most common Phoenix performance bug.
+
+```elixir
+# Bad — N+1: each post in the loop fires a separate query for post.author.
+posts = Repo.all(Post)
+for post <- posts, do: post.author.name   # one SELECT per post
+
+# Good — one query for posts, one for all authors.
+posts = Post |> preload(:author) |> Repo.all()
+for post <- posts, do: post.author.name
+```
+
+Migrations are forward-only facts about schema history — write a new one, don't edit a shipped migration. Changeset recipes, `Ecto.Multi`, advanced queries/preloads, constraints and sandbox config are in `references/ecto-patterns.md`.
+
+## LiveView — stateful server-rendered UI
+
+A LiveView holds state in `socket.assigns`, renders HEEx, and reacts to events. The lifecycle:
+
+| Callback | Fires when | Use it for |
+|---|---|---|
+| `mount/3` | First connect (and the dead render) | Load initial data, set up subscriptions |
+| `handle_params/3` | Mount and every live patch | React to URL/query changes |
+| `handle_event/3` | A client event (`phx-click`, form submit) | Mutate state, call a context |
+| `handle_info/2` | A message arrives (PubSub, `send/2`) | Apply external/async updates |
+
+Rule: **use streams for collections — do not hold the full list in an assign.** A stream keeps the list off the socket; `stream_insert/3` of one item sends only that item over the wire. Why: assigning the whole list re-sends and re-diffs every row on every change — that is exactly the "re-renders the entire list when one row is added" symptom. For per-row change tracking wrap each entry in a LiveComponent.
+
+```elixir
+# Bad — full list in assigns; one insert re-diffs the entire collection.
+def mount(_p, _s, socket), do: {:ok, assign(socket, :messages, Chat.list_messages())}
+def handle_info({:new, msg}, socket) do
+  {:noreply, assign(socket, :messages, socket.assigns.messages ++ [msg])}
+end
+
+# Good — stream; only the new row crosses the wire.
+def mount(_p, _s, socket), do: {:ok, stream(socket, :messages, Chat.list_messages())}
+def handle_info({:new, msg}, socket), do: {:noreply, stream_insert(socket, :messages, msg)}
+```
+
+```heex
+<div id="messages" phx-update="stream">
+  <div :for={{dom_id, msg} <- @streams.messages} id={dom_id}>{msg.body}</div>
+</div>
+```
+
+Build forms with `to_form/2` (carry the changeset, render errors). Route with **verified routes** — the `~p` sigil (`~p"/products/#{product}"`) is compile-checked, the default since 1.7. LiveView 1.1 adds **colocated hooks** (`<script :type={Phoenix.LiveView.ColocatedHook} name="...">`, extracted at compile time, requires Phoenix 1.8+), ColocatedJS, official TypeScript types for the JS client, and keyed comprehensions. Full lifecycle, streams + LiveComponent change tracking, forms/uploads, JS commands, colocated hooks and `assign_async` are in `references/liveview.md`.
+
+## Channels & PubSub — real-time fan-out
+
+Reach for a **channel** when you need raw bidirectional WebSocket messaging or to broadcast to many clients (chat fan-out, presence, live dashboards feeding many sockets). Reach for **LiveView** when one user drives a server-rendered UI — most "real-time" UI is just LiveView + `Phoenix.PubSub`.
+
+```elixir
+Phoenix.PubSub.subscribe(MyApp.PubSub, "room:42")   # in mount/3
+Phoenix.PubSub.broadcast(MyApp.PubSub, "room:42", {:new, msg})  # from a context
+```
+
+`Phoenix.Presence` tracks who is online on a topic. Keep channel callbacks thin — they call contexts too.
+
+## Auth & scopes
+
+`mix phx.gen.auth` in 1.8 **defaults to magic-link (passwordless) auth**, with a re-auth "sudo mode" plug for sensitive operations; email+password is still available. It also sets up the **default scope** that generators thread through contexts. Treat scope-based filtering as the authorization layer: the query never returns rows the scope can't see, so authz is enforced in the data access, not in a forgotten `if`. Flow, sudo mode, custom scopes and testing authz are in `references/auth-and-scopes.md`.
+
+## Testing — test at the right layer
+
+| Test target | Helper | Isolation |
+|---|---|---|
+| Controllers / JSON | `Phoenix.ConnTest` via `ConnCase` | SQL sandbox |
+| Context / Ecto logic | `DataCase` | SQL sandbox |
+| LiveView UI | `Phoenix.LiveViewTest` (`live/2`, `render_click`, `element/2`) | SQL sandbox |
+| Concurrent DB tests | `Ecto.Adapters.SQL.Sandbox` | per-test transaction |
+
+Rule: **test domain rules at the context (DataCase), test interaction at the LiveView (LiveViewTest).** Why: a context test that drives the UI is slow and brittle; a LiveView test that re-asserts every validation rule duplicates the context test.
+
+```elixir
+test "creating a product shows it in the list", %{conn: conn} do
+  {:ok, view, _html} = live(conn, ~p"/products")
+  view |> form("#product-form", product: %{name: "Widget"}) |> render_submit()
+  assert render(view) =~ "Widget"
+end
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `Repo.all/insert` called from a controller or LiveView | Web layer couples to the DB; logic can't be reused or tested in isolation | Call a context function; keep `Repo` inside the context |
+| Returning Ecto schemas as the public contract | Callers couple to column names; refactors ripple outward | Expose functions over plain data; schemas stay internal |
+| Holding the full collection in `socket.assigns` | Every insert re-sends and re-diffs the whole list (lag, bandwidth) | `stream/3` + `stream_insert/3`; LiveComponent for per-row tracking |
+| `try/rescue` around persistence to "validate" | Hides expected errors as exceptions; no field-level messages | `Ecto.Changeset` → `{:ok, _}` / `{:error, changeset}` |
+| Looping over records touching an association | N+1 — one query per row | `preload/2` (or a join) before the loop |
+| Forgetting to filter a query by the scope | Cross-tenant data leak — the worst kind of bug | Thread `scope` through every context fn; filter in the query |
+| Multi-write without a transaction | Partial writes leave corrupt state | `Ecto.Multi`, commit or roll back as one |
+| Fat schema modules full of business logic | Domain rules scatter; the boundary blurs | Logic lives in the context; schema holds fields + changeset |
+| Hardcoded path strings in templates | Breaks silently when routes change | Verified routes — the `~p` sigil, compile-checked |
+
+## See also
+
+- `../elixir/SKILL.md` — OTP, GenServers, supervision trees, the runtime Phoenix builds on.
+- `../postgresdb/SKILL.md` — raw SQL tuning, index design and DB ops below the Ecto line.
+- `references/liveview.md`, `references/ecto-patterns.md`, `references/auth-and-scopes.md` — branch-specific depth.

package/skills/phoenix/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — phoenix
+
+These cases check two things, neither of which is an automated unit test. First, **routing**: feed each `should_trigger` prompt to the skill router and confirm it selects `phoenix`, and feed each `should_not_trigger` prompt and confirm it routes to the named sibling (`elixir`, `postgresdb`, `fly-io`, `django`) instead — the non-obvious cases (the re-rendering list, the N+1, the Catalan context prompt) are the ones worth watching. Second, the **capability** case is graded by hand or by a judge model: have the agent implement the Catalog/Product LiveView scenario and check the generated code against the `must_include` rubric (context boundary, changeset validation, scope threaded into the query, streams over full-list assigns, `to_form`, `~p` routes, LiveViewTest + DataCase). Pass means every rubric item is satisfied in real Phoenix 1.8 / LiveView 1.1 code, not just mentioned.