rsc-universal 0.1.1

package/skills/together-fireworks/references/batch-and-tuning.md

@@ -0,0 +1,59 @@
+# Batch, dedicated & fine-tuning — Together / Fireworks
+
+Facts dated 2026-06-02. Re-check the provider batch docs before relying on limits.
+
+## Together native Batch API (NOT the OpenAI Batch endpoint)
+
+Together's OpenAI-compat layer does **not** expose `/v1/batches`. Pointing the OpenAI Batch client at Together fails. Use Together's **native** Batch API.
+
+**Limits:** default **24h** completion window, up to **50,000 requests/file**, up to **50% off** serverless pricing, **separate rate-limit pool** from real-time.
+
+**JSONL request file** — one request per line:
+
+```jsonl
+{"custom_id": "req-1", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Label as spam or ham: ..."}]}}
+{"custom_id": "req-2", "body": {"model": "openai/gpt-oss-20b", "messages": [{"role": "user", "content": "Label as spam or ham: ..."}]}}
+```
+
+**Flow** (use the `together` SDK or REST):
+
+```python
+from together import Together
+
+client = Together()  # reads TOGETHER_API_KEY from env
+
+up = client.files.upload(file="requests.jsonl", purpose="batch-api")
+job = client.batches.create_batch(file_id=up.id, endpoint="/v1/chat/completions")
+
+# poll until terminal
+status = client.batches.get_batch(job.id)   # PENDING -> IN_PROGRESS -> COMPLETED / FAILED
+
+# on COMPLETED, download the output file id and parse one JSON result per line,
+# matched back to requests by custom_id.
+```
+
+Each output line carries the `custom_id` so you can join results back to inputs. Handle `FAILED`/partial lines — a row erroring does not fail the whole job.
+
+## Fireworks batch (a serving path, not a separate API)
+
+Fireworks **Serverless 2.0** exposes Standard / Priority / **Batch** through the same API. Batch = **50%** of serverless price on input and output. You select the batch path per request/config rather than uploading a separate JSONL job. Priority (≈1.5×) works with both OpenAI- and Anthropic-compatible endpoints.
+
+## When batch pays off
+
+- No human waiting on the response (eval runs, synthetic-data generation, bulk classification/extraction, backfills).
+- More than ~1k requests — the 50% cut clears any added orchestration overhead.
+- You can tolerate the completion window (Together default 24h).
+
+Do **not** batch a user-facing request — the latency window makes it unusable in real time.
+
+## Dedicated deployments
+
+Both providers offer reserved-GPU / dedicated endpoints billed by GPU-hour (not per token). It only beats serverless above a **high, sustained** QPS or when you need a **fixed latency SLA** or a model not on the serverless menu. Below that load, an idle dedicated GPU burns money a token endpoint never would. If you are leaning dedicated mostly to control infra, that is the self-host tradeoff — compare against renting raw GPUs (`../runpod/SKILL.md`, `../modal/SKILL.md`).
+
+## Fine-tuning (Together)
+
+Tiered per 1M training tokens (together.ai/pricing, 2026-06-02): up to 16B SFT **$0.48** / Full $1.20–$1.35; 17B–69B SFT **$1.50**; 70B–100B SFT **$2.90** / Full $7.25–$8.00 — the published size tiers **stop at 70B–100B; there is no 405B tier**. Beyond that the catalog prices by named specialized model, not size (DeepSeek-R1 SFT $10.00 / DPO $25.00; Llama 4 Maverick SFT $8.00 / DPO $20.00). Serve the result on a dedicated deployment. Re-check the pricing page — these tiers shift.
+
+## Sources (accessed 2026-06-02)
+- https://docs.together.ai/docs/inference/batch/overview · https://www.together.ai/blog/batch-api
+- https://fireworks.ai/blog/serverless-2 · https://docs.fireworks.ai/serverless/pricing

package/skills/together-fireworks/references/models-and-pricing.md

