@daanvandenbergh/i18nkit 1.0.0

package/skills/i18nkit-sweep/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: i18nkit-sweep
+description: Full-project sweep that hunts down every user-facing string NOT wrapped in i18nkit's type-safe system (LanguageText / defineTextCatalog / a translator from useTranslator or i18n.translator) - so adding a locale stays a compile-checked guarantee instead of a manual hope. A team of parallel agents reads every UI file, reports each bare literal with file:line and category, and (only with --fix) wraps the confident ones through a co-located defineTextCatalog and verifies typecheck stays green. When the project uses @daanvandenbergh/blogkit it also verifies every post's per-slug folder has a body for every configured locale, and that each post's hero.js covers every locale so each language renders its own hero. Use this whenever the user wants to audit, enforce, or fix i18n / translation coverage, find or fix hardcoded / untranslated / non-translatable strings, make "all text support i18n" or "use LanguageText everywhere", verify nothing bypasses the translation system, get the codebase ready before adding a language, or asks "are all our strings translatable?" - even if they don't name the i18n module. It closes the gap for text that ALREADY exists; do NOT use it for translating supplied strings into another language, adding or configuring a locale in the I18n instance, or changing the default locale. Takes an optional area (e.g. components, "app/(dashboard)") to scope the sweep, or omit for all of src/. Report-only by default; pass --fix to also wrap the confident violations.
+user-invokable: true
+argument-hint: "[area] [--fix]   e.g. components  |  \"app/(dashboard)\" --fix  |  (omit = report all of src/)"
+---
+
+# i18nkit-sweep
+
+Hunt every piece of user-facing text in the project's source that reaches the UI as a **bare
+string** instead of going through an i18nkit translator. This is a **negative-space** search:
+correct code resolves copy through a `LanguageText`/`LanguageTextCatalog` built with
+`i18n.defineTextCatalog`; a violation is the *absence* of that - a literal that silently escapes the
+compile-time coverage guarantee. i18nkit's guarantee is structural: the locale set is a union `L`
+inferred from `new I18n({ locales })`, `LanguageText<L>` is a mapped type over `L`, so adding a
+locale turns every un-translated entry into a compile error - but a bare literal has no per-locale
+keys, so nothing forces it to keep up. Grep alone can't judge intent, so the sweep is a **team of
+agents that read the actual files** against a precise ruleset. Thoroughness comes from covering
+every file; correctness comes from judgment, not pattern-matching.
+
+The bar is **exhaustive coverage with high precision**. A short, correct list beats a long, noisy
+one - every reported violation must be a real one a staff engineer would agree with.
+
+## Inputs
+
+Everything after `/i18nkit-sweep` is one raw string. Parse in prose:
+1. Extract `--fix` if present, then strip it. Its presence means **also fix**: after reporting, wrap
+   the confident violations and re-verify typecheck (Phase 3.4). **Default (no `--fix`):
+   report-only** - sweep and report, change no files.
+2. The remainder is the **area** to scope to (a path under the source root, e.g. `components` or
+   `app/(dashboard)`). Empty -> sweep **all of `src/`** (or the project's user-facing source root).
+
+## The authority
+
+`reference/rules.md` (in this skill's own directory) is the adjudicator: exactly what counts as
+user-facing text, the full exception list (dev-only `throw`s, JSON-LD data fields, endonyms, brand
+name, non-copy attributes, mask glyphs...), the gray-zone calls, and the finding format. **Read it
+now.** Let `<skill-dir>` be this skill's own directory (the folder containing this SKILL.md);
+resolve it to an absolute path and pass `<skill-dir>/reference/rules.md` to every sweep agent - it
+is what keeps precision high. (The skill is a drop-in: it carries its own rules and script, so
+nothing here hardcodes a machine path.)
+
+## Phase 0 - Learn the locale set
+
+Locate the consumer's `I18n` instance: `new I18n({ locales: {...}, default: "..." })` (conventionally
+`app/i18n.ts`, often re-exported as `export const i18n` with `type Locale = keyof typeof i18n.locales`).
+Read it to learn:
+- the **supported locales** = the keys of `locales` (e.g. `en`, `nl`), and
+- the **default locale** = the `default` field.
+
+That set is what "if we shipped one more locale tomorrow" means concretely, and it is the locale
+axis both the string sweep and the blogkit-parity step (Phase 3.5) enumerate. Endonyms live in
+`locales[x].label` and are **not** copy (see rules.md).
+
+## Phase 1 - Scope and shard
+
+1. **Resolve the file set.** All `.ts`/`.tsx` under the target area, **excluding** `tests/`,
+   `*.test.*`, `*.test-d.*`, `*.d.ts`. Priority (Next.js App Router + React first; degrade
+   gracefully for other setups):
+   - **HIGH** (where copy lives): route files under `app/` - pages, `layout`, `error`,
+     `not-found`, and `generateMetadata` returns - and everything under `components/`.
+   - **IN SCOPE - server-generated user-facing copy**: email modules (transactional subjects /
+     headings / bodies) and product/catalog modules (titles/descriptions shown at checkout). Real
+     users see these, so bare copy there is a violation (`backend-copy`; see rules.md item 6). The
+     rest of server code is machine/dev strings (throws, logs, index names) = not copy.
+   - **EXEMPT**: the blog area when `@daanvandenbergh/blogkit` is used (article bodies and
+     front-matter-derived text are content, localized file-per-language; parity is checked
+     separately in Phase 3.5); and placeholder/demo `_data.ts`-style data (stand-in content, treated
+     like DB data).
+   - **SKIP**: the file that constructs the `I18n` instance (it *is* the config; its locale labels
+     and default are the exceptions), and i18nkit's own package files.
+   - **Non-Next / non-React project?** Drop the `app/`-specific names and treat it generically: sweep
+     all user-facing source under the area (default `src/`), same rules.
+2. **Get a heat-map.** Run the bundled lead-finder over the area:
+   ```bash
+   <skill-dir>/scripts/find_candidates.sh "<area or src>"
+   ```
+   It prints **SUSPECT FILES** (render JSX but touch no seam/translator - read these first) and
+   **LITERAL LEADS** (bare copy attributes, same-line JSX text, toast/error, metadata/JSON-LD).
+   Leads are starting points, **not verdicts** - every file still gets read in full.
+3. **Shard.** Split the file set into groups of ~8-12 files along directory boundaries so each agent
+   has coherent context. Aim for one agent per coherent sub-area. Keep concurrent agents to ~10-12;
+   run more in a second batch.
+
+## Phase 2 - Parallel sweep (the team)
+
+Spawn one `general-purpose` agent per shard, **all in one message** so they run concurrently. Give
+each this task (fill in the shard's files and the resolved rules path):
+
+> You are one of several agents sweeping this project's source for i18nkit violations - user-facing
+> text that reaches the UI as a bare string instead of resolving through an i18nkit translator
+> (`useTranslator()` in React, or `i18n.translator(locale)` / `i18n.translate(text, locale)` in the
+> core). **First read `<skill-dir>/reference/rules.md`** - it is the exact definition of a violation,
+> the full exception list, and the finding format. It is easy to over-report; follow it precisely.
+> The project's configured locales are `<list them>` (default `<default>`).
+>
+> Your files: `<list the shard's paths>`.
+>
+> For **every** file: read it **in full** (do not rely on grep excerpts - multi-line JSX text and
+> metadata objects hide from grep). Judge each string against the one question in the rules: *"if we
+> shipped one more locale tomorrow, would this exact string have to change?"* Flag every bare
+> user-facing literal; ignore every exception (dev-only `throw`s, per-locale `defineTextCatalog`
+> values, data/URLs/enums/ids, endonyms, brand name, mask glyphs, decorative `alt=""`, non-copy
+> attributes). Pay special attention to any file that renders copy but imports no `useTranslator` /
+> `i18n.translator` / `defineTextCatalog` and never calls a translator.
+>
+> Return findings in the exact block format from rules.md (file, line, snippet, category, why, fix,
+> confidence). For every file with no violations, emit `<path>: clean` so coverage is provable. **Do
+> not spawn sub-agents. Do not modify files.** Return only the findings + the clean list.
+
+## Phase 3 - Verify, then report
+
+1. **Collect** every agent's findings and clean-list. Confirm each shard's files were all accounted
+   for (found-or-clean) - if an agent skipped files, re-dispatch them. No file goes unread.
+2. **Verify the doubtful.** Re-check every `medium`/`low` confidence finding yourself by reading that
+   spot (or dispatch a single skeptical verifier agent for a batch): does it truly change under a new
+   locale, or is it an exception? Drop the false positives. A wrong finding is worse than a missing
+   one here.
+3. **Report.** Print, in the conversation:
+   - A one-line verdict: `N violations across M files (K files swept, area = ...)`.
+   - Violations grouped **by file**, each as the rules.md block, ordered high->low confidence.
+   - A short **counts-by-category** tally (jsx-text / attribute / toast-or-error / metadata /
+     json-ld / backend-copy).
+   - A **coverage line**: which areas were swept and which were intentionally skipped (so the user
+     knows nothing was silently dropped), plus the blogkit-parity result from 3.5.
+   Offer to save the report to `claude/reports/i18nkit-sweep.md` if the list is long.
+4. **Fix (only under `--fix`; skip this whole step by default).** Apply the fixes per rules.md ("How
+   a fix is applied") - extend the file's `defineTextCatalog`, wire a translator via the right seam,
+   replace the literal. Touch only the violating lines; do not restructure files. Guards:
+   - **Only auto-fix `high`-confidence findings, and only when wrapping yields a green entry.** A
+     bare literal is the *default*-locale text; a catalog entry needs **every** configured locale to
+     compile, and you must never invent the others. So: single-locale project -> wrap (lossless);
+     multi-locale with the other translations genuinely known -> fill all and wrap; otherwise list
+     the finding as **needs-translation** and leave it unchanged. Say clearly what you applied vs.
+     left, and list every `medium`/`low` finding as **needs-your-call**.
+   - **`backend-copy` is not a mechanical wrap** - it needs a locale source threaded in (no
+     request-scoped locale in a job/webhook). Do **not** auto-edit backend files; report them with
+     the design note from rules.md item 6 and let the user decide the seam.
+   After editing, run `npm run typecheck` (fallback `npx tsc --noEmit`) and report it green. If it
+   fails, fix the wrap or revert that one finding - never leave the tree non-compiling.
+5. **blogkit translation parity (always, even without `--fix`).** This is the one place a new locale
+   is **not** compile-checked, so verify it directly - mostly a file check, no agent.
+   1. **Detect blogkit.** The project uses it if any of: `@daanvandenbergh/blogkit` appears in the
+      consumer's `package.json` (`dependencies`/`devDependencies`), a source file imports it, or a
+      `new Blog({...})` instance exists. If **none** hold, **skip this whole step** and say so in the
+      coverage line ("blogkit not detected - blog parity skipped").
+   2. **If present, read the `Blog` config** for `contentDir` (a required field, conventionally
+      `./blog`), the `locales[].code` list, `defaultLocale`, and `extension` (the post file
+      extension, default `.mdx`). Cross-check that locale set against the `I18n` locales from Phase 0;
+      if they diverge, report the divergence as its own finding. Each post is a **folder**
+      `<contentDir>/<slug>/` holding one `<locale>.mdx` body per language - the default is
+      `<slug>/<defaultLocale>.mdx` (e.g. `en.mdx`; a neutral `<slug>/post.mdx` is the fallback name),
+      each translation `<slug>/<code>.mdx` (same folder), plus one `<slug>/hero.js`. blogkit has **no
+      silent fallback**, so a missing file is a real gap.
+   3. **Post parity - a pure file check.** Set `CONTENT_DIR` and `DEF` (the default locale) from the
+      config, replace `.mdx` with the configured `extension` if it is non-default, and **inline the
+      non-default locale codes as a literal list** (write `for l in nl de` - do **not** rely on an
+      unquoted `$langs` variable, which does not word-split under zsh):
+      ```bash
+      CONTENT_DIR="./blog"; DEF="en"       # from the Blog config (contentDir, defaultLocale)
+      # find (not a bare glob) so an empty or non-post folder never aborts the loop under zsh's nomatch
+      find "$CONTENT_DIR" -mindepth 1 -maxdepth 1 -type d | while read -r dir; do
+          # a post needs a default-locale body: <default>.mdx, or the neutral post.mdx fallback
+          if [ ! -f "$dir/$DEF.mdx" ] && [ ! -f "$dir/post.mdx" ]; then
+              # no base body: any <locale>.mdx here is an orphan translation (base renamed/deleted)
+              find "$dir" -maxdepth 1 -name '*.mdx' -exec echo "ORPHAN: {}" \;
+              continue
+          fi
+          for l in nl de; do               # <- the non-default locale codes, inline
+              [ -f "$dir/$l.mdx" ] || echo "MISSING: $dir/$l.mdx"
+          done
+      done
+      ```
+   4. **Hero parity.** The hero is one `<slug>/hero.js` per post, `export default (locale) => ({
+      gradient, ...text[locale] })`, whose `text` map holds each language's `title`/`subtitle`; it is
+      rendered once per locale to `public/assets/blog/<slug>/hero.<code>.jpg`, and each body's
+      `image:` front-matter points at its **own** locale's JPEG (a hero bakes in that language's text,
+      so a shared JPEG is untranslated copy). Two checks:
+      - **Primary - `hero.js` locale coverage (robust, no path guessing).** For each post that has a
+        `hero.js` in the `(locale) => params` form, read its `text` map and confirm it has a key for
+        **every** configured locale. A configured locale missing from the map -> **hero locale gap**
+        (that language renders a blank/wrong hero). This is the signal blogkit's `hero_image.md`
+        defers to the sweep to catch project-wide. (A single-language plain-object `hero.js` on a
+        now-multi-locale blog is itself a `hero locale gap` - it needs converting to the map form.)
+      - **Secondary - rendered hero + `image:` reference (heuristic path).** By the Next.js
+        convention the JPEGs live at `public/assets/blog/<slug>/hero.<code>.jpg` (say the base dir is
+        a heuristic if the project serves static assets elsewhere). For each configured locale whose
+        body exists, flag a **broken hero reference** if its `hero.<code>.jpg` is missing, if the
+        body's `image:` path has no file under `public/`, or if the `image:` points at **another**
+        locale's JPEG (e.g. `<slug>/fr.mdx` -> `hero.en.jpg`). Check the base body too.
+   5. **Report** each `MISSING:`, hero locale gap, broken hero reference, and orphan as a
+      **blogkit-parity gap** in the coverage section - a content-parity gap, not a translator
+      violation, and **never auto-fixed** here (writing/translating a post body, or generating a
+      localized hero, is the blog author's job - point to blogkit's own `skills/blogkit` write and
+      `hero_image.md` skills).
+
+## Notes
+
+- **Why a team, not one pass:** a real UI has many text-bearing files; one agent reading all of them
+  loses focus and misses things. Sharded parallel reads keep each agent sharp and finish fast.
+- **Portability:** the default fan-out uses the `Agent` tool. For a very large or repeated whole-repo
+  sweep the same shape maps onto a `Workflow` (finder -> per-shard sweep -> verify), but Agent
+  parallelism is enough for most repos.
+- **Universal drop-in:** this skill makes no repo-specific assumptions - it resolves the locale set
+  from the project's own `I18n` config, reads its own bundled rules/script by relative path, and
+  degrades from Next/React-specific guidance to a generic `src/` sweep when the project is neither.
+- **Re-runnable:** scope to an area you just edited (`/i18nkit-sweep app/(dashboard)/billing`) for a
+  fast focused check, or run bare before adding a locale for the full guarantee.

package/skills/i18nkit-sweep/reference/rules.md

@@ -0,0 +1,174 @@
+# i18nkit-sweep rules - what is a violation, what is not
+
+This is the adjudicator for the sweep. A **violation** is any *user-facing text* in the project's
+source that reaches the UI as a bare string instead of being resolved through an i18nkit
+translator. The whole point of the system: the locale set is a union `L` (inferred from the keys of
+`new I18n({ locales })`) and `LanguageText<L>` is a **mapped type over `L`**, so adding a locale
+turns every un-translated entry into a compile error. A bare literal silently escapes that
+guarantee - so it is a bug, always. There is no linter for this by design; this sweep is the
+enforcement.
+
+## The one question that decides every case
+
+> **If the project shipped one more locale tomorrow, would this exact string have to change?**
+
+- **Yes** -> it is user-facing copy and MUST be a `LanguageText<L>` / `LanguageTextFn<L, A>` resolved
+  via a translator. If it is a bare literal, it is a **violation**.
+- **No** (it is a name, URL, enum value, CSS class, id, dev-only error, log line, or other
+  machine/data string) -> not copy, **not a violation**. Do not flag it.
+
+When genuinely unsure, keep the finding but mark `confidence: low` and say why - the aggregation
+pass re-checks those. Precision matters: a flood of false positives is worse than a short, correct
+list.
+
+## How correct code looks (so you recognize the absence of it)
+
+- Copy lives in a co-located catalog built with the project's `I18n` instance:
+  `export const TX = i18n.defineTextCatalog({ title: { en: "Customers", nl: "Klanten" } });`
+  (import `i18n` from the consumer's config module, e.g. `import { i18n } from "@/i18n"`). Every
+  configured locale must be present or it does not compile. Parameterized entries are functions per
+  locale: `{ en: (n: string) => \`${n} deleted\`, nl: (n: string) => \`${n} verwijderd\` }`.
+- **Core / server** (framework-agnostic): resolve the active locale yourself - from a cookie or the
+  `Accept-Language` header via `i18n.resolveLocale(...)` / `i18n.matchAcceptLanguage(...)` - then
+  bind a translator: `const translate = i18n.translator(locale);` and call `translate(TX.title)`.
+  A one-off resolve without binding is `i18n.translate(TX.title, locale)`. There is **no**
+  dedicated server helper; the locale is the caller's to resolve.
+- **React**: `const translate = useTranslator();` (from `@daanvandenbergh/i18nkit/react`) returns a
+  translator already bound to the active locale from context (`I18nProvider`).
+- In JSX: `{translate(TX.title)}`, `placeholder={translate(TX.ph)}`, `aria-label={translate(TX.close)}`,
+  `toast(translate(TX.saved))`, `setError(translate(TX.required))`. Interpolation:
+  `translate(TX.subtitle, orgName)`.
+- A word that is deliberately identical in every locale (a brand token) is authored with
+  `i18n.uniform("...")` - a real `LanguageText<L>`, not a bare literal.
+- Note any `.js` suffix on i18nkit / internal imports (NodeNext ESM) - it is correct, not a build
+  artifact. Never flag an import specifier.
+
+**A UI file that renders copy but imports no seam (`useTranslator` / `i18n.translator` /
+`defineTextCatalog`) and never calls a translator is the #1 place bare copy hides.** Read those
+first (the finder's "SUSPECT FILES").
+
+## MUST be `LanguageText` (flag if bare) - the full list
+
+1. **JSX text children** - headings, paragraphs, button/link labels, list items, empty states,
+   badges, any words rendered between tags: `<h1>Customers</h1>`, `>Save changes<`.
+2. **User-facing attribute values**: `aria-label`, `alt` (non-empty, non-decorative), `placeholder`,
+   `title`. These are read aloud by screen readers or shown on hover - they are copy.
+3. **Toasts, validation messages, and any error string shown to a user**: `toast("Saved")`,
+   `setError("Name is required")`, an error message returned from a **server action** or an **API
+   route** that the UI renders.
+4. **Page SEO metadata**: `title`, `description`, and OpenGraph/Twitter fields, whether in a static
+   `export const metadata` or a `generateMetadata()` return.
+5. **Human-readable strings in JSON-LD** (`application/ld+json`): `name`, `description`, `headline`,
+   `serviceType`, FAQ question/answer text, etc.
+6. **Backend/server-generated copy that reaches a user** - transactional **email** subjects,
+   headings and body text, and **product/catalog** titles/descriptions shown at checkout. i18nkit's
+   type layer (`@daanvandenbergh/i18nkit`) is dependency-free and importable anywhere, so this copy
+   is in scope. Flag it as `category: backend-copy`. In the `fix`, note that a backend job/webhook
+   has **no request-scoped locale** (no cookie/headers), so wrapping also needs a **language source**
+   - the recipient's / org's locale passed in; say so.
+
+## NOT `LanguageText` (never flag) - the exceptions
+
+- **The per-locale values inside a `defineTextCatalog` entry** (`en: "..."`, `nl: (n) => ...`).
+  Those literals *are* the translations - the correct end state, not a violation. (The finder
+  pre-filters locale-code-keyed lines; never re-flag them.)
+- **Anything already resolved**: `{translate(TX.x)}`, `translate(TX.x, arg)`,
+  `i18n.translate(TX.x, locale)`, `i18n.uniform("...")`, or a variable holding an already-resolved
+  string (e.g. a server action returns `{ ok:false, error }` where `error` was already built with a
+  translator; the JSX that renders `result.error` is **correct**, not bare).
+- **User / DB / content data**: a customer's real name, address, phone, invoice number, transcript.
+  Also placeholder/demo/sample data (`_data.ts`-style stand-in content, sample names): it is
+  stand-in content, not product copy, so it is exempt like real DB data.
+- **The entire blog area when the project uses `@daanvandenbergh/blogkit`**: MDX article bodies
+  **and their front-matter-derived fields** (title, excerpt, author, tags) are content, localized
+  **file-per-language in a per-slug folder** by blogkit - each post is a folder `<contentDir>/<slug>/`
+  whose default body `<slug>/<defaultLocale>.mdx` gets a same-slug translation beside it (e.g.
+  `blog/<slug>/nl.mdx`), never wrapped in a translator. The post's `<slug>/hero.js` is likewise
+  **content/data, not a translator seam**: its per-locale `text` map (`en`/`nl` `title`/`subtitle`) is
+  hero copy localized file-style, so **do not flag its string literals as bare copy**. Do not flag
+  literals that are article content or come from a post's front-matter or `hero.js`. (The blog's own
+  page-shell chrome - a hardcoded nav label or empty state in a route/component - would still be copy,
+  but the blog area is content-dominated; treat it as the low-yield exception.) Translation
+  *completeness* - a missing locale body, or a locale absent from a `hero.js` `text` map - is not a
+  translator concern and is checked separately by the sweep's blogkit-parity step, not flagged here.
+- **The brand / product name** rendered as text (e.g. the wordmark) - a proper noun, not translated.
+  If it must be a `LanguageText<L>` for a seam, the sanctioned form is `i18n.uniform("Brand")`.
+- **Language endonyms** - a locale's own name, i.e. the `label` on each entry in the `I18n`
+  `locales` config, and any language-name chips (a language's own name is never translated).
+- **Non-copy attributes**: `className`, `href`, `src`, `role`, `id`, `name`, `type`, `key`, `value`
+  (of `<option>`/inputs), `htmlFor`, `rel`, `target`, `autoComplete`, `data-*`, `viewBox`, and
+  **technical ARIA** (`aria-hidden`, `aria-expanded`, `aria-controls`, `aria-current`). `alt=""`
+  (decorative image) is correct - leave it.
+- **Developer-only strings never rendered to an end user**: `throw new Error("...")` in server/lib
+  code that only gets logged or is mapped to a `LanguageText` at the action layer (e.g.
+  `"Authentication required"` -> caught and re-messaged), React hook invariants
+  (`throw new Error("useX must be used within <ProviderX>")`), assertions, and every `log.*(...)` /
+  `console.*(...)` message. (Distinguish these from backend copy that a user *does* see - emails,
+  product catalog - which IS in scope, item 6 above.)
+- **Machine/config strings**: database index `name:` options, collection names, enum discriminants,
+  lookup keys, ids, URLs, currency/tax codes - data, not copy.
+- **Non-linguistic tokens**: pure punctuation/symbol separators (`·`, `/`, `→`, `•`), the em-dash
+  fallback `"-"`, mask glyphs (`placeholder="••••••••"`), lone numbers, currency symbols, single
+  characters.
+- **JSON-LD data fields**: `streetAddress`, `addressCountry`/`addressLocality`, `postalCode`,
+  `email`, `telephone`, `url`, ids, `availableLanguage: ["en","nl"]`, price/currency codes - these
+  are data, not copy. Only the human-readable fields (above) are.
+
+## Gray-zone judgment calls
+
+- **`throw new Error("...")`**: violation *only if* the thrown message can reach the UI. Backend
+  throws (mapped to `LanguageText` at the action layer, or only logged) and hook/dev invariants are
+  **not** violations. A `throw` inside a **client** component whose message is shown in a toast/error
+  UI **is**. When you can't tell, `confidence: low`.
+- **`<option value="lead">Lead</option>`**: the `value` attribute stays bare (it's a machine key);
+  the child text `Lead` is copy and must be `{translate(TX.statusLead)}`.
+- **Rich text** (a sentence with an inline `<b>`/`<span>`/`<a>`): correct form is several
+  `LanguageText` fragments composed in JSX (`{translate(TX.a)}<b>{translate(TX.b)}</b>{translate(TX.c)}`).
+  That is **not** the forbidden concatenation. The forbidden thing is a resolved string glued to a
+  **raw literal** (`translate(TX.a) + " more text"`) or JSX text sitting next to a `{translate(...)}`.
+- **`aria-label` with a value that is data, not copy** (e.g. `aria-label={customer.name}`): not a
+  violation - it's data. `aria-label="Close"` (a literal) is.
+- **Proper-noun-adjacent tokens** - product **tier names** (`"Brand Starter/Pro/Scale"`), **place
+  names** in JSON-LD (`areaServed name: "Europe"`), and similar: these sit between brand/data and
+  copy. Lean toward treating them as brand/data (usually shipped untranslated); if you do flag them,
+  use `confidence: medium` with a one-line note - never `high`. Don't let them pad the list.
+- **Test files, `.d.ts`, `.stories.*`, `.test-d.*`**: not user-facing; skip them.
+
+## Finding format (return exactly this per violation)
+
+```
+- file: src/app/customers/CustomerList.tsx
+  line: 42
+  snippet: <h2>Recent activity</h2>
+  category: jsx-text            # jsx-text | attribute | toast-or-error | metadata | json-ld | backend-copy
+  why: bare JSX heading rendered to the user; must resolve via translate(TX.*)
+  fix: add `recentActivity: { en: "Recent activity", nl: "..." }` to the file's TX catalog and render `{translate(TX.recentActivity)}`
+  confidence: high              # high | medium | low
+```
+
+Group nothing, sort nothing - just emit one block per violation. If a file is clean, say so
+(`<path>: clean`) so the orchestrator knows it was actually read, not skipped.
+
+## How a fix is applied (only under `--fix`; the default run is report-only)
+
+1. Find or create the file's co-located `export const TX = i18n.defineTextCatalog({ ... });`
+   (import `i18n` from the consumer's config module).
+2. Add an entry. Static -> `{ en: "...", nl: "..." }`. Interpolated ->
+   `{ en: (x) => \`...${x}...\`, nl: (x) => \`...${x}...\` }`. Convert HTML entities to the literal
+   Unicode char (`&middot;` -> `·`, `&rsquo;` -> `'`).
+3. Ensure the call site has a translator: `const translate = i18n.translator(locale);` (core/server,
+   with the locale resolved by the caller) or `const translate = useTranslator();` (React, from
+   `@daanvandenbergh/i18nkit/react`).
+4. Replace the literal with `{translate(TX.key)}` (or `translate(TX.key, arg)` for interpolation, or
+   the attribute form `attr={translate(TX.key)}`).
+5. **Locale-safe wrapping (critical):** a bare source literal is (only) the **default**-locale text.
+   A `defineTextCatalog` entry must cover **every** configured locale or it will not compile - and
+   you must **never invent** the other locales' translations (a fake `nl` value silently ships wrong
+   copy and defeats the whole guarantee). So:
+   - If the project has a **single** configured locale, wrapping is lossless: apply it.
+   - If **multi-locale** and the other translations are genuinely known, fill them all and apply.
+   - Otherwise **do not auto-wrap**: list the finding as `needs-translation` (default-locale value
+     ready, other locales awaiting a human) and leave the literal unchanged.
+6. Never create per-language source-file copies; never hardcode one locale's value at a call site; a
+   `LanguageText` value is always a plain string, never JSX.
+7. After any applied wrap, `npm run typecheck` (fallback `npx tsc --noEmit`) must stay green.

package/skills/i18nkit-sweep/scripts/find_candidates.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+#
+# find_candidates.sh - lead generator for the i18nkit-sweep.
+#
+# This is a HEAT-MAP, not a verdict. Every line it prints is a *candidate* that a
+# sweep agent must confirm by reading the surrounding file against reference/rules.md.
+# It errs toward over-reporting (grep can't see intent); the agent's judgment - not this
+# script - decides what is a real violation. It exists so every run and every agent
+# starts from the same lead list instead of re-inventing the greps.
+#
+# It is framework-agnostic: it greps for the shape of bare copy, not for any one project's
+# layout. Point it at any user-facing source root.
+#
+# Usage:  scripts/find_candidates.sh [path]      (default: src)
+#
+# Two sections:
+#   1. SUSPECT FILES  - .tsx that render JSX but never reach an i18nkit translate seam
+#                       (useTranslator / i18n.translator / defineTextCatalog / translate):
+#                       a file rendering copy with no visible path to i18n.
+#   2. LITERAL LEADS  - specific bare-literal lines (copy attributes, same-line JSX text,
+#                       toast/error strings), with obvious non-copy pre-filtered out.
+
+set -euo pipefail
+ROOT="${1:-src}"
+
+# Two backends, one interface. Prefer ripgrep; fall back to POSIX grep when it is absent (rg is
+# not always on PATH - e.g. when it is a shell alias the script's own shell never sees). The
+# helpers take only (pattern[, root]) - no tool-specific flags leak to the call sites, so SECTION 1
+# works identically under either backend. TSX_FILES lists matching *.tsx paths; SEARCH prints
+# matching lines with file:line. tests / *.d.ts / *.test.* are always excluded.
+if command -v rg >/dev/null 2>&1; then
+    # Positive globs FIRST (ripgrep is last-match-wins), then the exclusions - same .ts/.tsx
+    # universe the grep fallback restricts to, so the lead list does not depend on which backend
+    # is installed. Without the includes, rg would also scan .css/.js/.json/.md and diverge.
+    SEARCH()    { rg -n --no-heading -g '*.ts' -g '*.tsx' -g '!**/tests/**' -g '!**/*.d.ts' -g '!**/*.test.*' "$@"; }
+    # Positive glob FIRST, exclusions after: ripgrep is last-match-wins, so `-g '*.tsx'` must
+    # precede the negatives or it would re-include test/.d.ts files they excluded.
+    TSX_FILES() { rg -l -g '*.tsx' -g '!**/tests/**' -g '!**/*.d.ts' -g '!**/*.test.*' -e "$1" "$2"; }
+else
+    # POSIX grep fallback (BSD/GNU). Coarser exclusions. SECTION 1's patterns avoid \s / \b so both
+    # backends yield the identical suspect list; the 2a-2d lead patterns keep \b (best-effort here).
+    SEARCH()    { grep -rnE --include='*.tsx' --include='*.ts' "$@" | grep -vE '/tests/|\.d\.ts|\.test\.'; }
+    TSX_FILES() { grep -rlE --include='*.tsx' -e "$1" "$2" | grep -vE '/tests/|\.d\.ts|\.test\.'; }
+fi
+
+# Drop noise common to every pass: catalog interiors (a `defineTextCatalog` entry's per-locale
+# values ARE the copy, e.g. `en: "..."` / `nl: (n) => ...`), comment lines, and import specifiers.
+# The locale-code-key filter is best-effort - a BCP-47-ish key (`en`, `nl`, `pt-BR`) followed by a
+# colon is almost always a catalog translation value, not a bare literal. Over-dropping a rare lead
+# is fine: agents read every file in full regardless.
+DENOISE() { grep -vE '^[[:space:]]*[a-z]{2,3}(-[A-Za-z]{2,4})?[[:space:]]*:|^[[:space:]]*//|^[[:space:]]*\*|^[[:space:]]*/\*|import .* from'; }
+
+echo "############################################################"
+echo "# i18nkit-sweep candidate leads for: $ROOT"
+echo "# These are LEADS ONLY - confirm each by reading the file."
+echo "############################################################"
+
+echo
+echo "== SECTION 1: SUSPECT FILES (render JSX, no translate seam) =="
+echo "   A UI file that never reaches useTranslator/i18n.translator/translate(...) is where bare copy hides."
+# Candidate render files: .tsx that contain JSX return. Then subtract any that touch a seam.
+# POSIX ERE (no \s / \b) so the pattern is identical under ripgrep and grep.
+comm -23 \
+    <(TSX_FILES 'return[[:space:]]*\(|=>[[:space:]]*\(|<[A-Za-z]' "$ROOT" 2>/dev/null | sort -u) \
+    <(TSX_FILES 'useTranslator|\.translator\(|defineTextCatalog|defineText|translate\(|LanguageText' "$ROOT" 2>/dev/null | sort -u) \
+    || true
+
+echo
+echo "== SECTION 2a: COPY ATTRIBUTES with a bare string value =="
+echo "   placeholder / title / alt / aria-label = \"...words...\" -> should be {translate(TX.x)}"
+SEARCH -e '\b(placeholder|title|alt|aria-label)=["'\''`][^"'\''`]*[A-Za-z]{2,}' "$ROOT" 2>/dev/null \
+    | grep -vE 'alt=""' | DENOISE || true
+
+echo
+echo "== SECTION 2b: SAME-LINE JSX TEXT between tags =="
+echo "   >Some words< on one line -> should be >{translate(TX.x)}<  (multi-line text: read the file)"
+# Exclude ():;= inside the span: those are TS-generic / signature noise (Promise<void>,
+# Readonly<{...}>), never short JSX copy. Sentences with . , ' ! ? still match.
+SEARCH -e '>[^<>{}():;=]*[A-Za-z]{3,}[^<>{}():;=]*<' "$ROOT" 2>/dev/null \
+    | grep -vE '=>|https?:|import ' | DENOISE || true
+
+echo
+echo "== SECTION 2c: TOAST / ERROR / setError string literals =="
+echo "   toast(\"...\") / setError(\"...\") / new Error(\"...\") shown to a user -> translate(TX.x)"
+echo "   (backend throws & dev-invariant Errors are NOT violations - see rules.md)"
+SEARCH -e '\b(toast|setError|setMessage|alert)\([[:space:]]*["'\''`][^"'\''`]*[A-Za-z]{2,}' "$ROOT" 2>/dev/null \
+    | DENOISE || true
+
+echo
+echo "== SECTION 2d: metadata / JSON-LD human-readable string literals =="
+echo "   title/description/name/... : \"words\"  inside metadata or ld+json -> translate(TX.x)"
+echo "   (data fields - streetAddress, email, ids, lang codes - stay bare; see rules.md)"
+# Keywords narrowed to metadata/JSON-LD-specific keys: generic `name`/`label`/`heading`
+# match too much config (index options, demo data) to be useful as leads.
+SEARCH -e '\b(title|description|siteName|ogTitle|ogDescription|twitterTitle|twitterDescription|headline|serviceType|tagline)[[:space:]]*:[[:space:]]*["'\''`][^"'\''`]*[A-Za-z]{2,}' "$ROOT" 2>/dev/null \
+    | DENOISE || true
+
+echo
+echo "== done. Confirm every lead by reading the file against reference/rules.md. =="