@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/network-troubleshooting/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: network-troubleshooting
+description: Layer-by-layer diagnosis of network faults on Linux, macOS and Windows, working up from link and IP routing through DNS resolution, TCP/UDP port reachability and firewalls, TLS certificates and SNI, to latency, packet loss and MTU black holes, with the exact command for each check and how to read its output. Use when a host, site or service is unreachable, name resolution fails, a connection times out or is refused, a TLS handshake errors, or a link is slow or drops large transfers.
+license: MIT
+compatibility: Any Agent Skills host with a shell. Uses standard OS tools (ping, ip or ifconfig, dig or nslookup, nc, curl, openssl); mtr and tcpdump are optional.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ping, curl"
+  kete-loom/owner: "Kete-org"
+---
+
+# Network troubleshooting
+
+Find the lowest layer that is broken, prove it with one command, then fix only that. Most "the network is down" reports are DNS, a firewall, or a wrong route, and guessing wastes hours.
+
+Per-OS command equivalents are in `references/commands.md`. Read it when the user is not on Linux or a command below is missing.
+
+## Ground rules
+
+1. **Read-only first.** Every check in this skill observes state. Do not flush caches, restart services, change routes or edit firewall rules until you have shown which layer is broken, and ask the user before any change on a remote machine you are connected through: a wrong rule cuts you off.
+2. **Pin down the symptom before testing.** Get: source host, destination (name and port), protocol, the exact error text, when it last worked, and what changed. "Connection refused" and "timed out" point to different layers.
+3. **Test from where the failure is.** A check from your laptop proves nothing about the server's path. Run each command on the failing source, or say clearly where you ran it.
+4. **One variable at a time.** Compare against a known-good target (`1.1.1.1`, another host on the same subnet) so each result splits the problem in half.
+5. **Never paste secrets** (VPN keys, tokens in URLs, cookies from `curl -v`) into the report.
+
+## Step 1: Local link and address
+
+```sh
+ip -br addr            # interface up, has the expected IPv4/IPv6 address?
+ip route               # is there a default route, via the right gateway?
+ip route get 1.1.1.1   # which interface and source address a packet would use
+ping -c 3 <gateway>
+```
+
+- No address, or a `169.254.x.x` address: DHCP failed. Check cable/Wi-Fi association and the DHCP server, not DNS.
+- Gateway does not answer but has an entry in `ip neigh` marked `FAILED`/`INCOMPLETE`: layer 2 problem (wrong VLAN, cable, switch port).
+- Two default routes, or a VPN that installed `0.0.0.0/1` routes: traffic may be leaving by the wrong interface.
+
+## Step 2: IP reachability beyond the gateway
+
+```sh
+ping -c 3 1.1.1.1        # internet by IP, no DNS involved
+traceroute -n <dest-ip>  # or: mtr -rwnc 50 <dest-ip>
+```
+
+- IP works but names fail: go to step 3.
+- Path stops at a hop and never continues: routing or a firewall at that hop. Note the last hop that answered.
+- Many networks drop ICMP. A failed ping alone does not prove a host is down; test the real port in step 4.
+
+## Step 3: DNS
+
+```sh
+dig example.com                 # what the system's configured resolver says
+dig @1.1.1.1 example.com        # what a public resolver says
+dig +trace example.com          # walk from the root; shows which delegation breaks
+getent hosts example.com        # what applications see (honours /etc/hosts and nsswitch)
+resolvectl status               # systemd-resolved: which DNS server per interface
+```
+
+Read the `status:` field in the dig header:
+
+| Result | Meaning | Next |
+|---|---|---|
+| `NOERROR` with answers | Name resolves | Check the answer is the IP you expect |
+| `NOERROR`, no answers | Name exists, no record of that type | Query `A` and `AAAA` separately |
+| `NXDOMAIN` | Name does not exist at that resolver | Typo, missing record, or split-horizon DNS |
+| `SERVFAIL` | Resolver could not get an answer | DNSSEC failure or broken authoritative servers; try `dig +cd` |
+| `connection timed out; no servers could be reached` | Resolver unreachable | Firewall on UDP/TCP 53, wrong resolver IP, or VPN DNS |
+
+- `dig` and `getent` disagree: an `/etc/hosts` entry, a local cache, or search-domain expansion is involved.
+- Public resolver right, local one wrong: stale cache or an internal zone overriding the public one. Compare TTLs.
+- After a DNS change, the old answer lives until its TTL expires in every cache along the way.
+
+## Step 4: Port reachability and firewalls
+
+```sh
+nc -vz -w 5 <host> <port>                     # TCP
+curl -sv --connect-timeout 5 http://<host>:<port>/ -o /dev/null
+```
+
+| Error | What it means |
+|---|---|
+| `Connection refused` | Packet reached the host; nothing listening on that port, or a firewall REJECT (TCP reset or ICMP port-unreachable) |
+| Timed out | Packet or reply dropped silently: firewall DROP, security group, wrong route, or host down |
+| `No route to host` | ARP failed on the local subnet, or a firewall REJECT with ICMP host-prohibited |
+
+On the destination, check what listens and what filters:
+
+```sh
+ss -tulpn                       # listening sockets; 127.0.0.1:port is local-only
+sudo nft list ruleset           # or: sudo iptables -S ; sudo ufw status verbose ; sudo firewall-cmd --list-all
+```
+
+- `curl` fails but `nc` works: check `env | grep -i proxy` (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`); a proxy setting sends the request somewhere else.
+- Service bound to `127.0.0.1` or `::1` only: it is not reachable from outside, whatever the firewall says.
+- Check every filter on the path: host firewall, cloud security group or network ACL, router port forward, and the container runtime's own rules.
+- Capture to settle it: `sudo tcpdump -ni any host <client-ip> and port <port>`. SYN arrives with no SYN-ACK: the host's firewall or the service. No SYN arrives: something upstream drops it.
+
+## Step 5: TLS
+
+```sh
+openssl s_client -connect <host>:443 -servername <host> -showcerts </dev/null
+openssl s_client -connect <host>:443 -servername <host> </dev/null 2>/dev/null \
+  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName
+curl -v https://<host>/ -o /dev/null
+```
+
+`-ext` needs OpenSSL 1.1.1 or newer; on older OpenSSL or LibreSSL (macOS) use `-noout -text` and read the `Subject Alternative Name` block.
+
+- `Verify return code: 0 (ok)` means the chain is trusted from this machine.
+- `unable to get local issuer certificate`: the server does not send its intermediate certificate, or this client lacks the root. Browsers can hide this; `curl` and most libraries do not.
+- `certificate has expired` or `notAfter` in the past: renew. Also check the client clock with `date`.
+- Hostname mismatch: the name is not in `subjectAltName`. Without `-servername` (no SNI) many servers return a default certificate, so always pass it.
+- To test one backend behind a load balancer or before DNS changes: `curl -v --resolve <host>:443:<ip> https://<host>/`.
+
+## Step 6: Latency, loss and MTU
+
+```sh
+mtr -rwnc 100 <host>
+curl -o /dev/null -s -w 'dns %{time_namelookup}  connect %{time_connect}  tls %{time_appconnect}  ttfb %{time_starttransfer}  total %{time_total}\n' https://<host>/
+ping -M do -s 1472 -c 3 <host>   # 1472 + 28 bytes of headers = 1500
+```
+
+- In `mtr`, loss at one middle hop that does not continue to later hops is ICMP rate limiting, not real loss. Loss that starts at a hop and persists to the destination is real.
+- The `curl -w` timings say which phase is slow: DNS, TCP connect, TLS, or the server itself (time to first byte).
+- **MTU black hole** signs: ping and small requests work, but large downloads, `git clone`, TLS handshakes with big certificate chains, or SSH sessions after login hang. Lower `-s` until the do-not-fragment ping succeeds; the working size plus 28 is the path MTU. Typical culprits are VPNs (WireGuard commonly uses 1420), PPPoE (1492) and firewalls that block ICMP "fragmentation needed". Fix with a lower interface MTU or TCP MSS clamping on the router, and say which.
+
+## Stop and ask the user
+
+- Before any change that could drop your own session (firewall, routes, interface down, VPN restart) on a machine you reach over the network.
+- When the fault is outside what you can see: ISP, cloud provider console, a corporate proxy, or a device you have no shell on. Say exactly what to check there.
+- When a fix needs credentials or admin access you do not have.
+
+## Never
+
+- Never disable a firewall entirely "to test" on an internet-facing host.
+- Never use `curl -k` or turn off certificate verification as the fix; it only hides the TLS fault.
+- Never conclude "host is down" from ping alone.
+
+## Report
+
+```
+Symptom: <source> → <destination:port/proto>: <exact error>
+Broken layer: <link | IP/routing | DNS | port/firewall | TLS | MTU/latency>
+Evidence: <command> → <the output line that proves it>
+Cause: <one sentence>
+Fix: <smallest change, and where to apply it> (applied | proposed, needs approval)
+Checked and fine: <layers verified working>
+Not checked: <what you could not test, and why>
+```

package/skills/network-troubleshooting/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "My server can ping 8.8.8.8 but apt update says it can't resolve the mirror hostname",
+    "curl to our API on port 8443 just hangs and then times out, what's blocking it?",
+    "Users get 'unable to get local issuer certificate' when hitting our site from Python but Chrome is fine",
+    "Small web pages load over the VPN but large downloads and git clone stall forever",
+    "nc says connection refused on port 5432 from the app box, how do I figure out why",
+    "Why is the website slow only from the office, mtr shows loss at hop 6"
+  ],
+  "should_not_trigger": [
+    "Help me split my home network into VLANs for IoT, guests and my servers",
+    "Review this nftables ruleset and WireGuard config for anything exposed to the internet",
+    "Write a Kubernetes NetworkPolicy that only lets the frontend reach the API pods",
+    "Set up a GitHub Actions workflow that deploys to staging on every merge",
+    "Profile this Node.js endpoint, the database query inside it takes 3 seconds",
+    "Write Terraform for an AWS VPC with public and private subnets"
+  ]
+}

