@damiangilgonzalez/harness 1.3.7

package/skills/translation-l10n/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: translation-l10n
+description: "Use when adding a second or Nth language to a web or app product — i18n plumbing (string extraction, ICU messages, locale routing), fixing broken plurals or date formats, and making a UI survive other languages through right-to-left layout and text expansion. NOT defining the brand's tone in one language (that is `brand-voice`)."
+tags: [i18n, l10n, internationalization, localization, translation, rtl, icu-messageformat]
+recommends: [brand-voice, nextjs, seo-geo, accessibility, content-engine]
+origin: risco
+---
+
+# Translation & localization
+
+You are making a product speak more than one language *correctly* — not word-for-word. The job splits in two, and confusing them is the root cause of "we translated everything but the dates are still American."
+
+- **i18n (internationalization)** = engineering the code so it *can* hold any locale: no hardcoded strings, externalized catalogs, locale-aware formatting, locale routing. Done once.
+- **l10n (localization)** = the per-locale *content* and cultural formatting: the actual translations, plural rules, date/number/currency conventions, RTL layout. Done per language, repeatedly.
+
+Sequence matters: do i18n first. Teams that skip it end up retrofitting string extraction under a launch deadline, which is when concatenation and `count === 1` bugs ship.
+
+## Route out fast
+
+| If the task is really about… | Go to |
+| --- | --- |
+| Inventing the brand's tone/word bank in one language | `../brand-voice/SKILL.md` |
+| App Router structure, RSC, data fetching (non-locale) | `../nextjs/SKILL.md` |
+| hreflang strategy, per-country keyword research, geo ranking | `../seo-geo/SKILL.md` |
+| Authoring net-new source copy (landing, article) | `../content-engine/SKILL.md` |
+| General a11y semantics beyond `lang`/`dir`/bidi | `../accessibility/SKILL.md` |
+
+This skill emits the `lang`/`dir`/alternate plumbing and only touches routing where it is locale-specific. It does not author source copy or invent voice — it moves an existing voice across languages.
+
+## Decision: where are you?
+
+| Symptom | Enter |
+| --- | --- |
+| Hardcoded strings live in JSX/components | Phase 1 — internationalize the code |
+| Plurals/gender are wrong in some language | Phase 2 — ICU MessageFormat |
+| Dates/numbers/currency look wrong per locale | Locale-aware formatting (`Intl.*`) |
+| Layout breaks, text overflows, Arabic mirrored wrong | Phase 3 routing + RTL & bidi |
+| "We have the strings, we need them translated" | Phase 4 — translation workflow |
+
+## Phase 1 — internationalize the code
+
+**Externalize every user-facing string to a catalog.** A string in JSX cannot be translated, pseudolocalized, or counted as missing. Move it to a message file keyed by a stable, namespaced ID.
+
+**Key on intent, not on the English text.** `checkout.payButton` survives a copy change; `"Pay now"` as the key breaks every translation the moment marketing edits the English.
+
+```json
+{
+  "checkout": {
+    "payButton": "Pay now",
+    "itemsInCart": "{count, plural, one {# item} other {# items}}"
+  }
+}
+```
+
+**Library choice — pick once:**
+
+| Stack / need | Use | Why |
+| --- | --- | --- |
+| Next.js App Router | `next-intl` | Request-scoped `i18n/request.ts` + `defineRouting()`, RSC-native, `localePrefix` strategies |
+| Cross-stack / existing i18next ecosystem | `next-i18next` / `i18next` | Shared catalogs across React Native, backend, plugins |
+| Tiny app, few strings, no plural complexity | `Intl` only | No dependency; you still get correct formatting |
+
+**Never concatenate translated fragments.** Word order is not universal — building a sentence from pieces produces garbage in languages that reorder subject/object/verb.
+
+```tsx
+// Bad — three fragments the translator can never reorder
+<p>{t("youHave")} {count} {t("messages")}</p>
+
+// Good — one message, named/numeric ICU argument
+<p>{t("inbox.summary", { count })}</p>
+// "inbox.summary": "{count, plural, one {You have # message} other {You have # messages}}"
+```
+
+**Configure a fallback locale.** A missing key in `de` should resolve to `en`, never render the raw key or blank. Set the default/source locale as the fallback at config time.
+
+## Phase 2 — ICU MessageFormat correctly
+
+ICU MessageFormat is the cross-library standard for plurals and `select`, powered by CLDR plural categories. Use it for **plurals and gender only** — keep date/number formatting out (next section).
+
+**CLDR defines up to six plural categories. English uses two; you cannot assume singular/plural is enough.**
+
+| Category | Example languages |
+| --- | --- |
+| `one`, `other` | English, German, Spanish |
+| `one`, `few`, `many`, `other` | Russian, Polish, Czech |
+| `zero`, `one`, `two`, `few`, `many`, `other` | Arabic (all six) |
+| `other` only | Chinese, Japanese, Korean |
+
+```tsx
+// Bad — correct only for English-like 2-form languages
+const label = count === 1 ? "item" : "items";
+
+// Good — ICU resolves the right CLDR category per locale
+// "cart.items": "{count, plural, one {# item} other {# items}}"
+// Russian catalog supplies one/few/many/other; the call site never changes.
+```
+
+**Every `plural`, `selectordinal`, and `select` block REQUIRES an `other` clause** — it is the mandatory fallback; without it the message is invalid and the formatter throws.
+
+```icu
+{gender, select, female {She replied} male {He replied} other {They replied}}
+{place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}} place
+```
+
+**Wrap the formatter in try/catch and fall back to the key.** A malformed ICU string from a translator throws at runtime — returning the key keeps the UI alive while you log the error.
+
+```ts
+function format(key: string, args?: Record<string, unknown>) {
+  try {
+    return formatter.format(messages[key], args);
+  } catch (err) {
+    console.error(`ICU format failed for "${key}"`, err);
+    return key; // visible, non-crashing fallback
+  }
+}
+```
+
+See `references/icu-cookbook.md` for nested plural+select, escaping `'` and `{`, and per-language plural-category tables.
+
+## Locale-aware formatting
+
+Dates, numbers, and currency belong to `Intl.*`, **not** inside ICU messages and never string-concatenated. These read CLDR data, so `de-DE` renders `1.000,50` while `en-US` renders `1,000.50` — for free.
+
+```ts
+new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(1000.5);
+// "1.000,50 €"
+
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(new Date());
+// "2026年6月2日"
+
+new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-1, "day");
+// "ayer"
+
+new Intl.ListFormat("en", { type: "conjunction" }).format(["a", "b", "c"]);
+// "a, b, and c"
+
+new Intl.PluralRules("ar").select(3); // "few"  — drives non-ICU plural logic
+```
+
+Rule: if you typed a `/`, `,`, `.`, `$`, or `%` into a translated string, you have a bug. Format with `Intl`.
+
+## Phase 3 — locale routing & rendering
+
+For Next.js App Router with `next-intl`, route locale through a `[locale]` segment. Defer all non-locale framework detail to `../nextjs/SKILL.md`.
+
+```ts
+// routing.ts
+import { defineRouting } from "next-intl/routing";
+
+export const routing = defineRouting({
+  locales: ["en", "es", "ar"],
+  defaultLocale: "en",
+  localePrefix: "as-needed", // 'always' | 'as-needed' | 'never'
+});
+```
+
+`localePrefix`: `always` (`/en/...`, `/es/...`), `as-needed` (default locale unprefixed), or `never` (locale via cookie/header only). Pick based on your SEO needs — defer the ranking call to `../seo-geo/SKILL.md`.
+
+**Add `generateStaticParams` on the `[locale]` segment** so each locale renders statically. Set `lang` *and* `dir` on `<html>` — `dir` is what flips the layout.
+
+```tsx
+export function generateStaticParams() {
+  return routing.locales.map((locale) => ({ locale }));
+}
+
+export default function RootLayout({ children, params: { locale } }) {
+  const dir = locale === "ar" || locale === "he" ? "rtl" : "ltr";
+  return <html lang={locale} dir={dir}>{children}</html>;
+}
+```
+
+## RTL & bidi
+
+**Set direction with the HTML `dir` attribute on the root, not the CSS `direction` property.** `dir` carries semantic meaning the browser and assistive tech use for bidi; CSS `direction` does not. Then write layout with **CSS logical properties** so one stylesheet serves both directions.
+
+| Physical (don't) | Logical (do) |
+| --- | --- |
+| `margin-left` | `margin-inline-start` |
+| `padding-right` | `padding-inline-end` |
+| `text-align: left` | `text-align: start` |
+| `left: 0` | `inset-inline-start: 0` |
+| `border-right` | `border-inline-end` |
+
+These auto-flip with `dir`/`writing-mode`, so RTL needs no separate stylesheet. **Isolate interpolated user content** (names, IDs) with `<bdi>` or `unicode-bidi: isolate` so a Hebrew username doesn't scramble surrounding LTR text.
+
+See `references/rtl-and-bidi.md` for the full mapping, which icons to mirror vs. not, and RTL testing.
+
+## Phase 4 — translation workflow
+
+The 2025–2026 pipeline is MT/TM pre-fill → LLM post-edit (MTPE) → human review, governed by a glossary and translation memory.
+
+1. **Freeze the source.** Translating moving copy doubles the work. Lock strings, then hand off.
+2. **Build a glossary/termbase.** Locks product terms ("Workspace", "Boost") to one approved translation per language — keeps terminology consistent and measurably cuts post-edit effort.
+3. **Stand up translation memory (TM).** Reuses approved translations for repeat/near-repeat segments across the product, so you never re-translate or re-pay for the same string.
+4. **MT pre-fill, then LLM post-edit, then human review.** MT/LLM gives a strong first pass; humans review for nuance. Upstream quality (clear source + glossary + style + TM) is what makes the post-edit cheap.
+5. **Preserve placeholders/variables.** `{count}`, `%s`, `<b>…</b>` must survive untouched — validate after every MT/LLM pass.
+
+**Never auto-translate unreviewed:** legal/contract copy (route to `../brand-voice/SKILL.md` and legal review for terms), and brand-voice-critical strings — those need the voice carried deliberately, not machine-flattened.
+
+## Testing
+
+- [ ] **Pseudolocalization first.** Transform source strings: accent the letters, pad +30–40% length, wrap in brackets — e.g. `[Ŝéttîñgś……]`. Surfaces hardcoded strings, truncation/overflow from text expansion, and broken concatenation **before** you hire a single translator.
+- [ ] **Missing-key detection.** Fail CI when a locale lacks a key the source has.
+- [ ] **Longest-language overflow check.** German/Finnish expand most; verify buttons and fixed-width UI survive.
+- [ ] **Per-locale snapshot/visual diff**, including one RTL locale.
+- [ ] **Fallback locale resolves**, never the raw key.
+
+## Anti-patterns
+
+| Anti-pattern | Why it breaks | Do instead |
+| --- | --- | --- |
+| Concatenating translated fragments | Word order differs per language | One ICU message with named args |
+| `count === 1 ? x : y` | Wrong for ~most languages (Russian, Arabic…) | ICU `plural` with CLDR categories |
+| Date/number formats baked into strings | `1,000.50` is wrong in de-DE | `Intl.NumberFormat`/`DateTimeFormat` |
+| `margin-left` everywhere | Doesn't flip for RTL | CSS logical properties |
+| Translating in raw spreadsheets, no TM | Drift, repeat work, lost terms | TM + glossary + a TMS |
+| Machine-translating legal/brand copy unreviewed | Liability + flattened voice | Human/legal + `brand-voice` |
+| No fallback locale | Missing key renders blank/raw | Configure source locale fallback |
+| Using English text as the message key | Copy edit breaks all translations | Stable namespaced key |
+| Missing `other` clause in ICU | Invalid message, formatter throws | Always include `other` |
+| ICU formatting with no try/catch | One bad translation crashes the view | Catch → return key, log |
+| Setting direction via CSS, not HTML `dir` | Loses bidi semantics | `dir` attribute on `<html>` |
+| Assuming all languages expand equally | DE/FI overflow, ZH contracts | Pseudoloc + longest-language test |
+
+## Handoff checklist
+
+**i18n-ready:** no hardcoded user-facing strings · catalog with stable namespaced keys · fallback locale set · all plurals via ICU · all dates/numbers via `Intl` · CSS logical properties · `lang`+`dir` on `<html>` · pseudoloc passes.
+
+**l10n-ready:** glossary/termbase signed off · TM populated · MT→LLM→human pipeline defined · legal/brand strings flagged for human review · per-locale CI checks (missing keys, overflow, RTL snapshot) green.

package/skills/translation-l10n/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — translation-l10n
+
+These cases are run by the rsc skill eval harness. `should_trigger` and `should_not_trigger` check routing precision: that locale/translation requests (including non-obvious symptom phrasings and a Spanish prompt) select this skill, while voice (brand-voice), framework wiring (nextjs), ranking strategy (seo-geo), and copy authoring (content-engine) route to the correct sibling instead. The single `capability` case is a rubric, not an executable test — a reviewer (human or model) reads the SKILL.md guidance against an "add Arabic to a React product" scenario and confirms each `must_include` point is covered (i18n-first sequencing, ICU plurals with CLDR `other`, no concatenation, `Intl.*` formatting, RTL via `dir` + logical properties, the glossary/TM/post-edit workflow, pseudoloc + missing-key testing, fallback locale). There is no code to execute — this is a process/knowledge skill, so its rigor lives in the capability rubric rather than a verify.sh.

package/skills/translation-l10n/evals/cases.yaml

@@ -0,0 +1,39 @@
+skill: translation-l10n
+
+should_trigger:
+  - prompt: "We need to ship the app in French and Arabic."
+    why: Core add-a-language request spanning i18n plumbing and RTL — the central use case.
+  - prompt: "Our plural messages are wrong in Russian and Polish — it always shows the singular form."
+    why: ICU/CLDR plural categories; non-obvious symptom that points straight at the count===1 anti-pattern.
+  - prompt: "The German text overflows our buttons and dates still show American format for Spanish users."
+    why: Text-expansion overflow plus Intl date formatting — two localization symptoms phrased as bugs, not as 'i18n'.
+  - prompt: "Set up locale routing with next-intl and generateStaticParams for our App Router."
+    why: Phase 3 locale routing/rendering plumbing — the framework on-ramp this skill owns.
+  - prompt: "Traducir la app al árabe y montar el glosario para los traductores."
+    why: Spanish trigger covering the translation workflow, glossary/termbase, and an RTL language.
+
+should_not_trigger:
+  - prompt: "Define our brand's tone of voice and word bank for our copy."
+    route_to: brand-voice
+    why: Inventing voice in one language; this skill moves an existing voice across languages, it does not author it.
+  - prompt: "How do I fetch data in a Next.js App Router server component?"
+    route_to: nextjs
+    why: General framework wiring unrelated to locale; this skill only touches routing where locale-specific.
+  - prompt: "Plan our hreflang and per-country keyword strategy to rank in Germany."
+    route_to: seo-geo
+    why: Multilingual ranking/geo strategy, not translation or i18n plumbing.
+  - prompt: "Write the English landing page copy for our launch."
+    route_to: content-engine
+    why: Authoring net-new source copy; localization translates existing content, it does not write it.
+
+capability:
+  - scenario: "Add Arabic to our existing React product so it ships correctly."
+    must_include:
+      - i18n-before-l10n sequencing (make the code locale-ready before producing translations)
+      - externalize strings to a catalog with stable namespaced keys; no concatenation of fragments
+      - ICU plural with correct CLDR categories including the mandatory `other` clause (Arabic uses all six)
+      - dates/numbers/currency via `Intl.*`, never baked into strings
+      - RTL via `dir` on `<html>` and CSS logical properties (not CSS `direction`, not `margin-left`)
+      - translation workflow with glossary + translation memory + MT/LLM post-edit + human review
+      - pseudolocalization and missing-key testing before hiring translators
+      - configured fallback locale

package/skills/translation-l10n/references/icu-cookbook.md

@@ -0,0 +1,82 @@
+# ICU MessageFormat cookbook
+
+Lookup recipes for the patterns that don't fit inline in SKILL.md. ICU is for plurals and `select` only — format dates/numbers with `Intl.*`, not inside the message.
+
+## Full-sentence pattern (named args)
+
+Never assemble a sentence from fragments. Put the whole sentence in one message and let the translator reorder freely.
+
+```icu
+{name} shared {count, plural, one {# photo} other {# photos}} with you
+```
+
+The translator owns the entire string, so Japanese or Arabic word order is theirs to set — your call site stays `t("share.summary", { name, count })`.
+
+## Nested plural + select
+
+Combine gender/category selection with pluralization. Each block still needs its own `other`.
+
+```icu
+{gender, select,
+  female {{count, plural, one {She has # follower} other {She has # followers}}}
+  male   {{count, plural, one {He has # follower}  other {He has # followers}}}
+  other  {{count, plural, one {They have # follower} other {They have # followers}}}
+}
+```
+
+## selectordinal — 1st / 2nd / 3rd
+
+`plural` is for cardinals (1 item); `selectordinal` is for ordinals (1st place). English needs `one`/`two`/`few`/`other`; other languages differ.
+
+```icu
+You finished {place, selectordinal,
+  one {#st}
+  two {#nd}
+  few {#rd}
+  other {#th}
+}
+```
+
+## The `#` token
+
+Inside a `plural`/`selectordinal` block, `#` prints the formatted number for the current locale. Outside such a block it is a literal `#`. Don't reuse the count variable name where `#` already does the job.
+
+## Escaping literals
+
+ICU treats `{`, `}`, and `'` as syntax. To print them literally, wrap in single quotes; a doubled `''` prints one apostrophe.
+
+```icu
+This is a literal '{brace}' and an apostrophe '' here.
+```
+
+- `'{brace}'` → renders the text `{brace}` unparsed.
+- `''` → renders `'`.
+- A lone `'` that doesn't open a quoted span is treated as literal in most ICU implementations, but quote it explicitly to be safe.
+
+## Per-language plural categories (quick table)
+
+CLDR rules, summarized. Catalogs for these languages must supply exactly these categories.
+
+| Language | Categories used |
+| --- | --- |
+| English (en), German (de), Spanish (es) | `one`, `other` |
+| French (fr) | `one`, `many`, `other` |
+| Russian (ru) | `one`, `few`, `many`, `other` |
+| Polish (pl) | `one`, `few`, `many`, `other` |
+| Arabic (ar) | `zero`, `one`, `two`, `few`, `many`, `other` |
+| Chinese (zh), Japanese (ja), Korean (ko) | `other` only |
+
+A category your language doesn't use is simply ignored; a category it *does* use but you omitted falls through to `other` — often wrong (e.g. Russian "2 файла" needs `few`, not `other`).
+
+## Skeletons (number/date inside ICU)
+
+ICU supports number/date "skeletons" (`{price, number, ::currency/EUR}`), but prefer formatting outside the message with `Intl` so the format stays in code, reviewable and testable, rather than scattered across translator-edited catalogs. Reserve skeletons for cases where the number is grammatically fused into the sentence.
+
+## Validation before ship
+
+Parse every catalog with your ICU library at build time and assert:
+- every `plural`/`selectordinal`/`select` has an `other` clause,
+- all placeholders present in the source key exist in each translation,
+- no unbalanced `{`/`}`.
+
+A failing parse should break CI, not surface at runtime.

package/skills/translation-l10n/references/rtl-and-bidi.md

@@ -0,0 +1,60 @@
+# RTL & bidi reference
+
+Full depth for right-to-left (Arabic, Hebrew, Persian, Urdu) and bidirectional text. The core rule lives in SKILL.md: set `dir` on `<html>`, write layout with CSS logical properties. This file is the complete mapping plus the judgment calls.
+
+## Physical → logical property mapping
+
+Replace physical properties so one stylesheet flips automatically with `dir`/`writing-mode`.
+
+| Physical | Logical |
+| --- | --- |
+| `margin-left` / `margin-right` | `margin-inline-start` / `margin-inline-end` |
+| `padding-left` / `padding-right` | `padding-inline-start` / `padding-inline-end` |
+| `left` / `right` | `inset-inline-start` / `inset-inline-end` |
+| `border-left` / `border-right` | `border-inline-start` / `border-inline-end` |
+| `text-align: left` / `right` | `text-align: start` / `end` |
+| `border-top-left-radius` | `border-start-start-radius` |
+| `width` / `height` | `inline-size` / `block-size` |
+| `float: left` | `float: inline-start` |
+
+Flexbox/grid: `flex-start`/`flex-end` and `start`/`end` already follow direction — prefer them over `left`/`right`. Use `justify-content: flex-start`, not absolute positioning, where possible.
+
+## Bidi isolation for interpolated content
+
+User-supplied or locale-foreign text embedded in a sentence can reorder surrounding characters (the "bidi spillover" bug: a Hebrew name pushes an LTR punctuation mark to the wrong side).
+
+- HTML: wrap the interpolated value in `<bdi>` — it isolates the embedded run's direction.
+- CSS: `unicode-bidi: isolate` on the wrapper achieves the same.
+- `dir="auto"` on an input/element lets the browser infer direction from the first strong character — useful for user-generated content fields whose language you don't know.
+
+```html
+<span>@<bdi>{{username}}</bdi> mentioned you</span>
+```
+
+## Mirror vs. don't mirror
+
+When `dir="rtl"`, layout flips — but not every graphic should.
+
+**Mirror** (directional meaning): back/forward arrows, breadcrumb chevrons, progress that advances, list bullets/indentation, send/reply arrows, undo/redo.
+
+**Do NOT mirror** (physical/absolute meaning): media play button (always points to time-forward, conventionally right), clocks, musical notation, checkmarks, logos and brand marks, photos, phone/email/numbers that read LTR even in RTL context, charts with a real x-axis.
+
+Implement icon mirroring with a logical transform scoped to RTL:
+
+```css
+[dir="rtl"] .icon-directional { transform: scaleX(-1); }
+```
+
+Keep a single explicit class for mirrored icons rather than flipping all of them.
+
+## Numbers, dates, and embedded LTR
+
+Numbers and Latin product names stay LTR even inside RTL text — the bidi algorithm handles this if you don't fight it. Don't force `direction` on number spans; let `Intl.NumberFormat` with the locale render digits (Arabic-Indic vs. Western) and let bidi place them.
+
+## Testing RTL
+
+1. **Pseudo-RTL locale.** Add a fake locale that forces `dir="rtl"` plus pseudolocalized strings to smoke-test layout flip without real translations.
+2. **Snapshot one real RTL locale** (ar) in visual regression.
+3. **Tab order + focus**: verify keyboard navigation follows visual order after the flip.
+4. **Check truncation/ellipsis**: `text-overflow` and gradient fades must sit on the logical end, not a hardcoded right edge.
+5. **Mixed content**: render an LTR username/number inside an RTL sentence and confirm no spillover.

package/skills/typescript/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: typescript
+description: "Use when writing or fixing TypeScript type code (.ts/.tsx/.d.ts), modeling data with generics/unions/branded types, diagnosing narrowing failures, or configuring tsconfig and the build toolchain. NOT runtime code, fs/streams/http (that is `nodejs`); NOT component/route typing (that is `react`/`nextjs`); NOT ORM type-gen (that is `drizzle-orm`)."
+tags: [typescript, types, generics, tsconfig, type-safety]
+recommends: [nodejs, secure-coding, drizzle-orm]
+origin: risco
+---
+
+# Idiomatic TypeScript types
+
+Express data and contracts precisely in the TypeScript type system, and configure the
+compiler so the types actually hold.
+
+Targets **TypeScript 5.9** (current stable, Q1 2026): redesigned `tsc --init` defaults
+(`module: nodenext`, `target: esnext`, `moduleDetection: force`, strict on), `import defer`
+for deferred module evaluation, expandable editor hovers. The **TypeScript 7 native
+compiler** (`tsgo`, the Go port) is in preview as `@typescript/native-preview` and
+type-checks roughly 10x faster (VS Code's 1.5M LOC: 89s -> 8.74s) — adopt it for fast
+local checks; stable 7.0 lands early 2026.
+
+## Boundary: language vs runtime vs framework
+
+Three layers, three owners. **Language + compiler config lives here** — generics, narrowing,
+`.d.ts`, `tsconfig`, and the build toolchain (`tsc` vs `tsgo`, `tsx`, resolution mode).
+**Runtime behavior** (how a stream backpressures, how the event loop schedules) is `nodejs`.
+**Framework idioms** (component props, route maps, server-component typing) are
+`react`/`nextjs`/`nestjs` — those *borrow* this skill's type mechanics but own their wiring.
+A `tsconfig` question is here; a "stream backpressure" question is `nodejs`; a "type my
+`useReducer` state" question is `react`. Also delegate: ORM schema-to-type generation ->
+`drizzle-orm` / `prisma-orm`; REST/contract shape design -> `api-design`; test runner and E2E
+setup -> `testing-web` / `e2e-testing`; injection/authz review -> `secure-coding`; Python
+typing -> `python`; Go -> `go`.
+
+## Decision rules
+
+Apply these on every TypeScript edit:
+
+1. **Prefer inference; annotate boundaries.** Let TS infer locals and returns; annotate
+   function parameters, public APIs, and `.d.ts`. Why: redundant annotations drift from
+   reality and suppress the better inferred type.
+2. **`import type` for type-only imports**, with `verbatimModuleSyntax: true`. Why: it
+   prevents emitting type-only imports as runtime `require`s and lets esbuild/swc transpile
+   each file alone.
+3. **Narrow, don't cast.** Reach for type guards, `in`, `typeof`, discriminant checks before
+   `as`; when `as` is unavoidable, only `as <narrower>` or `as unknown as T` at a true I/O
+   boundary. Why: `as` asserts a claim the compiler cannot verify — it is a silenced error,
+   and `as` to a *wider* or unrelated type is almost always a real bug hidden.
+
+## The type-system toolbox
+
+### Generics + constraints, and `const` type parameters
+
+Constrain type parameters so callers get errors at the call site, and use a `const` type
+parameter (TS 5.0+) to preserve literal inference without `as const` everywhere:
+
+```ts
+// Bad: unconstrained T, and the literal "a"|"b" widens to string.
+function pick<T>(obj: T, key: string) { return (obj as any)[key]; }
+
+// Good: K is constrained to obj's keys; const T keeps the literal union.
+function pick<const T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+const r = pick({ a: 1, b: "x" } as const, "b"); // r: "x", not string
+```
+
+### `unknown` over `any` at every boundary
+
+`any` disables checking and silently poisons every downstream type it touches; `unknown`
+forces a narrow before use.
+
+```ts
+// Bad: any flows everywhere, no error ever fires downstream.
+function parse(json: string): any { return JSON.parse(json); }
+
+// Good: unknown forces a narrow before the value is trusted.
+function parse(json: string): unknown { return JSON.parse(json); }
+const data = parse(input);
+if (typeof data === "object" && data && "id" in data) { /* now narrowed */ }
+```
+
+### `satisfies` for config validation without widening
+
+```ts
+type Route = { path: string; method: "GET" | "POST" };
+
+// Bad: annotation widens — routes.home.method is "GET" | "POST", and a typo in
+// a key would only surface far away.
+const a: Record<string, Route> = { home: { path: "/", method: "GET" } };
+
+// Good: satisfies validates each entry AND keeps literal types.
+const routes = {
+  home: { path: "/", method: "GET" },
+} satisfies Record<string, Route>;
+routes.home.method; // "GET" (narrow), and "GE" would error right here
+```
+
+### Discriminated unions + exhaustive `never`
+
+Model state as a discriminated union, not an optional-field bag:
+`{ data?: T; error?: E; loading?: boolean }` permits `loading && error`; a literal discriminant
+makes illegal states unrepresentable. That discriminant must be a **literal** type (not
+`string`), and you must check it **before** destructuring — destructuring first throws away
+the narrowing.
+
+```ts
+type State =
+  | { status: "loading" }
+  | { status: "ok"; data: string }
+  | { status: "error"; message: string };
+
+// Bad: destructured before the check — `data`/`message` are typed as the union.
+function render({ status, data, message }: State) { /* no narrowing */ }
+
+// Good: switch on the literal discriminant, exhaustive never guard at the end.
+function render(s: State): string {
+  switch (s.status) {
+    case "loading": return "...";
+    case "ok": return s.data;
+    case "error": return s.message;
+    default: { const _exhaustive: never = s; return _exhaustive; }
+  }
+}
+```
+
+Add a `"deleted"` member to `State` and the `default` branch fails to compile — that is the
+point.
+
+### Branded (nominal) types
+
+TS is structural, so a `UserId` and a raw `string` are interchangeable unless you brand them:
+
+```ts
+type UserId = string & { readonly __brand: "UserId" };
+const asUserId = (s: string): UserId => s as UserId; // brand only at the validated boundary
+function load(id: UserId) { /* a bare string is now a compile error */ }
+```
+
+### Utility types cheat row
+
+`Partial<T>` `Required<T>` `Readonly<T>` `Pick<T,K>` `Omit<T,K>` `Record<K,V>`
+`Exclude<U,M>` `Extract<U,M>` `NonNullable<T>` `ReturnType<F>` `Parameters<F>`
+`Awaited<T>` `NoInfer<T>` (TS 5.4+, blocks a type param from inferring at one site).
+
+### Mapped / conditional / template-literal one-liners
+
+```ts
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };          // strip readonly
+type Nullable<T> = { [K in keyof T]: T[K] | null };            // mapped transform
+type Unwrap<T> = T extends Promise<infer U> ? U : T;           // conditional + infer
+type EventName<T extends string> = `on${Capitalize<T>}`;       // template literal
+```
+
+Deep recipes (recursive types, declaration merging, variance/`in`-`out`, assertion functions,
+overloads) live in [references/type-system.md](references/type-system.md).
+
+## tsconfig: strict base
+
+Copy-paste base. Every package `extends` this and overrides only paths/references:
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,                    // the whole strict family, non-negotiable
+    "noUncheckedIndexedAccess": true,  // arr[i] / rec[k] are T | undefined
+    "verbatimModuleSyntax": true,      // explicit import type; safe single-file transpile
+    "isolatedModules": true,           // each file transpilable alone (esbuild/swc/babel)
+    "skipLibCheck": true,              // don't type-check node_modules .d.ts (speed)
+    "resolveJsonModule": true,         // import data.json with types
+    "target": "esnext",
+    "module": "nodenext",              // or "esnext" + "moduleResolution": "bundler"
+    "moduleResolution": "nodenext",
+    "moduleDetection": "force",
+    "noEmit": true                     // a bundler/tsc -b emits; the base just checks
+  }
+}
+```
+
+### moduleResolution: bundler vs nodenext
+
+| Aspect | `bundler` | `nodenext` |
+| --- | --- | --- |
+| Use when | Vite / Next / Remix / esbuild build the code | Code runs directly in Node (no bundler) |
+| Relative import extensions | omit (`./util`) | required (`./util.js`) |
+| `package.json` `exports`/`imports` | resolved | resolved |
+| `module` setting | `esnext`/`preserve` | `nodenext` |
+| Emits runnable JS itself | no (the bundler does) | yes |
+
+Pick `bundler` when a bundler owns resolution; pick `nodenext` for libraries and scripts
+that Node executes directly. Field-by-field reference and the full matrix are in
+[references/build-and-monorepo.md](references/build-and-monorepo.md).
+
+## Monorepo & build
+
+Use **project references** so packages type-check independently and in dependency order. A
+shared `tsconfig.base.json` holds the strict flags; each package extends it, sets
+`composite: true`, `outDir`/`rootDir`, and lists upstream packages under `references`. Build
+the graph with `tsc -b` (or `tsgo -b`).
+
+For declaration emit and publishing a library, set `declaration: true`,
+`declarationMap: true`, and an `exports` map in `package.json`. For fast local checks prefer
+`tsgo` (TS7 preview: `npx @typescript/native-preview`); run scripts with `tsx` instead of
+`ts-node`. Depth, build-order graph, path aliases, and the `tsgo` adoption steps are in
+[references/build-and-monorepo.md](references/build-and-monorepo.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `any` as an escape hatch | disables all checking and spreads silently downstream | `unknown` + narrow, or a precise type / generic |
+| `as` to silence "not assignable" | asserts a claim TS can't verify — hides the real bug | fix the type, or narrow with a guard/`in`/`typeof` |
+| `enum` for a small fixed set | emits runtime code, awkward with `isolatedModules`, no literal subtyping | union of string literals (`"a" \| "b"`) + `as const` |
+| Destructure before the discriminant check | narrowing is lost; fields become the full union | check `obj.kind` first, then read fields |
+| Skipping `noUncheckedIndexedAccess` | `arr[i]`/`rec[k]` typed as `T` but are `undefined` at runtime | enable it; handle the `\| undefined` |
+| `Function` / bare `object` / `{}` types | accept almost anything, no call-signature safety | a precise signature, or `Record<string, unknown>` |
+| No exhaustive `never` guard on unions | a new union member compiles with a missing branch | `default: const _: never = x` in every switch |
+| One giant `tsconfig` for a monorepo | can't express per-package targets; breaks references | `tsconfig.base.json` + per-package `extends` |
+| `// @ts-ignore` | swallows the error even after the line is fixed, masking new ones | `// @ts-expect-error` (errors if the line later type-checks) |
+| Default-importing in a CJS-emit file under `verbatimModuleSyntax` | blocked / wrong emit | use `export =`/named, or set the right `module` |
+
+## Project grounding
+
+When working inside a real workspace, record this project's tsconfig and strictness choices
+(resolution mode, which strict flags are on, the build tool) in the project wiki via
+[../harness/SKILL.md](../harness/SKILL.md) — so the next session does not re-derive them.

package/skills/typescript/evals/README.md

@@ -0,0 +1,15 @@
+# Evals: typescript
+
+`cases.yaml` checks two things. **Routing**: `should_trigger` lists prompts (including
+non-obvious narrowing symptoms and Spanish/Catalan phrasings) that must select this skill, and
+`should_not_trigger` lists adjacent prompts that must route to a named sibling (`nodejs`,
+`react`, `drizzle-orm`, `python`, `testing-web`) instead. **Capability**: the scenario gives a
+loosely-typed module with no tsconfig and grades the output against the `must_include` rubric
+(any -> precise types, discriminated union with a literal discriminant, exhaustive `never`
+guard, a strict tsconfig, `import type` usage, no error-silencing casts).
+
+To run, feed each prompt to the skill router and confirm the trigger/route decision, then run
+the capability scenario through an agent loaded with this skill and score the result by hand
+against the rubric. There is no automated runner here; the rigor is the rubric plus
+`scripts/verify.sh`, which independently proves the toolchain enforces strictness and
+exhaustiveness on a sample project.