@@ -0,0 +1,79 @@
+# Models & pricing — Together AI / Fireworks AI
+
+Every figure here is **per 1M tokens, USD**, and was read directly off the provider's own pricing/model page on **2026-06-02**. No number on this page is sourced to a third-party tracker — aggregators are addressed (and excluded) in the last section. Prices move and ids get retired; **re-read the primary page before quoting a customer**:
+- Together pricing (authoritative $/1M): https://www.together.ai/pricing — read 2026-06-02
+- Together serverless model catalog (authoritative id list): https://docs.together.ai/docs/serverless-models — read 2026-06-02
+- Fireworks serverless pricing (authoritative $/1M + id): https://docs.fireworks.ai/serverless/pricing — read 2026-06-02
+
+Rule of thumb for grounding: every $/1M figure and every model id below traces to one of the three pages above, as read on the date stated. If you cannot find a model on the provider's own catalog, treat the id as unverified and do not quote it — a tracker listing is not a confirmation.
+
+## Together AI
+
+Base URL `https://api.together.ai/v1`. Model id shape `<vendor>/<model>`. Confirm the exact id string and rate on docs.together.ai/docs/serverless-models and together.ai/pricing before quoting — casing and suffixes (`-Turbo`, `-Lite`) are load-bearing.
+
+Each row's `V` column is the verifiability of the **id + price** as read off together.ai/pricing on 2026-06-02:
+- **stable** — long-lived id, low price churn; safe to quote after a glance at the page.
+- **projected** — current-generation flagship whose id/price moves fast (and whose id you may not recognize from training data); the number is the page's figure on this date, but treat it as a moving target and re-read the page before any quote.
+
+| Model | Model id | Input $/1M | Output $/1M | V | Notes |
+|---|---|---|---|---|---|
+| GPT-OSS 20B | `openai/gpt-oss-20b` | 0.05 | 0.20 | stable | cheapest; classify/extract |
+| GPT-OSS 120B | `openai/gpt-oss-120b` | 0.15 | 0.60 | stable | bigger open GPT-OSS |
+| Llama 3 8B Instruct Lite | `meta-llama/Meta-Llama-3-8B-Instruct-Lite` | 0.14 | 0.14 | stable | small & fast, 8K ctx |
+| Llama 3.3 70B | `meta-llama/Llama-3.3-70B-Instruct-Turbo` | 1.04 | 1.04 | stable | general chat |
+| Qwen 3.6 Plus | `Qwen/Qwen3.6-Plus` | 0.50 | 3.00 | projected | high output cost — watch it; ~1M ctx |
+| DeepSeek V4-Pro | `deepseek-ai/DeepSeek-V4-Pro` | 2.10 | 4.40 | projected | top reasoning; $0.20 cached input; 512K serverless ctx (1M on dedicated) |
+
+Not on Together serverless as of this date (do **not** quote these ids against Together): `deepseek-ai/DeepSeek-V3.1`, `meta-llama/Llama-4-Maverick-*`. They appear on aggregators but are absent from the provider's own serverless catalog — confirm at docs.together.ai/docs/serverless-models.
+
+**Embeddings:** `intfloat/multilingual-e5-large-instruct` — $0.02 / 1M input tokens (together.ai/pricing). Confirm the exact id/price on the pricing page before quoting.
+
+**Fine-tuning** (together.ai/pricing, per 1M training tokens): up to 16B — SFT $0.48 / DPO $0.54 / Full $1.20–$1.35; 17B–69B — SFT $1.50 / DPO $1.65 / Full $3.75–$4.12; 70B–100B — SFT $2.90 / DPO $3.20 / Full $7.25–$8.00. The standard size tiers stop at **70B–100B — there is no published 405B tier** as of this date; a >100B fine-tune runs as one of the specialized models, not a size tier. Specialized: DeepSeek-R1 SFT $10.00 / DPO $25.00 (min $20.00); Llama 4 Maverick SFT $8.00 / DPO $20.00 (min $16.00). Serve the result on a dedicated deployment.
+
+## Fireworks AI
+
+Base URL `https://api.fireworks.ai/inference/v1`. Model id shape `accounts/fireworks/models/<name>`.
+
+**Size-tiered base pricing** (docs.fireworks.ai/serverless/pricing; applies in and out, for any model without a named price):
+
+| Model size | $/1M (input and output) |
+|---|---|
+| < 4B | 0.10 |
+| 4B – 16B | 0.20 |
+| > 16B (dense) | 0.90 |
+| MoE ≤ 56B (e.g. Mixtral 8x7B) | 0.50 |
+| MoE 56.1B – 176B (e.g. DBRX, Mixtral 8x22B) | 1.20 |
+
+These are the provider's own published tiers, so they hold up as a sizing estimate in a quote. They are not a per-model promise — the named-model prices below override the tier where a model is explicitly listed.
+
+**Named models** (docs.fireworks.ai/serverless/pricing — input / cached input / output, Standard tier). `V` = verifiability of id+price as read on 2026-06-02 (same legend as the Together table: **stable** = long-lived; **projected** = fast-moving current flagship, re-read the page before quoting):
+
+| Model | Model id | Input | Cached | Output | V |
+|---|---|---|---|---|---|
+| GPT-OSS 20B | `accounts/fireworks/models/gpt-oss-20b` | 0.07 | 0.035 | 0.30 | stable |
+| GPT-OSS 120B | `accounts/fireworks/models/gpt-oss-120b` | 0.15 | 0.015 | 0.60 | stable |
+| Llama 3.1 8B Instruct | `accounts/fireworks/models/llama-v3p1-8b-instruct` | 4B–16B tier (0.20) | — | 4B–16B tier (0.20) | stable |
+| Kimi K2.6 | `accounts/fireworks/models/kimi-k2p6` | 0.95 | 0.16 | 4.00 | projected |
+| DeepSeek V4-Pro | `accounts/fireworks/models/deepseek-v4-pro` | 1.74 | 0.145 | 3.48 | projected |
+| DeepSeek V4 Flash | `accounts/fireworks/models/deepseek-v4-flash` | 0.14 | 0.028 | 0.28 | projected |
+
+Note `gpt-oss-20b` on Fireworks is $0.07/$0.30, slightly above Together's $0.05/$0.20 for the same weights — the kind of arbitrage the env-driven config in SKILL.md lets you exploit.
+
+**Embeddings:** input only — up to 150M params $0.008, 150M–350M $0.016, Qwen3 8B $0.10 / 1M input (docs.fireworks.ai/serverless/pricing).
+
+**Multipliers** (docs.fireworks.ai/serverless/pricing):
+- **Cached input** defaults to **50%** of input price on text/vision models (named models above publish a lower cached figure — use the published one when available).
+- **Priority serving** is opt-in and runs above Standard — the page lists priority per model (e.g. Kimi K2.6 priority input $1.50 vs $0.95 standard, ≈1.5–1.6×). Do not budget at priority rates unless you enable it.
+- **Batch = 50%** of serverless on both input and output.
+- **Serverless 2.0** routes Standard / Priority / Batch through one API; Priority works with OpenAI- and Anthropic-compatible endpoints.
+
+## Aggregators (use only for cross-provider sizing, never for a per-model quote)
+
+Third-party trackers (Artificial Analysis, aipricing.guru, lmmarketcap, costbench) are useful for a *blended* sense of where the catalog sits but routinely lag and mis-attribute per-model rates — e.g. they still list DeepSeek-V3.1 as a live Together serverless model. For any dollar figure you put in front of a customer, cite the provider page above, not an aggregator.
+
+## Sources (accessed 2026-06-02)
+- https://docs.together.ai/docs/serverless-models
+- https://www.together.ai/pricing
+- https://www.together.ai/blog/deepseek-v4-pro-now-available-on-together-ai
+- https://docs.fireworks.ai/serverless/pricing
+- https://docs.together.ai/docs/openai-api-compatibility