package/skills/network-troubleshooting/references/commands.md

@@ -0,0 +1,33 @@
+# Command equivalents by OS
+
+Use the row for the user's OS. All are read-only unless marked.
+
+| Check | Linux | macOS | Windows (PowerShell) |
+|---|---|---|---|
+| Addresses | `ip -br addr` | `ifconfig` or `ipconfig getifaddr en0` | `Get-NetIPAddress` or `ipconfig /all` |
+| Routes | `ip route` | `netstat -rn` | `Get-NetRoute` or `route print` |
+| Route for one destination | `ip route get <ip>` | `route -n get <ip>` | `Find-NetRoute -RemoteIPAddress <ip>` |
+| Neighbour/ARP table | `ip neigh` | `arp -an` | `Get-NetNeighbor` |
+| Trace path | `traceroute -n`, `tracepath`, `mtr` | `traceroute -n`, `mtr` (Homebrew) | `tracert -d`, `pathping` |
+| DNS query | `dig`, `getent hosts` | `dig`, `dscacheutil -q host -a name <name>` | `Resolve-DnsName <name>`, `nslookup` |
+| Resolver in use | `resolvectl status` or `/etc/resolv.conf` | `scutil --dns` | `Get-DnsClientServerAddress` |
+| Flush DNS cache (changes state) | `resolvectl flush-caches` | `sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder` | `Clear-DnsClientCache` or `ipconfig /flushdns` |
+| TCP port test | `nc -vz -w 5 <host> <port>` | `nc -vz -G 5 <host> <port>` | `Test-NetConnection <host> -Port <port>` |
+| Listening sockets | `ss -tulpn` | `lsof -nP -iTCP -sTCP:LISTEN` | `Get-NetTCPConnection -State Listen` or `netstat -ano` |
+| Host firewall | `nft list ruleset`, `iptables -S`, `ufw status verbose`, `firewall-cmd --list-all` | `sudo pfctl -sr`, `/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate` | `Get-NetFirewallProfile`, `Get-NetFirewallRule -Enabled True` |
+| Don't-fragment ping (1500 path) | `ping -M do -s 1472 <host>` | `ping -D -s 1472 <host>` | `ping -f -l 1472 <host>` |
+| Packet capture | `sudo tcpdump -ni any <filter>` | `sudo tcpdump -ni en0 <filter>` | `pktmon` or Wireshark |
+
+## Reading traceroute
+
+- `* * *` on one hop, later hops answer: that router does not reply to probes. Ignore it.
+- `* * *` from some hop to the end: traffic is dropped there or the destination filters probes. Test the real port with `nc` before concluding anything.
+- A sudden large latency jump that stays for every later hop is a real slow link; a jump at one hop only is the router deprioritising ICMP.
+
+## UDP checks
+
+`nc -vzu` cannot tell "open" from "filtered" because UDP has no handshake. Test UDP services with their own client instead: `dig @<server> <name>` for DNS, `wg show` handshake time for WireGuard, `ntpdate -q` or `sntp` for NTP, or capture with `tcpdump` on the server to see whether packets arrive.
+
+## IPv6 versus IPv4
+
+If a name has both `A` and `AAAA` records, clients usually try IPv6 first. When IPv6 is broken, connections stall then fall back. Force each family to compare: `curl -4 ...` and `curl -6 ...`, `ping -4` / `ping -6` (or `ping6`).

