rsc-universal 0.1.1

package/skills/no-code-app/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: no-code-app
+description: "Use when building an app on a no-code/low-code platform (Bubble, Softr, Glide, with Airtable/Xano backends) — picking the tool, modeling the data, taming usage/cost metering, or planning the exit before lock-in. Triggers: 'build a CRM without code', 'Bubble or Glide for my MVP', 'monta una app sin codi per reserves', 'my Bubble bill suddenly exploded' (workload-unit metering), 'Glide updates overage', 'how do I avoid getting locked into a no-code tool', 'when should I stop and write real code'. NOT a coded web app (that is nextjs)."
+tags: [no-code, low-code, bubble, glide, softr, app-builder, mvp]
+recommends: [nextjs, shopify, wordpress, automation-flows, spreadsheet-ops, notion-connector, stripe]
+origin: risco
+---
+
+# No-code app
+
+You are deciding whether to build an app on a visual platform, which platform, how to model it, and where the wall is. No-code is not "the easy way" — it is a trade: you buy speed-to-first-user and pay it back in logic ceilings and metered cost. Your job is to make that trade with eyes open.
+
+## The one rule
+
+Decide the exit before you build the entrance.
+
+- No-code wins on **speed-to-first-user** — a working app in days, no deploy pipeline. That is the only thing it reliably wins.
+- It dies on **deep conditional logic** and on **scale economics** — many-branch workflows get unmaintainable, and metering turns a $29 bill into a $400 one without warning.
+- ~25-30% of no-code projects get rewritten when they outgrow the tool, at $50K-$250K. ~68% of platforms offer no code export. If you cannot describe how you would leave, you are not building an MVP — you are building a hostage.
+
+## Step 0: is no-code even the right tool?
+
+Run this gate before touching any builder. If any line is a clear yes, route out — do not rationalize staying.
+
+| If the user really wants... | Stop and go to |
+| --- | --- |
+| A hand-written app, full control over code | [../nextjs/SKILL.md](../nextjs/SKILL.md) (or react) |
+| A commerce storefront, products + checkout | `shopify` |
+| A content site / blog / CMS | `wordpress` |
+| To wire SaaS tools together, no app UI | [../automation-flows/SKILL.md](../automation-flows/SKILL.md) |
+| A spreadsheet as the deliverable itself | [../spreadsheet-ops/SKILL.md](../spreadsheet-ops/SKILL.md) |
+| A Notion workspace, not a published app | [../notion-connector/SKILL.md](../notion-connector/SKILL.md) |
+
+No-code is the right tool when ALL hold: there is a real app UI (screens + data + logic), the logic is mostly CRUD + a handful of rules, time-to-launch matters more than scale today, and you accept the platform owns your runtime. If logic is the heart of the product (pricing engine, matching algorithm, real-time anything), no-code is wrong even if the UI is simple — write code.
+
+## Pick the platform
+
+Match the platform to the **app shape**, then to the **billing model** you will have to defend in six months. Why this order: the billing model, not the feature list, is what kills no-code projects.
+
+| App shape | Platform | Bills on | Why |
+| --- | --- | --- | --- |
+| Internal tool / client portal over existing data | **Softr** | Flat rate per workspace | No per-write metering, no charge for internal editors → predictable as you grow |
+| Customer-facing, simple, mobile-feel | **Glide** | "Updates" (data writes) | Fast to ship; cost scales with write volume, and rows are capped per plan (a standard source tops out far below Glide's own tables) — watch both |
+| Complex custom SaaS, heavy logic, custom workflows | **Bubble** | Workload Units (WU) | Most powerful builder; every query/workflow/API call burns WU, and tier allotments are small (Starter ~175K WU, Growth ~250K — only ~1.4x, not the 4x some stale write-ups claim) → cost is a function of usage, not seats |
+
+Rules:
+- **Default to Softr for anything that is "a nice front-end over a table."** Flat-rate billing means a usage spike does not become a surprise invoice.
+- **Reach for Bubble only when the logic genuinely needs it.** Bubble can do almost anything; that power is exactly why its WU bill is hard to predict. If you pick Bubble for a simple portal you are overpaying in money and complexity.
+- **If you find yourself fighting the builder to express logic, that is the signal to stop** and reconsider [../nextjs/SKILL.md](../nextjs/SKILL.md). The builder fighting back is the migration cliff sending a postcard.
+
+Exact tiers and numbers change — see [references/platform-limits.md](references/platform-limits.md). Do not hardcode prices into your design; design against the *metering model*.
+
+## Model the data first
+
+Tables and relations come before a single screen. Why: screens are cheap to rebuild, a wrong data model poisons every workflow and every cost estimate on top of it.
+
+Pick the backend by **logic complexity**, not by familiarity:
+
+| Backend | What it is | Use when | Watch out |
+| --- | --- | --- | --- |
+| Platform-native DB | Built into Bubble/Glide/Softr | Simple apps, one source of truth | Locked to the platform |
+| Airtable | Relational DB with a spreadsheet UI | Simple read/create, admin data entry | ~50K records/base cap, slow API |
+| Xano | Full backend (PostgreSQL + visual API builder) | Complex logic, performance, security | More setup; it is a real backend |
+
+The hybrid pattern that scales: **Airtable for human data entry/admin, Xano for API logic + performance + security.**
+
+Field-type and relation discipline:
+- Normalize. One entity = one table. A `bookings` row links to `customers` and `classes` by relation, it does not copy the customer's name and email into every booking.
+- Give every field its real type (date, number, single-select), not "text for everything." Wrong types make filters and aggregations expensive or impossible later.
+- Watch the **50K-record/base cap on Airtable** and the fact that on Bubble every relation traversal in a workflow is WU you pay for.
+
+Bad → Good:
+
+```text
+Bad  — one giant "Records" table, 40 columns, status in a text field,
+       customer name + email + class title all duplicated per row.
+       => filtering is slow, a rename means editing every row, WU/updates balloon.
+
+Good — customers | classes | bookings(customer→, class→, date, status:single-select)
+       => rename once, filter by relation, aggregate cleanly, predictable cost.
+```
+
+Sketch the model in plain text before you build it:
+
+```yaml
+customers: { id, name, email, phone }
+classes:   { id, title, starts_at, capacity, instructor }
+bookings:  { id, customer: ->customers, class: ->classes, status: [pending|paid|cancelled], created_at }
+payments:  { id, booking: ->bookings, amount, provider_ref }   # via stripe
+```
+
+## Build logic without footguns
+
+The metering model punishes the obvious-but-wrong way of doing things. Build defensively.
+
+- **Keep workflows shallow.** A 6-level nested conditional in a visual editor is unreadable and un-debuggable. If logic gets that deep, it belongs in code (Xano function or a real backend), not in the builder canvas.
+- **Batch writes; never loop an API call per row.** A workflow that fires one external API call per record across 2,000 rows is 2,000 metered operations — this is the #1 cause of an exploded Bubble WU bill and Glide update overage. Batch, or move the loop server-side.
+- **Validate server-side, not just in the UI.** Client-side-only validation in a no-code app is trivially bypassed; enforce rules in the backend (Bubble backend workflow, Xano endpoint) and gate writes with privacy/permission rules.
+- **Push expensive aggregation to scheduled jobs**, not to every page load. Recomputing a dashboard on each view multiplies reads by traffic.
+
+Bad → Good:
+
+```text
+Bad  — On booking confirmed: loop over all 2,000 customers, call email API per row.
+       => 2,000 metered ops every run; WU/update bill spikes; rate limits hit.
+
+Good — On booking confirmed: write one row; a scheduled batch job sends queued emails.
+       => one metered write per booking; sending is amortized and rate-safe.
+```
+
+## Know your limits and the cost ceiling
+
+The full 2026 tier/metering/record-cap table and worked cost examples live in [references/platform-limits.md](references/platform-limits.md). Operating rules:
+
+- **Estimate cost from the metering model, not the sticker price.** Bubble: count WU ≈ queries + workflow steps + API calls per user action, times expected actions/month. Glide: count data writes (updates) per user per month. A free or Starter tier that looks fine at demo traffic is the trap.
+- **Load-test at 10x expected rows, early.** A Bubble app that is snappy at 100 records can crawl at 10,000. Find the wall before your users do, not after.
+- **Know the hard caps**: Airtable ~50K records/base; per-tier app/user/row limits on every platform. Design so you do not silently hit one in month three.
+- **Watch the overage meters**: Bubble warns by email at 75% and 100% of your WU allotment, then charges overage. Wire those warnings to a human who can react.
+
+## Plan the exit
+
+This is the section everyone skips and everyone regrets. Do it on day 1.
+
+1. **Export your data on day 1 and on a schedule.** Confirm the platform actually lets you export records (~68% give you no code export — data export is the minimum you must verify).
+2. **Keep the data model portable.** Clean tables + relations (the model above) map onto Postgres/Prisma directly. A giant denormalized table does not.
+3. **Know your migrate-off triggers** and watch for them:
+   - Logic outgrows the canvas — many-branch conditionals, custom algorithms.
+   - Performance — it crawls at real row counts (the 10K-row test).
+   - Cost — the metered bill crosses what a real backend + hosting would cost.
+4. **Price the rewrite honestly.** Outgrowing the tool means a $50K-$250K rebuild. Knowing that number is what lets you decide *now* whether to start in code via [../nextjs/SKILL.md](../nextjs/SKILL.md) instead.
+
+When two of those triggers fire, stop adding features and start the migration plan — do not keep pouring work into a runtime you are about to leave.
+
+## Anti-patterns
+
+| Bad | Good | Why |
+| --- | --- | --- |
+| Reaching for Bubble because "no-code is faster" | Run Step 0 gate first | Coded apps/stores/blogs route to nextjs/shopify/wordpress |
+| Building screens, then bolting on data | Model tables + relations first | Wrong model poisons every workflow and cost estimate |
+| One giant table, 40 columns, text-typed everything | Normalized tables linked by relation | Cheap renames, fast filters, predictable metering |
+| Airtable for complex logic + scale | Xano (or hybrid: Airtable entry + Xano logic) | Airtable ~50K cap + slow API; Xano is a real backend |
+| Per-row API call in a workflow loop | Batch writes / scheduled jobs | #1 cause of WU/update bill explosions |
+| Client-side-only validation | Enforce rules server-side + permission gates | UI validation is trivially bypassed |
+| Pricing off the monthly sticker | Estimate from the metering model | WU/updates scale with usage, not the headline price |
+| Testing only at demo scale (100 rows) | Load-test at 10x expected rows early | Snappy at 100 can crawl at 10,000 |
+| No export plan, hope you never leave | Export day 1, keep model portable | 68% offer no code export; rewrite is $50K-$250K |
+| Picking Bubble for a simple internal portal | Softr (flat-rate) for portals over data | Predictable cost, no per-write surprise |
+
+## References
+
+- [references/platform-limits.md](references/platform-limits.md) — 2026 pricing/metering/record-cap cheatsheet (Bubble WU tiers, Glide updates, Softr flat tiers), backend comparison (native/Airtable/Xano), cost-estimation worked examples, and the migrate-off trigger list, with sources and access dates.
+
+Payments in any of these flows: see [../stripe/SKILL.md](../stripe/SKILL.md).

package/skills/no-code-app/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: no-code-app
+
+This is a process/judgment skill — there is no compiled artifact, so there is no `verify.sh` and no automated runner. Evaluate by hand: read `cases.yaml` against `SKILL.md`. For each `should_trigger` prompt, confirm the description's "Use when…/Triggers:" line would plausibly route an agent here; for each `should_not_trigger`, confirm the named `route_to` sibling is the better home and that this skill's boundary (`NOT a coded web app (that is nextjs)`) sends it away. The `capability` case is a rubric check: an agent following the skill on the yoga-studio brief should produce all five `must_include` items — Step 0 gate, a platform pick justified by app shape + billing model, a normalized data model with a named backend, a metered cost/limit estimate with a load-test note, and an exit/export plan. If any are missing, the SKILL.md body needs tightening.

package/skills/no-code-app/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: no-code-app
+
+should_trigger:
+  - prompt: "Build a CRM for my team without writing code"
+    why: Core no-code build request — app UI + data + light logic, no code.
+  - prompt: "Should I use Bubble or Glide for my MVP?"
+    why: Platform-choice question this skill owns the decision table for.
+  - prompt: "Monta una app sin codi per gestionar reserves del gimnàs"
+    why: Catalan phrasing for building a no-code booking app.
+  - prompt: "My Bubble app's monthly bill suddenly exploded — what happened?"
+    why: Non-obvious; symptom of Workload-Unit metering (per-row loops / unbatched writes).
+  - prompt: "How do I avoid getting locked into a no-code tool?"
+    why: Non-obvious; the exit/lock-in planning this skill insists on up front.
+  - prompt: "Airtable or Xano as the backend for my Softr app?"
+    why: Backend-by-logic-complexity decision, squarely in scope.
+
+should_not_trigger:
+  - prompt: "Build this web app in Next.js with a Postgres backend"
+    route_to: nextjs
+    why: Hand-written coded app, full control — not a visual builder.
+  - prompt: "I want to open an online store"
+    route_to: shopify
+    why: Commerce storefront, not a general-purpose app.
+  - prompt: "Connect my Stripe payments to a Google Sheet, no app needed"
+    route_to: automation-flows
+    why: Tool-to-tool wiring with no app UI.
+  - prompt: "Set up a blog / content site"
+    route_to: wordpress
+    why: CMS / content site, not an app with custom data + logic.
+  - prompt: "Clean up and pivot this spreadsheet of sales data"
+    route_to: spreadsheet-ops
+    why: The sheet itself is the deliverable, not a backend for an app.
+
+capability:
+  - scenario: >
+      Design a no-code booking app for a yoga studio (classes, bookings, payments)
+      and decide whether no-code is even the right call.
+    must_include:
+      - runs the Step 0 gate and confirms no-code is appropriate vs writing code (nextjs)
+      - picks a platform with a reason tied to app shape AND its billing model (Softr flat / Glide updates / Bubble WU)
+      - models the data as normalized tables + relations before screens; names a backend choice (native / Airtable / Xano) by logic complexity
+      - estimates the limit/cost ceiling (WU, updates, or record cap) and includes a load-test-at-10x note
+      - includes an exit/export plan (export day 1, portable model, migrate-off triggers, rewrite cost)

package/skills/no-code-app/references/platform-limits.md

@@ -0,0 +1,100 @@
+# Platform limits cheatsheet (2026)
+
+Dated numbers live here so SKILL.md stays evergreen. Design against the *metering model*, not these exact figures — re-verify before quoting a price to anyone.
+
+## Bubble — metered by Workload Units (WU)
+
+Every DB query, workflow run, and API call burns WU. Cost is a function of usage, not seats.
+
+| Tier | Price (web) | WU/month |
+| --- | --- | --- |
+| Free | $0 | ~50K (dev/trial) |
+| Starter | $29/mo | 175K |
+| Growth | $119/mo | 250K |
+| Team | $349/mo | 500K |
+| Enterprise | custom | custom |
+
+- The allotments are small and the steps between tiers are small — Growth's 250K is only **~1.43x** Starter's 175K. A widely-repeated older claim put Growth at **1M WU** (a 4x jump); that figure is stale and unsupported by any current source — do not design around it. Plan around the metering, not the tier names.
+- Prices shift with billing choice: the figures above are **web-only, annual billing**. Web+mobile and monthly billing run higher (e.g. Starter up to ~$59, Team up to ~$549); the WU allotments per tier stay 175K / 250K / 500K across those variants.
+- Overage: extra WU is sold in packs (≈ $0.30 per 1,000 WU as a rough run rate) beyond the tier allotment — verify the current pack pricing before quoting.
+- Warning emails at **75%** and **100%** of allotment — wire these to a human.
+- Source: goodspeed.studio "Bubble.io Pricing 2026" (last updated 2026-05-29, verified against the official pricing page), adalo.com/posts/bubble-pricing, lowcode.agency Bubble pricing, manual.bubble.io pricing-plans, bubble.io/pricing (re-verified 2026-06-02). Three independent write-ups plus the Bubble docs agree on 175K / 250K / 500K WU.
+
+## Glide — metered by "updates" (data writes)
+
+Billed on writes, not seats. Cost is unpredictable as write volume grows.
+
+| Tier | Price | Notes |
+| --- | --- | --- |
+| Free | $0 | Draft apps; up to 25K rows |
+| Maker | $25/mo | personal/community apps, more features than Free |
+| Team | $99/mo | unlimited apps, 20 users, 5K updates/mo, Glide Basic API |
+| Business | $249/mo | unlimited apps, 30 users, 5K updates/mo, rows capped: ~25K with an external/standard source, ~100K with Glide (Big) Tables |
+
+- The Business row cap is real and load-bearing: a standard/external data source tops out around **25K rows**; you only reach **~100K rows** on Glide's own (Big) Tables. Pick the data source with that ceiling in mind.
+- Update overage beyond the monthly allotment is charged per extra update — confirm the current per-update rate before quoting.
+- Source: glideapps.com/pricing, adalo.com/posts/glide-pricing, costbench.com Glide 2026, Glide community "Data rows in business plan? 25000 or 100000?" (verified 2026-06-02).
+
+## Softr — flat-rate per workspace (not metered)
+
+No per-write metering; no charge for internal editors → the most predictable scaling of the three.
+
+| Tier | Price | Notes |
+| --- | --- | --- |
+| Basic | ~$49/mo (annual) | 3 apps, 20 app users, **10,000 records/base** (50,000 records/workspace) for the Softr DB; custom code, payments |
+| Professional | ~$139/mo | 50,000 records/base (500,000/workspace) |
+| Business | ~$269/mo | 200,000 records/base (1,000,000/workspace) |
+
+- The Basic per-base cap is **10,000 records**, *not* 50K. The 50K figure is the **per-workspace** total across bases — easy to mistake for the per-base limit, which is the one a single dataset actually hits. Size against the 10K-per-base number early.
+- External/advanced data sources (SQL, BigQuery, Xano, Supabase) get much higher per-app limits (Basic ~500K), so the 10K cap bites hardest on the native Softr DB.
+- Source: softr.io/pricing (re-verified 2026-06-02 — Basic 10,000/base, 50,000/workspace), docs.softr.io pricing-and-plans, Softr community "Database Limits for Basic Plan", adalo.com/posts/softr-pricing.
+
+## Backend comparison
+
+| | Airtable | Xano |
+| --- | --- | --- |
+| What | Relational DB with a spreadsheet UI | Full backend: PostgreSQL + visual API builder |
+| Record cap | ~50K records/base on the common Team tier (Free 1K, Business 125K) — cumulative across the base's tables | Scales (real DB) |
+| API speed | Slow | <200ms typical |
+| Best for | Simple read/create, admin data entry | Complex logic, performance, security, scale |
+
+Note the Airtable per-base cap (~50K on Team) is a *different* number from Softr's Basic per-base cap (10K) — don't conflate them. The Airtable limit counts all records across all tables in one base.
+
+Hybrid pattern: **Airtable for human data entry/admin, Xano for API logic + perf + security.**
+
+Source: airtable.com/pricing (Team ~50K/base, Business 125K — re-verified 2026-06-02), xano.com/versus/xano-vs-airtable, minimum-code.com, adalo.com.
+
+## Cost-estimation worked examples
+
+**Bubble (WU):** estimate WU per user action ≈ (DB queries + workflow steps + API calls) it triggers. Multiply by expected actions/month.
+
+```text
+1 booking action ≈ 3 queries + 4 workflow steps + 1 payment API call ≈ ~8 WU
+2,000 bookings/mo  => ~16K WU just for bookings (comfortably under Starter's 175K)
+add page loads, searches, dashboards, scheduled jobs => easily 100K-300K WU/mo
+=> the overhead, not the bookings, is what eats the budget: 100K-300K WU lands you
+   on the edge of Starter (175K) and quickly past it — Growth only buys 250K, so a
+   single feature that loops an API call per row pushes you to overage, not just a
+   tier bump. Budget against total WU, not the headline booking count.
+```
+
+**Glide (updates):** count data writes per user per month.
+
+```text
+Each user: ~10 writes/visit x 8 visits/mo = ~80 updates/user/mo
+500 users => ~40K updates/mo, on top of tier allotment, overage ~$0.02 each.
+```
+
+**Softr (flat):** the same workloads cost the tier price regardless of write volume — this is why it is the predictable choice for portals.
+
+## Migrate-off trigger list
+
+Stop adding features and start the migration plan when **two or more** fire:
+
+1. **Logic outgrows the canvas** — many-branch conditionals, custom algorithms that fight the visual builder.
+2. **Performance wall** — the app crawls at real row counts (snappy at 100, slow at 10,000; load-test at 10x early).
+3. **Cost crossover** — the metered bill exceeds what a real backend + hosting would cost.
+
+Context: ~25-30% of no-code projects get rewritten when they outgrow the tool; rebuild cost **$50K-$250K**; ~68% of platforms offer **no code export** (verify data export on day 1).
+
+Source: weweb.io code-export buyer's guide, nocodefinder.com vendor lock-in, designrevision.com platform comparison (accessed 2026-06-02).

package/skills/nodejs/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: nodejs
+description: "Use when building or structuring a plain Node.js / Express backend service — project layout, async correctness, central error handling, config validation, and graceful shutdown — the runtime and HTTP service, not a DI framework. Triggers: 'set up an Express 5 service', 'my async route error returns 200 with an empty body', 'where do controllers vs services go', 'centralize error handling middleware', 'shut down cleanly on SIGTERM without dropping requests', 'why does one unhandled promise rejection crash my server', 'monta un backend con Express y manejo de errores', 'apaga el servidor sin perder peticiones en vuelo'. NOT NestJS DI/modules/guards (that is nestjs); NOT the TS type system/tsconfig (that is typescript); NOT REST contract/versioning (that is api-design)."
+tags: [nodejs, express, backend, async, error-handling]
+recommends: [nestjs, typescript, api-design, error-handling, postgresdb]
+origin: risco
+---
+
+# Node.js backend services
+
+Stand up a plain Node.js HTTP/JSON service — `node:http` or Express 5 — that a person can read, test, and operate without a DI framework. This skill is about the runtime and the request lifecycle: how to lay out the code, how to keep async correct, how errors become status codes, how config fails fast, and how the process dies cleanly. The contract shape, the type system, and the data layer live elsewhere (see the boundaries below).
+
+## Use this when
+
+- Standing up a new HTTP/JSON service on Node with Express 5 (or bare `node:http`).
+- Structuring routes / controllers / services / repositories in a non-DI app.
+- Fixing async bugs: floating promises, swallowed errors, callbacks not awaited.
+- Centralizing error handling and the 404/500 contract in one place.
+- Graceful shutdown on SIGTERM, env validation at boot, the request lifecycle.
+- Choosing CommonJS vs ESM and pinning a runtime.
+
+## Not this when
+
+- The app is built around `@Module` / `@Injectable` / DI providers, guards, interceptors, pipes, exception filters → `../nestjs/SKILL.md`. Nest starts the moment the DI container appears; route away then, do not half-build it here.
+- Pure TypeScript type system, generics, `tsconfig` → `../typescript/SKILL.md`. This skill uses TS but does not teach types.
+- REST resource modeling, versioning, pagination, status-code semantics (framework-agnostic) → api-design. This skill *wires* the handlers; api-design decides the contract.
+- Schema, queries, connection pool, migrations → `../postgresdb/SKILL.md` / prisma-orm / drizzle-orm. *Calling* a repository stays here; designing the table does not.
+- Containerizing / shipping → docker / deployment. Choosing the logging/metrics/tracing stack → observability. This skill emits structured logs and a shutdown hook; it does not own the pipeline.
+
+## Decide first
+
+Pick the runtime shape before writing code — the wrong choice is expensive to undo.
+
+| Situation | Choice | Why |
+| --- | --- | --- |
+| Needs DI/modules, large team, heavy cross-cutting | route to `../nestjs/SKILL.md` | Don't reinvent a DI container by hand |
+| Small/medium JSON API, want middleware + routing | Express 5 | Mature, async errors auto-forward (v5) |
+| One tiny endpoint, zero deps, a healthcheck | `node:http` | No dependency surface to maintain |
+| A library, not a server | not this skill | No request lifecycle to manage |
+
+Defaults for a new service: pin **Node 24 (Active LTS)** in `engines.node`; Node 22 is Maintenance LTS; Node 26 is Current (released 2026-05-05, enters LTS Oct 2026) — adopt it only if you want Temporal/V8 14.6 and can track Current. Write **ESM** for new code (`"type": "module"`), CommonJS only when a hard dependency forces it.
+
+```jsonc
+// package.json
+{
+  "type": "module",
+  "engines": { "node": ">=24" },
+  "scripts": {
+    "dev": "node --watch src/server.ts",
+    "test": "node --test"
+  }
+}
+```
+
+## Project layout
+
+Concrete tree. The names are conventions, not magic — but the split is load-bearing.
+
+```text
+src/
+  app.ts          # build + return the Express app; NEVER calls listen()
+  server.ts       # imports app, listens, owns SIGTERM/shutdown
+  config/
+    env.ts        # validate process.env once, export a typed `config`
+  routes/
+    users.ts      # router only: path → controller
+  controllers/
+    users.ts      # parse request, call service, shape response
+  services/
+    users.ts      # business logic, no req/res objects
+  repositories/
+    users.ts      # data access; the only layer that touches the DB
+  errors/
+    app-error.ts  # AppError/HttpError with status + code
+```
+
+**Rule — separate app construction from `listen()`.** `app.ts` builds and returns the app; `server.ts` binds the port and owns shutdown. Why: tests import `app` and exercise routes in-process without binding a port, so they run fast and in parallel.
+
+```ts
+// Bad: index.ts listens at import time — untestable, double-binds in tests
+const app = express();
+app.get("/health", (_req, res) => res.json({ ok: true }));
+app.listen(3000); // side effect on import
+
+// Good: app.ts
+export function buildApp() {
+  const app = express();
+  app.get("/healthz", (_req, res) => res.json({ ok: true }));
+  return app; // no listen here
+}
+```
+
+## Async rules
+
+Every async mistake here is a latent production incident, not a style nit.
+
+- **Await or return every promise.** A floating promise is a latent process crash — since Node 15 an unhandled rejection terminates the process by default. The error happens later, detached from its handler.
+- **Never mix callback + promise styles.** Promisify once at the boundary (`util.promisify` or `fs/promises`) and stay in promises after that. Half-converted code swallows errors.
+- **`Promise.all` for independent work; sequential `await` only for true dependencies.** Awaiting independent calls one by one wastes wall-clock time.
+- **Use `AbortSignal.timeout(ms)` for per-operation deadlines** and thread the signal into `fetch`/DB/long ops. Compose with `AbortController` so shutdown can cancel in-flight work (see graceful shutdown).
+- **Never rely on a global `unhandledRejection` handler as control flow.** Log and exit there if anything; do not use it to keep running.
+
+```ts
+// Bad: forgotten await — the rejection floats and crashes later, error lost
+function handler(req, res) {
+  saveAudit(req.body);          // returns a promise nobody awaits
+  res.json({ ok: true });       // responds before save resolves/rejects
+}
+
+// Good: await it (Express 5 forwards a throw to the error middleware)
+async function handler(req, res) {
+  await saveAudit(req.body);
+  res.json({ ok: true });
+}
+```
+
+## Error handling
+
+This is the core, and the most common bug. In **Express 5 an async handler that rejects or throws is auto-forwarded to the error middleware** — no `try/catch + next(err)` wrapper, no `asyncHandler`. Source: Express 5 migration guide and the framework's own router tests (a value-less `Promise.reject()` becomes an Error with message `Rejected promise`).
+
+- Define one `AppError` (or `HttpError`) carrying `status` and `code`. Throw it from services; controllers don't translate.
+- Register **exactly one 4-arg `(err, req, res, next)` error middleware, LAST**, after every route. **Arity is what makes Express treat it as an error handler** — a 3-arg function is a normal middleware no matter what you name it. Order still matters in v5.
+- A 404 fallthrough handler goes *just before* the error middleware.
+- Map known errors → their status; unknown → 500; **never leak the stack or raw message in production.**
+
+```ts
+// errors/app-error.ts
+export class AppError extends Error {
+  constructor(public status: number, public code: string, message: string) {
+    super(message);
+  }
+}
+
+// app.ts — registration ORDER (routes → 404 → error handler)
+app.use("/users", usersRouter);
+
+app.use((_req, res) => res.status(404).json({ code: "not_found" }));
+
+// LAST, exactly 4 args — this is the error handler
+app.use((err, _req, res, _next) => {
+  const status = err instanceof AppError ? err.status : 500;
+  const code = err instanceof AppError ? err.code : "internal_error";
+  if (status >= 500) logger.error({ err }, "unhandled");
+  res.status(status).json({
+    code,
+    message: status < 500 ? err.message : "Internal Server Error",
+    ...(process.env.NODE_ENV !== "production" && { stack: err.stack }),
+  });
+});
+```
+
+```ts
+// Bad: the symptom "async route throws but client gets 200 empty body"
+app.use((err, _req, res, _next) => { /* error handler */ });  // registered FIRST
+app.get("/users/:id", async (req, res) => {
+  const u = await findUser(req.params.id);   // throws NotFound
+  res.json(u);                                // never reached; no handler after → hangs/empties
+});
+```
+
+The error handler placed before the route never sees the throw, so the response is whatever was half-written. Put it last. See `references/express5-migration.md` for the full v4→5 breaking-change checklist and the legacy v4 `asyncHandler` wrapper.
+
+## Config & secrets
+
+Validate `process.env` once at boot, fail fast, and export a typed `config` object. **A missing variable should crash at startup, not at 3am on first use.** Ban scattered `process.env.X` reads throughout the codebase — they hide the contract and defeat the boot check.
+
+```ts
+// config/env.ts — hand-rolled or zod/envalid; the point is one gate
+import { z } from "zod";
+const schema = z.object({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+});
+export const config = schema.parse(process.env); // throws → process won't start
+```
+
+## Graceful shutdown
+
+On SIGTERM the orchestrator gives you a brief window to finish. Drop nothing.
+
+1. Flip readiness to **not-ready** so the load balancer stops routing new traffic.
+2. `server.close()` — stop accepting new connections, let in-flight requests finish.
+3. Abort long-running work via a shared `AbortController` (the signal you threaded into ops).
+4. Close the DB pool and other resources.
+5. `process.exit(0)`, with a force-exit timer as a backstop if drain stalls.
+
+Expose `/healthz` (liveness — is the process up) separately from `/readyz` (readiness — should it receive traffic). They answer different questions; conflating them causes both false restarts and dropped requests during deploys. The full copy-pasteable `server.ts` lives in `references/graceful-shutdown.md`.
+
+```ts
+// server.ts (sketch — full version in references/)
+const controller = new AbortController();
+const server = buildApp().listen(config.PORT);
+
+function shutdown() {
+  ready = false;                       // /readyz now 503
+  server.close(() => process.exit(0)); // drain, then exit
+  controller.abort();                  // cancel in-flight long ops
+  setTimeout(() => process.exit(1), 10_000).unref(); // backstop
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+```
+
+## Testing
+
+Node 24 ships a built-in test runner — `node:test` with `node --test` — so a backend needs no external runner for unit/integration tests, and `node --watch` for dev. **Import `app` from `app.ts` and hit it directly** (supertest or `undici`); never start the live server in a test. That is exactly why `app.ts` doesn't call `listen()`.
+
+```ts
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import request from "supertest";
+import { buildApp } from "../src/app.ts";
+
+test("404 returns the error contract", async () => {
+  const res = await request(buildApp()).get("/nope");
+  assert.equal(res.status, 404);
+  assert.equal(res.body.code, "not_found");
+});
+```
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| Floating promise (no `await`/`return`) | Unhandled rejection crashes the process (Node 15+), error detached | Await or return every promise |
+| Error middleware with 3 args or not last | Express never treats it as an error handler; throws fall through | 4 args `(err,req,res,next)`, registered LAST |
+| Reading `process.env.X` everywhere | Missing var fails at 3am, contract is invisible | Validate once in `config/env.ts`, export typed `config` |
+| `listen()` inside `app.ts` | Side effect on import; tests bind a port / double-listen | `app.ts` returns app, `server.ts` listens |
+| `catch (e) {}` then continue | Swallows the failure, masks the bug | Re-throw, or map to an `AppError` |
+| `process.exit()` without draining | Drops in-flight requests on deploy | SIGTERM → `server.close()` → abort → exit |
+| Global `unhandledRejection` as control flow | Hides bugs, leaves process in a bad state | Log + exit there; fix the floating promise |
+| Assuming Express 4 defaults | v5: `urlencoded` `extended:false`, `static` `dotfiles:"ignore"` | Read `references/express5-migration.md` |
+| Leaking stack/message in prod | Information disclosure | Stack only when `NODE_ENV !== "production"` |
+
+## References & siblings
+
+- `references/express5-migration.md` — full Express 4→5 breaking changes, middleware-order diagram, the legacy v4 `asyncHandler` wrapper.
+- `references/graceful-shutdown.md` — complete `server.ts`: signal handlers, `AbortController`, readiness gate, force-exit backstop.
+- DI/modules/guards → `../nestjs/SKILL.md`. Type system/tsconfig → `../typescript/SKILL.md`. Data layer → `../postgresdb/SKILL.md`. Contract design → api-design. Cross-cutting error taxonomy → error-handling.
+
+`scripts/verify.sh` statically lints a produced repo for these rules (4-arg error handler last, no `listen()` in `app.ts`, `engines.node` supported, floating-promise heuristic). Advisory; hard-fails only on `listen()` in `app.ts` or a missing error handler.

package/skills/nodejs/evals/README.md

@@ -0,0 +1,3 @@
+# Evals: nodejs
+
+These cases are run by the repository's eval harness against the skill router. Each `should_trigger` prompt expects the router to select `nodejs`; each `should_not_trigger` prompt expects it to select the named sibling instead (`route_to`), guarding the boundaries against `nestjs`, `typescript`, `api-design`, and `postgresdb`. The single `capability` case is graded by a judge against its `must_include` rubric — it checks that a scaffolded Express 5 service splits `app.ts` from `server.ts`, has one 4-arg error handler last, validates env at boot, and shuts down gracefully. Run them with the repo's standard eval command pointed at this skill directory; there is no separate setup beyond the harness itself.

package/skills/nodejs/evals/cases.yaml

@@ -0,0 +1,39 @@
+skill: nodejs
+
+should_trigger:
+  - prompt: "Set up an Express 5 service with a central error handler and graceful shutdown."
+    why: "Core greenfield plain-Node/Express service — layout, error handling, shutdown."
+  - prompt: "My async route throws but the client gets a 200 with an empty body."
+    why: "Non-obvious symptom of a mis-ordered or missing 4-arg error middleware in Express 5."
+  - prompt: "Where should controllers, services and repositories live in my Node API?"
+    why: "Non-DI service structure is exactly this skill's project-layout concern."
+  - prompt: "Why does one unhandled promise rejection crash my whole Node server?"
+    why: "Node 15+ runtime async semantics — floating promise as a latent crash."
+  - prompt: "Monta un backend con Express y apaga el servidor sin perder peticiones en vuelo."
+    why: "Spanish; graceful shutdown / draining in-flight requests on a plain Express service."
+
+should_not_trigger:
+  - prompt: "Wire a custom provider with useFactory in my NestJS module."
+    route_to: "nestjs"
+    why: "DI container, modules and providers are NestJS, not a bare Node/Express service."
+  - prompt: "Make this generic helper preserve the literal type and fix my tsconfig."
+    route_to: "typescript"
+    why: "Pure TypeScript type system and tsconfig, not the Node runtime."
+  - prompt: "Design the REST resource URLs, versioning and pagination for our public API."
+    route_to: "api-design"
+    why: "Framework-agnostic contract design; this skill wires handlers, it does not shape the contract."
+  - prompt: "Set up the Postgres connection pool and write the user query."
+    route_to: "postgresdb"
+    why: "Data layer / schema / queries belong to the database skill, not the HTTP service."
+
+capability:
+  - scenario: "A user asks to scaffold a production-ready Express 5 JSON service."
+    must_include:
+      - "app.ts builds and returns the app; server.ts owns listen() and shutdown."
+      - "Exactly one 4-arg (err,req,res,next) error middleware registered LAST, with a 404 fallthrough just before it."
+      - "Typed AppError carrying status + code; known errors mapped to status, unknown to 500, no stack leak in production."
+      - "Environment validated once at boot (fail fast), exported as a typed config; no scattered process.env reads."
+      - "SIGTERM handler: flip readiness to not-ready, server.close() to drain, abort in-flight via AbortController, then exit, with a force-exit backstop."
+      - "Tests use node:test and import the app from app.ts rather than starting the live server."
+      - "engines.node pinned to a supported LTS (Node 24); ESM for new code."
+      - "Routes DI/modules to nestjs, contract design to api-design, and the data layer to postgresdb."

package/skills/nodejs/references/express5-migration.md

@@ -0,0 +1,53 @@
+# Express 4 → 5 migration & middleware order
+
+Express 5.2.x is current and requires Node.js 18+. Source: npm `express`, Express 5 migration guide (accessed 2026-06-02). Use this as the offloaded depth referenced from SKILL.md.
+
+## Breaking changes that bite a backend
+
+| Area | v4 | v5 | Action |
+| --- | --- | --- | --- |
+| Async errors | a rejected/thrown async handler hangs unless wrapped | auto-forwarded to the 4-arg error middleware | Delete `asyncHandler` wrappers; just `throw` / reject |
+| `express.urlencoded` | `extended: true` default | `extended: false` default | Pass `{ extended: true }` explicitly if you relied on rich objects |
+| `express.static` dotfiles | `"allow"` for some setups | `dotfiles: "ignore"` default | Set `{ dotfiles: "allow" }` only if you intend to serve `.well-known` etc. |
+| Path matching | older path-to-regexp | newer path-to-regexp; some wildcard/optional syntaxes changed | Re-test `:param?`, `*`, and regex routes; name your wildcards |
+| Removed/renamed | `res.json(status, obj)`, `app.del`, `req.param(name)` | removed | Use `res.status(s).json(obj)`, `app.delete`, `req.params`/`req.query`/`req.body` |
+
+## Auto async error catch — what it actually guarantees
+
+The framework's own router tests confirm: an `async` handler that rejects, or returns `Promise.reject(err)`, reaches the 4-arg error handler. A value-less `Promise.reject()` is surfaced as an `Error` with message `Rejected promise`. So in v5 you write:
+
+```ts
+// v5 — no wrapper
+app.get("/users/:id", async (req, res) => {
+  const u = await findUser(req.params.id); // throw NotFound → error middleware
+  res.json(u);
+});
+```
+
+```ts
+// v4 legacy wrapper — ONLY if you are still on Express 4
+const asyncHandler = (fn) => (req, res, next) =>
+  Promise.resolve(fn(req, res, next)).catch(next);
+app.get("/users/:id", asyncHandler(async (req, res) => { /* ... */ }));
+```
+
+What auto-catch does NOT cover: a promise you never awaited or returned inside the handler (a floating promise). That still escapes to the process, not the error middleware. Await everything.
+
+## Middleware order (still matters in v5)
+
+Order of registration is order of execution. The error handler is selected by arity (4 args), not by name or position alone — but it only catches what is registered *before* it.
+
+```text
+  app.use(express.json())            parsers, security headers
+        │
+        ▼
+  app.use("/users", usersRouter)     routes (may throw → forwarded down)
+        │
+        ▼
+  app.use((req,res) => 404)          fallthrough: nothing matched
+        │
+        ▼
+  app.use((err,req,res,next) => ...) ERROR HANDLER — 4 args, registered LAST
+```
+
+A 4-arg function registered *before* the routes is skipped for normal requests and can never catch a route's throw. Put it last, exactly once.