package/skills/together-fireworks/scripts/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static lint for Together AI / Fireworks AI inference snippets.
+#
+# WHAT IT DOES (read-only; never edits, never hits the network, no API key needed)
+#   Greps target .py/.ts/.js/.tsx/.jsx files that mention Together or Fireworks and
+#   flags the classic mistakes:
+#     1. A together/fireworks API key (or its base_url) paired with api.openai.com
+#        -> FAIL (the key only authenticates against its own host).
+#     2. A bare model name (no namespace) when a Together/Fireworks base_url is
+#        present -> FAIL. Together needs "<vendor>/<model>"; Fireworks needs
+#        "accounts/fireworks/models/<name>".
+#     3. A hardcoded API-key string literal (api_key="sk-..."/literal) where an
+#        env var belongs -> FAIL (committed key = leaked key).
+#     4. Wrong/legacy base_url for the provider in use -> WARN (verify the exact
+#        host: https://api.together.ai/v1 or https://api.fireworks.ai/inference/v1).
+#
+# EXIT CODES
+#   0  clean, or no relevant file to inspect (empty/clean target is NOT a failure)
+#   1  at least one [fail] finding
+#   2  bad usage
+#
+# HOW TO RUN (point it at YOUR code, not the skills repo)
+#   ./verify.sh app.py                 # lint one file
+#   ./verify.sh --path src/            # lint every .py/.ts/.js under a dir
+#   ./verify.sh                        # scan ./ ; if nothing matches, skip + exit 0
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    -*)        printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+    *)         SCAN_PATH="$1"; shift ;;
+  esac
+done
+[ -z "$SCAN_PATH" ] && SCAN_PATH="."
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+# --- collect candidate source files ----------------------------------------
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f \
+    \( -name '*.py' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \) \
+    2>/dev/null || true)"
+fi
+
+# Keep only files that actually reference these providers (so we never false-fail
+# on unrelated code).
+RELEVANT=""
+if [ -n "$FILES" ]; then
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if grep -iEq 'together\.ai|fireworks\.ai|TOGETHER_API_KEY|FIREWORKS_API_KEY|accounts/fireworks/models' "$f" 2>/dev/null; then
+      RELEVANT="$RELEVANT$f
+"
+    fi
+  done <<EOF
+$FILES
+EOF
+fi
+
+# Empty / clean target is NOT a failure.
+if [ -z "$RELEVANT" ]; then
+  skip "no Together/Fireworks inference code found under '$SCAN_PATH' — nothing to lint"
+  exit 0
+fi
+
+n_files="$(printf '%s' "$RELEVANT" | grep -c . || true)"
+printf 'Linting %s Together/Fireworks file(s) under: %s\n\n' "$n_files" "$SCAN_PATH"
+
+fail_total=0
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  printf '%s— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  uses_together=0; uses_fireworks=0
+  grep -iEq 'together\.ai|TOGETHER_API_KEY' "$f" 2>/dev/null && uses_together=1
+  grep -iEq 'fireworks\.ai|FIREWORKS_API_KEY|accounts/fireworks/models' "$f" 2>/dev/null && uses_fireworks=1
+
+  # 1. provider key/url paired with the OpenAI host -> FAIL
+  if grep -iEq 'api\.openai\.com' "$f" 2>/dev/null; then
+    hits="$(grep -inE 'api\.openai\.com' "$f" 2>/dev/null || true)"
+    fail "  api.openai.com used in a Together/Fireworks file — a provider key only works on its own host:"
+    printf '%s\n' "$hits" | head -n 5 | sed 's/^/        /'
+    fail_total=$((fail_total + 1))
+  else
+    ok "  no api.openai.com host mixed in"
+  fi
+
+  # 4. base_url present and correct -> WARN if a provider is used but its exact URL is absent
+  if [ "$uses_together" -eq 1 ]; then
+    if grep -Eq 'https://api\.together\.ai/v1' "$f" 2>/dev/null; then
+      ok "  Together base_url present and correct"
+    elif grep -iEq 'base_?url|baseURL' "$f" 2>/dev/null; then
+      warn "  Together used but exact base_url not found — expect https://api.together.ai/v1"
+    fi
+  fi
+  if [ "$uses_fireworks" -eq 1 ]; then
+    if grep -Eq 'https://api\.fireworks\.ai/inference/v1' "$f" 2>/dev/null; then
+      ok "  Fireworks base_url present and correct"
+    elif grep -iEq 'base_?url|baseURL' "$f" 2>/dev/null; then
+      warn "  Fireworks used but exact base_url not found — expect https://api.fireworks.ai/inference/v1"
+    fi
+  fi
+
+  # 2. bare model name (no namespace slash) -> FAIL
+  #    Capture model="..."/model: "..." values; a valid id contains a '/'.
+  bare="$(grep -inE 'model[[:space:]]*[:=][[:space:]]*["'\''][^"'\'']+["'\'']' "$f" 2>/dev/null \
+            | grep -vE 'model[[:space:]]*[:=][[:space:]]*["'\''][^"'\'']*/' \
+            | grep -viE 'os\.environ|process\.env|getenv|LLM_MODEL' || true)"
+  if [ -n "$bare" ]; then
+    fail "  bare model id (missing namespace '/') — Together needs <vendor>/<model>, Fireworks needs accounts/fireworks/models/<name>:"
+    printf '%s\n' "$bare" | head -n 5 | sed 's/^/        /'
+    fail_total=$((fail_total + 1))
+  else
+    ok "  model ids are namespaced (or env-driven)"
+  fi
+
+  # 3. hardcoded API key literal -> FAIL
+  hard="$(grep -inE 'api_?key[[:space:]]*[:=][[:space:]]*["'\''](sk-|fw_|[A-Za-z0-9]{16,})' "$f" 2>/dev/null \
+            | grep -viE 'os\.environ|process\.env|getenv|(^|[[:space:]])//|(^|[[:space:]])#' || true)"
+  if [ -n "$hard" ]; then
+    fail "  hardcoded API key literal — read it from an env var instead:"
+    printf '%s\n' "$hard" | head -n 5 | sed 's/^/        /'
+    fail_total=$((fail_total + 1))
+  else
+    ok "  API key is read from an env var"
+  fi
+
+  printf '\n'
+done <<EOF
+$RELEVANT
+EOF
+
+cat <<'NOTE'
+Note: [fail] = a routing/security bug that breaks the call or leaks a secret (fix it).
+      [warn] = the exact base_url string wasn't found (confirm the host is right).
+NOTE
+
+if [ "$fail_total" -gt 0 ]; then exit 1; fi
+exit 0

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/app product, wiring i18n plumbing (extract strings, ICU messages, locale routing), fixing broken plurals or dates, or making a UI survive other languages (RTL, text expansion). Triggers: 'ship the app in French and Arabic', 'set up next-intl routing with generateStaticParams', 'our Russian plurals always show the singular', 'German text overflows the buttons', 'dates still show American format for Spanish users', 'the Arabic layout is mirrored wrong', 'traducir la app al árabe y montar el glosario', 'necessito localitzar el producte'. 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