package/skills/nextjs-patterns/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: nextjs-patterns
+description: Next.js App Router conventions for the app/ directory - splitting Server and Client Components, async params and request APIs, fetch caching and revalidation (including Cache Components and "use cache"), Route Handlers, Server Actions with auth checks, the Metadata API, middleware/proxy, NEXT_PUBLIC_ environment variables and self-hosting or Vercel deployment traps. Use when adding routes, layouts or pages under app/, deciding where "use client" goes, fixing stale or over-cached data, writing a Server Action or route.ts, or upgrading a Next.js app across major versions.
+license: MIT
+compatibility: Any Agent Skills host. Targets the Next.js App Router (15 and 16); Pages Router projects need different guidance. Needs Node.js 20.9+ for Next.js 16 and the project's package manager.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# Next.js App Router patterns
+
+Keep data and secrets on the server, ship the least client JavaScript, and be explicit about what is cached. General component rules live in `react-patterns`; render speed in `react-performance`.
+
+## 0. Before you change anything
+
+1. Read `next` in `package.json`. Behaviour differs a lot between majors:
+   - 15: `params`, `searchParams`, `cookies()`, `headers()`, `draftMode()` became async (sync access still worked with warnings). `fetch` and `GET` Route Handlers stopped being cached by default.
+   - 16: sync access to those APIs is removed; `middleware.ts` is deprecated in favour of `proxy.ts`; `revalidateTag` takes a second `cacheLife` argument; Turbopack is the default bundler; `next lint` is removed; Node.js 20.9+ is required.
+2. Check `next.config.*` for `cacheComponents: true`. It switches the app to a different caching model (`"use cache"`, no `dynamic`/`revalidate`/`fetchCache` segment config); see `references/caching.md` for both models. Write new code in the model the app uses.
+3. Confirm the project uses `app/`. If it uses `pages/`, stop and tell the user this skill covers the App Router.
+4. If the repo ships version-matched docs (an `AGENTS.md` pointing into `node_modules/next/dist/docs/`), read those before guessing.
+
+## 1. Server vs Client Components
+
+Everything in `app/` is a Server Component unless its module (or an importer) starts with `"use client"`.
+
+Make a component a Client Component only if it needs one of: state or effects, event handlers, browser APIs, or a library that uses them. Then:
+
+1. Push `"use client"` to the **leaves**: a `LikeButton`, not the whole page.
+2. Pass Server Components into Client Components as `children` or props rather than importing them inside the client file.
+3. Props crossing the boundary must be serialisable: plain objects, arrays, strings, numbers, Dates, Promises, Server Actions. No class instances, functions (other than Server Actions) or symbols.
+4. Pass only the fields the client needs, never whole DB rows or user records. Everything you pass is visible in the page payload.
+5. Mark server-only modules (DB, secrets, SDKs with keys) with `import "server-only"` so a client import fails the build.
+6. Context providers are Client Components; render them as deep as possible and wrap `{children}`.
+
+`"use server"` marks Server Actions (functions callable from the client). It is not the opposite of `"use client"` and is never needed to make a Server Component.
+
+## 2. Request APIs and params
+
+```tsx
+export default async function Page(props: PageProps<"/blog/[slug]">) {
+  const { slug } = await props.params;
+  const { q } = await props.searchParams;
+  const theme = (await cookies()).get("theme")?.value;
+  // ...
+}
+```
+
+- `PageProps`, `LayoutProps` and `RouteContext` helpers are generated by `next typegen` (15.5+) or during `next dev`/`next build`.
+- In a Client Component, unwrap a passed `params` promise with React `use()`, or use `useParams()`/`useSearchParams()`.
+- `useSearchParams()` in a client component needs a `<Suspense>` boundary above it, or the build may fail or bail out of static rendering.
+- Treat `params` and `searchParams` as untrusted input; validate them (for example with zod) before using them in queries.
+
+## 3. Data fetching and caching
+
+1. Fetch in Server Components, close to where the data is used. Use `React.cache()` to dedupe a non-`fetch` call (ORM, SDK) within one request; identical `fetch` calls are memoised automatically.
+2. Start independent requests together (`Promise.all`) or in sibling components behind separate `<Suspense>` boundaries. Avoid sequential `await`s in a layout.
+3. Wrap slow or request-specific parts in `<Suspense fallback>` (or add `loading.tsx`) so the rest streams.
+4. Choose caching on purpose, per data source: how stale may it be, and what event invalidates it? Then apply the matching model from `references/caching.md`.
+5. After a mutation, invalidate what changed: `revalidatePath`, `revalidateTag(tag, profile)` (16) or `updateTag(tag)` for read-your-writes inside a Server Action (16).
+6. Development never caches pages. Always confirm caching behaviour with `next build && next start`.
+
+## 4. Route Handlers (`app/**/route.ts`)
+
+- Export named functions per method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. Use the Web `Request`/`Response` (or `NextRequest`/`NextResponse`).
+- A `route.ts` cannot sit in the same segment as a `page.tsx`.
+- Use them for webhooks, public APIs consumed by other clients, file downloads and OAuth callbacks. For mutations from your own UI, prefer Server Actions.
+- Webhooks: read the raw body with `await request.text()` before verifying a signature; don't `request.json()` first.
+- Authenticate and authorise inside every handler; nothing upstream does it for you.
+
+## 5. Server Actions
+
+```ts
+"use server";
+import { z } from "zod";
+import { revalidatePath } from "next/cache";
+
+const Input = z.object({ title: z.string().min(1).max(200) });
+
+export async function createPost(prev: State, formData: FormData): Promise<State> {
+  const session = await auth();                       // 1. authenticate
+  if (!session) return { error: "Sign in first" };
+  const parsed = Input.safeParse({ title: formData.get("title") }); // 2. validate
+  if (!parsed.success) return { error: "Invalid title" };
+  await db.post.create({ data: { ...parsed.data, authorId: session.user.id } }); // 3. authorise by owner
+  revalidatePath("/posts");                           // 4. invalidate
+  return { ok: true };                                // 5. return only what the UI needs
+}
+```
+
+- Every exported action is a public POST endpoint. A page-level auth check does **not** protect the actions on that page. Check auth and resource ownership inside each action (or in a `server-only` data access layer it calls).
+- Validate every argument; types are not runtime checks.
+- Return small plain objects; never return raw DB records.
+- `redirect()` throws to work: call it outside `try/catch`, or rethrow.
+- Use with `useActionState` for errors and pending state, `useOptimistic` for instant feedback.
+- Actions are rejected when the `Origin` host differs from the app host (`x-forwarded-host` or `host`). If a reverse proxy doesn't forward the public host, or the app is served from extra domains, list them in `experimental.serverActions.allowedOrigins`; when self-hosting several instances, set `NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` so all instances share the key.
+
+## 6. Metadata
+
+- Export `metadata` (static) or `generateMetadata` (dynamic) from `layout.tsx`/`page.tsx`. Only in Server Components.
+- Set `metadataBase` in the root layout so relative Open Graph URLs resolve.
+- Use `title.template` in the root layout (`"%s | Site"`) and plain `title` in pages.
+- File conventions: `opengraph-image.tsx`, `icon.tsx`, `sitemap.ts`, `robots.ts`. In 16 their `params` (and image `id`) are promises.
+- `generateMetadata` and the page share fetches through memoisation or `React.cache()`; don't fetch twice deliberately.
+- Viewport and theme colour go in `viewport`/`generateViewport`, not `metadata`.
+
+## 7. Middleware / proxy
+
+- 15: `middleware.ts` at the root (or `src/`), exporting `middleware` and `config.matcher`.
+- 16: rename to `proxy.ts` exporting `proxy`; it runs on the Node.js runtime only. If you need the Edge runtime, keep `middleware.ts` and tell the user. Don't blindly rename.
+- Keep it cheap: redirects, rewrites, header and cookie tweaks, optimistic auth redirects.
+- Never rely on it as the only authorisation check; re-check in pages, Route Handlers and Server Actions.
+- Always set a `matcher` that excludes `_next/static`, `_next/image` and static files.
+
+## 8. Environment variables
+
+- Only variables prefixed `NEXT_PUBLIC_` reach the browser, and they are **inlined at build time**. Changing them needs a rebuild; a Docker image built once can't pick up new public values at run time.
+- Never prefix a secret with `NEXT_PUBLIC_`. Read secrets only in server-only modules.
+- Load order: `.env.$(NODE_ENV).local`, `.env.local` (skipped when `NODE_ENV=test`), `.env.$(NODE_ENV)`, `.env`. Commit only non-secret defaults.
+- To read a server variable at request time rather than at build, make the code dynamic (`await connection()` from `next/server` first, 15+).
+- Validate required variables at startup (a small zod schema in `env.ts`) so a missing one fails loudly.
+
+## 9. Deployment pitfalls
+
+- Run `next build` locally before shipping; many errors (missing `Suspense` around `useSearchParams`, invalid segment config, missing `default.tsx` for parallel routes in 16) only appear there.
+- Self-hosting: use `output: "standalone"` for Docker and copy `public/` and `.next/static` into the image. With several instances, configure a shared cache handler or ISR results diverge per instance.
+- Images: configure `images.remotePatterns` (not the deprecated `domains`). In 16, `images.qualities` defaults to `[75]`.
+- Edge runtime has no Node APIs (`fs`, most DB drivers); keep DB access on the Node runtime.
+- Long work in a Server Action or Route Handler hits the host's function timeout; move it to a queue or background job.
+
+## Never
+
+- Never put `"use client"` on a layout or page just to make one hook work.
+- Never import a server-only module from a client file, or read `process.env.SECRET` in one.
+- Never trust that middleware/proxy or a hidden button protects a Server Action.
+- Never use the single-argument `revalidateTag(tag)` on 16, or `"use cache"` without `cacheComponents` enabled.
+
+## Stop and ask the user
+
+- Before enabling `cacheComponents`, the React Compiler or a major-version upgrade; each changes behaviour app-wide.
+- Before changing the runtime (`edge` vs `nodejs`) or the deployment output mode.
+- When it's unclear how fresh a piece of data must be.
+
+## Report back
+
+End with: routes and files changed, which components are client and why, the caching decision for each data source (cached for how long, invalidated by what), the `next build` result, and anything not verified in a production build.

package/skills/nextjs-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "My Next.js App Router page keeps showing old product prices after I update them in the admin",
+    "Where should I put 'use client' in this app/ layout so the header dropdown works?",
+    "Write a server action that creates a comment and revalidates the post page",
+    "We upgraded to Next 16 and now middleware.ts gives a deprecation warning, what do I change?",
+    "Add generateMetadata with Open Graph images to the app/blog/[slug] route",
+    "My NEXT_PUBLIC_API_URL is still the old value in the Docker deploy even though I changed the env var"
+  ],
+  "should_not_trigger": [
+    "Where should the selected-tab state live in my plain Vite React app?",
+    "Our Next.js bundle is huge, help me find which client components to code-split and measure with the Profiler",
+    "Review my Next.js pull request for server/client boundary leaks and hook bugs",
+    "Write a GitHub Actions workflow that builds and deploys our app",
+    "Set up a NestJS controller with validation pipes for the orders API",
+    "Configure Nuxt server routes and useFetch caching"
+  ]
+}

package/skills/nextjs-patterns/references/caching.md

@@ -0,0 +1,87 @@
+# Next.js caching: the two models
+
+Pick the model from `next.config.*`. If `cacheComponents: true` is set (Next.js 16+), use model B. Otherwise use model A. Write new code in the app's model; under model B, existing `fetch` cache options and `unstable_cache` keep working and can be migrated later, but segment config does not.
+
+Always check behaviour with `next build && next start`; `next dev` renders every request fresh.
+
+## Model A: previous model (no `cacheComponents`)
+
+Defaults (Next.js 15+):
+- `fetch` is **not** cached unless you opt in.
+- `GET` Route Handlers are not cached unless you opt in.
+- A route is still prerendered at build time if it uses no request-time API (`cookies()`, `headers()`, `searchParams`, uncached data after those). Fetches reached before any request-time API run once at build.
+
+Opt in per request:
+
+```ts
+await fetch(url, { cache: "force-cache" });                 // cache indefinitely
+await fetch(url, { next: { revalidate: 3600 } });           // time-based
+await fetch(url, { next: { tags: ["posts"] } });            // tag for on-demand invalidation
+await fetch(url, { cache: "no-store" });                     // always fresh
+```
+
+Non-`fetch` sources (ORM, SDK):
+
+```ts
+import { unstable_cache } from "next/cache";
+export const getUser = unstable_cache(
+  async (id: string) => db.user.findUnique({ where: { id } }),
+  ["user"],                       // key prefix; args are added to the key
+  { tags: ["user"], revalidate: 3600 },
+);
+```
+
+Route segment config (export from `page`, `layout` or `route`):
+
+| Export | Values | Use |
+|---|---|---|
+| `dynamic` | `'auto'` (default), `'force-dynamic'`, `'error'`, `'force-static'` | Force the whole segment static or dynamic |
+| `revalidate` | `false` (default), `0`, seconds | Default revalidation for the segment; must be a literal (`600`, not `60 * 10`) |
+| `fetchCache` | `'auto'`, `'default-cache'`, `'only-cache'`, `'force-cache'`, `'default-no-store'`, `'only-no-store'`, `'force-no-store'` | Advanced override; avoid unless needed |
+
+The lowest `revalidate` among a route's layouts, pages and fetches wins for the whole route.
+
+## Model B: Cache Components (`cacheComponents: true`, Next.js 16+)
+
+Nothing is cached unless marked. Uncached async work must sit inside `<Suspense>`, or the dev overlay and build report a blocking route.
+
+```ts
+import { cacheLife, cacheTag } from "next/cache";
+
+export async function getPosts() {
+  "use cache";
+  cacheLife("hours");          // always pair a directive with a lifetime
+  cacheTag("posts");
+  return db.post.findMany();
+}
+```
+
+- `"use cache"` at the top of a function or component caches its return value; at the top of a file it caches every export.
+- Arguments and closed-over values become part of the cache key. They must be serialisable.
+- Don't read `cookies()`/`headers()`/`searchParams` inside a `"use cache"` scope. Read them outside and pass the value in as an argument, or use `"use cache: private"`.
+- `"use cache: remote"` stores entries in a shared cache handler (durable across instances); the default store is in-memory per instance.
+- `Math.random()`, `Date.now()`, `crypto.randomUUID()` during render must be either inside `"use cache"` (same value for everyone) or after `await connection()` inside `<Suspense>` (per request).
+- Push `await params`/`await cookies()` down into the component that needs it, inside `<Suspense>`, so the rest of the layout stays in the static shell.
+- Segment config `dynamic`, `revalidate`, `fetchCache`, `dynamicParams` and `runtime` error in this model. Replace them with `"use cache"` + `cacheLife`, or plain uncached code for always-fresh data.
+- `generateStaticParams` must return at least one param; an empty array errors.
+- `"use cache"` entries are in-memory by default and scoped to one deployment, unlike the old `fetch` Data Cache. Use `"use cache: remote"` or a cache handler when entries must survive instance teardown.
+- Route state is preserved across navigations (React `<Activity>`), so `useState` and form values no longer reset when the user navigates away and back.
+
+## On-demand invalidation (both models)
+
+| API | Where | Effect |
+|---|---|---|
+| `revalidatePath(path)` | Server Action, Route Handler | Invalidate everything cached for a path |
+| `revalidateTag(tag, profile)` | Server Action, Route Handler | Mark tagged entries stale; next visitor gets stale data while it refreshes. Next.js 16 requires the second argument, for example `'max'`. On 15 it takes only the tag |
+| `updateTag(tag)` | Server Action only (16, either model) | Expire and refresh within the same request so the user sees their own write |
+| `refresh()` | Server Action only (16) | Refresh the client router without touching tags |
+
+Pick `updateTag` for forms and settings the user just edited, `revalidateTag` for content where a short delay is fine (catalogue, blog).
+
+## Debugging stale data
+
+1. Reproduce with `next build && next start`, not `next dev`.
+2. Find every cache layer between source and screen: the data cache entry, the route's prerendered output, the client router cache, a CDN in front.
+3. Check whether the data was read before a request-time API (model A: cached at build) or inside a `"use cache"` scope (model B).
+4. Check that the mutation calls the invalidation with the exact tag or path used when caching.
+5. Self-hosted with several instances: without a shared cache handler, each instance has its own cache and invalidation reaches only one.

package/skills/node-backend-patterns/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: node-backend-patterns
+description: Production rules for Node.js HTTP services written directly on Express or Fastify, without a full framework, including app/server split, schema validation of request input, centralised error middleware, graceful SIGTERM shutdown, structured pino logging, streaming with pipeline, helmet security headers, CORS and rate limiting. Use when starting or hardening an Express or Fastify service, adding request validation or an error handler, fixing dropped requests on deploy, or streaming large uploads and downloads.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js 18+ (prefer the current LTS) and the project's package manager.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# Node backend patterns (Express and Fastify)
+
+A Node service is production-ready when bad input is rejected at the edge, every error ends in one handler, logs are structured, and a deploy never cuts a request in half.
+
+## First, look at the project
+
+1. Read `package.json`: framework and major (`express` 4 vs 5, `fastify`), `"type"` (ESM or CJS), Node `engines`, existing validation (zod, TypeBox, Joi, ajv) and logger.
+2. Find the entry point and check whether app construction and `listen()` are separated.
+3. Keep the existing framework and libraries. Stop and ask the user before migrating Express to Fastify (or the reverse), or Express 4 to 5.
+
+If the project is NestJS, use the `nestjs-patterns` skill instead.
+
+## Structure
+
+```
+src/
+  app.ts        # builds and returns the app; no listen(), no process handlers
+  server.ts     # reads config, calls listen(), wires signals and shutdown
+  config.ts     # parses and validates env once at boot
+  routes/       # one router/plugin per resource
+  services/     # business logic, no req/res objects
+  errors.ts     # AppError classes with status and code
+```
+
+- `app.ts` exports a factory so tests can create the app without a port (`supertest(app)` for Express, `app.inject()` for Fastify).
+- Route handlers parse input, call a service, shape the response. Services never see `req`/`res`.
+- Validate config at boot (for example a zod schema over `process.env`) and exit with a clear message if anything is missing.
+
+## Validation at the edge
+
+- Validate `body`, `params`, `query` and relevant headers on every route that accepts input. Treat everything from the client as `unknown` until parsed.
+- **Fastify**: declare a JSON `schema` on the route (`body`, `querystring`, `params`, `response`). Fastify validates with ajv and serializes the response with fast-json-stringify, so a `response` schema keeps undeclared fields out of the output and stops columns leaking. Use TypeBox or a type provider for static types.
+- **Fastify's ajv defaults are not strict.** They are `removeAdditional: true`, `coerceTypes: 'array'` and `useDefaults: true`. So `additionalProperties: false` silently strips unknown fields instead of rejecting them, and `"5"` is coerced to `5`. If you need unknown fields rejected, set `ajv: { customOptions: { removeAdditional: false } }` on the Fastify instance. Never enable ajv `allErrors` on public routes, because it opens a DoS risk.
+- **Express**: a small middleware that runs `schema.safeParse(req.body)`, returns `400` with field errors on failure, and replaces `req.body` with the parsed value.
+- Set body limits explicitly (`express.json({ limit: '100kb' })`, Fastify `bodyLimit`) and reject unexpected content types.
+
+## Errors
+
+1. Define `AppError` subclasses with `status`, a stable `code` and a safe `message`.
+2. One error handler, registered last: Express `app.use((err, req, res, next) => ...)` with four arguments; Fastify `app.setErrorHandler(...)`.
+3. Known `AppError`: respond with its status and `{ error: { code, message } }`. Validation errors: `400` with field details. Anything else: log the full error with the request id and respond `500` with a generic message.
+4. **Express 4 does not catch rejected promises** from async handlers; wrap them or upgrade. Express 5 and Fastify forward rejections to the error handler.
+5. Also send a `404` JSON response for unmatched routes.
+6. Register `process.on('unhandledRejection')` and `uncaughtException` only to log and exit non-zero; never to keep running.
+
+## Graceful shutdown
+
+On `SIGTERM` (and `SIGINT` locally):
+
+1. Mark the service not ready so the readiness probe fails and the load balancer stops sending traffic. On Kubernetes, keep serving for a few seconds (or add a `preStop` sleep) so endpoint removal propagates before you close the listener.
+2. Stop accepting new connections: `server.close()` (Express/`http`) or `await app.close()` (Fastify, which also runs `onClose` hooks).
+3. Let in-flight requests finish; close idle keep-alive sockets with `server.closeIdleConnections()`.
+4. Close database pools, queue consumers and caches.
+5. Force exit with code 1 after a timeout shorter than the orchestrator's grace period (Kubernetes defaults to 30 seconds).
+
+Template in `references/templates.md`. Never call `process.exit()` before the server has closed.
+
+## Logging
+
+- Use `pino` (Fastify's built-in logger; `pino-http` for Express). JSON to stdout; pretty-print only in development.
+- Attach a request id to every log line (honour an incoming `x-request-id` or generate one) and return it in the response header.
+- Redact secrets: `redact: ['req.headers.authorization', 'req.headers.cookie', '*.password']`.
+- Never log full request bodies, tokens or card data. Never use `console.log` in request paths.
+
+## Streaming
+
+- Use `pipeline` from `node:stream/promises` to connect streams; it propagates errors and destroys every stream on failure. Never chain bare `.pipe()` without error handling.
+- Stream large files and exports instead of buffering them into memory. Set `Content-Type` and `Content-Disposition` before writing.
+- For uploads, use a streaming parser (`busboy`, `@fastify/multipart`) with size and file-count limits, and stream to storage.
+- Stop work when the client disconnects (listen for `close` on the request, or pass an `AbortSignal` to downstream calls).
+
+## Security
+
+- Headers: `helmet` (Express) or `@fastify/helmet`. Disable `x-powered-by` in Express (`app.disable('x-powered-by')`; helmet does this).
+- CORS: an explicit origin allowlist (`cors` / `@fastify/cors`). Never reflect any origin together with `credentials: true`.
+- Rate limiting: `express-rate-limit` or `@fastify/rate-limit`, stricter on login, signup and password reset. Use a shared store (Redis) when running more than one instance.
+- Behind a proxy, set `app.set('trust proxy', ...)` (Express) or `trustProxy` (Fastify) to the real hop count so client IPs and rate limits are correct; never `true` on a directly exposed server.
+- Set timeouts: `server.headersTimeout`, `server.requestTimeout`, and timeouts on every outbound HTTP and database call.
+- Run as a non-root user; keep `npm audit` or the `dependency-audit` skill in CI.
+
+## Never
+
+- Trust `req.body` types without validation.
+- Return raw error messages, stack traces or SQL errors to clients.
+- Do blocking CPU work (sync crypto, large `JSON.parse`, image processing) on the request thread; move it to a worker or queue.
+- Read `process.env` inside handlers.
+
+## Before you finish
+
+Run the project's lint, type-check and tests. Check by hand, or with a test: an invalid body returns 400, an unknown route returns 404 JSON, a thrown error returns a generic 500 and is logged with the request id, and `SIGTERM` during a slow request lets it complete. Report what changed, any new dependency, and any env variable the user must set.

package/skills/node-backend-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our Express API drops in-flight requests every time Kubernetes redeploys the pod",
+    "Add zod request validation and a single JSON error handler to this Express app",
+    "Set up a Fastify service with schema validation, helmet and rate limiting on login",
+    "Stream a large CSV export from Node without loading it all into memory",
+    "Replace console.log with structured pino logging and request ids in our Node server"
+  ],
+  "should_not_trigger": [
+    "Add a NestJS interceptor that maps every response into a data envelope",
+    "Write a Dockerfile with a multi-stage build for our Node service",
+    "Should we run our API on Bun instead of Node to speed up cold starts?",
+    "Design the versioning scheme and error format for our public REST API",
+    "Write Playwright tests for the checkout page"
+  ]
+}