@pikku/skills 0.12.22 → 0.12.25

package/skills/pikku-emails/SKILL.md

@@ -9,8 +9,8 @@ description: >-
   or emailTemplatesDir in pikku.config.json. TRIGGER when: user asks to add/edit a transactional
   email (verification, password reset, invitation, receipt), wire email sending, or translate an
   email. DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows
-  in general (use pikku-better-auth).
-installGroups: [fabric]
+  in general (use pikku-auth).
+installGroups: [core]
 ---
 
 # Pikku Emails
@@ -187,6 +187,7 @@ async send(input: SendEmailInput) {
   const r = renderEmailTemplate(input.template as RenderEmailInput<EmailTemplateName>)
   return this.delegate.send({
     to: input.to, from: input.from, subject: r.subject, html: r.html,
+    attachments: input.attachments,
     ...(r.text ? { text: r.text } : {}),
   })
 }

package/skills/pikku-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-fabric
-description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. TRIGGER when: user asks about a `pikku fabric validate` finding, including app-missing-actor-quick-login. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
+description: 'Build, convert and debug apps on the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, the pikku-verify workflow, and reading logs, traces and metrics from a deployed stage. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, asking about Fabric deployment, database or project conventions, asking about a `pikku fabric validate` finding including app-missing-actor-quick-login, or a deployed stage is erroring, timing out or behaving differently than local ("why is prod failing", "check the logs"). DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy instead — or the failure reproduces locally, which is where to debug it.'
 installGroups: [fabric]
 ---
 
@@ -21,7 +21,7 @@ Use this skill as an execution checklist, not reference material.
 5. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 6. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
-Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-http`, `pikku-services`, etc.
+Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-wiring`, `pikku-services`, etc.
 
 ## Before you start
 
@@ -440,3 +440,13 @@ Fix every `error` and `warn` in the output before continuing. Then:
 6. **Add `pikkufabric.config.json`** at project root with `projectId`, `production.domain`, and `frontends` (production is always `main`, so there is no `production.branch`).
 7. **Run `pikku all`** — verify codegen succeeds and there are no type errors.
 8. **Run `pikku fabric validate`** once more to confirm no structural issues remain.
+
+## A deployed stage misbehaving
+
+Reproduce locally first — a deployed stage adds cost and latency to every
+iteration, and a failure that reproduces locally is a local debugging problem.
+When it only happens deployed, read `references/debugging.md`: start from
+`errors` rather than `logs` (they are already filtered and carry the traceId),
+follow one trace end to end before forming a theory, and confirm the fix against
+the same stage. A deploy that *failed* is a build or config problem and belongs
+above, not there.

package/skills/{pikku-fabric-debug/SKILL.md → pikku-fabric/references/debugging.md}

@@ -1,9 +1,3 @@
----
-name: pikku-fabric-debug
-description: 'Debug a deployed Fabric stage from the CLI — read logs, find recent errors, follow a single request end-to-end by traceId, and check request/error/latency metrics. TRIGGER when: a deployed Fabric app is erroring, timing out, or behaving differently than local; the user asks "why is prod failing", "check the logs", "what happened to this request"; or a deploy succeeded but the app misbehaves. DO NOT TRIGGER when: the failure reproduces locally (debug it locally), the deploy itself failed (use pikku-fabric — that is a build/config problem, not a runtime one), or the project is not deployed to Fabric.'
-installGroups: [fabric]
----
-
 # Debugging a deployed Fabric stage
 
 ## Agent Operating Procedure

package/skills/pikku-i18n/SKILL.md

@@ -1,224 +1,77 @@
 ---
 name: pikku-i18n
-description: 'Wire i18n into a Pikku frontend with Paraglide JS (inlang). English by default, every user-facing string is a typed message function (`m.some__key()`) compiled from `messages/<locale>.json`, and additional languages are served under `/fr` `/de` URL prefixes. TRIGGER when: scaffolding or editing a frontend and writing user-facing text, adding a second language, or asked to "make this translatable / use tokens / add i18n". DO NOT TRIGGER for backend functions, error messages thrown from functions, or log output.'
-installGroups: [client, fabric]
+description: >-
+  Use when writing user-facing text in a Pikku frontend, or making one speak another language.
+  Covers Paraglide JS message functions compiled from messages/<locale>.json, adding a second
+  language, generated enum-label maps with @pikku/paraglide, and right-to-left support for Arabic,
+  Hebrew, Farsi and Urdu. TRIGGER when: scaffolding or editing a frontend and writing display
+  text, asked to make copy translatable, adding a language, labelling an enum/status/role value,
+  or asked to support RTL / mirror the layout. DO NOT TRIGGER for backend functions, error
+  messages thrown from functions, or log output — none of those are display strings.
+installGroups: [client]
 ---
 
-# Pikku i18n (Paraglide JS)
+# Pikku i18n
 
-## Agent Operating Procedure
+## Every visible string is a message
 
-Use this skill as an execution checklist, not reference material.
+Never hardcode display text: add a key to `messages/en.json` and render
+`m.the__key()`. This holds even in an app that will only ever ship English —
+the messages are the seam a second language slots into, and the deploy pipeline
+type-checks them, so an i18n mistake blocks the build rather than the release.
 
-1. Every user-facing string in a frontend is a message. Never hardcode display text — add a key to `messages/en.json` and render `m.the__key()`. This holds even when the app ships only English; the messages are the seam a second language slots into later.
-2. One `messages/<locale>.json` per language at the app root (NOT under `src/`), declared in `project.inlang/settings.json`. English (`en`) is `baseLocale` and the only locale until someone adds another. **`baseLocale` stays `en` whatever language the product speaks** — see [The product's language is not the code's language](#the-products-language-is-not-the-codes-language), which is the first thing to read if the brief says the app is not in English.
-3. Messages compile to typed ESM functions in `src/paraglide/` (generated, self-gitignored — never edit or commit it). The Vite plugin compiles during `dev`/`build` with HMR on message edits; run the CLI compile only when you need `tsc` before Vite has ever run.
-4. Validate with the app's own `tsc` then its `build`. The deploy pipeline compiles Paraglide and runs each frontend's `tsc` before building it — an i18n mistake blocks the deploy.
+## Pick the reference
 
-## The product's language is not the code's language
+| You are… | Read |
+| --- | --- |
+| Writing copy, wiring Paraglide, or adding a language | `references/messages.md` |
+| Labelling an enum, status, kind or role value | `references/enum-labels.md` |
+| Adding Arabic (or Hebrew, Farsi, Urdu), or writing layout styles | `references/rtl.md` |
 
-A brief that says "the entire UI is German, no English strings visible anywhere"
-is a statement about **one** of three separate things, and reading it as a
-statement about the codebase is the single most expensive mistake available in
-this skill. Three axes:
+## Three axes, and a brief usually means only one
 
-| Axis            | What it covers                                                                                          | What sets it                                                    |
-| --------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| **Identifiers** | Function, component, type and file names; database tables and columns                                   | Nothing — always English, no setting                            |
-| **Meta**        | `description` / `name` / `title` / `template` authored inside the code, which the Pikku Console renders | `metaLocale` in `pikku.config.json`, default `en`                   |
-| **Product UI**  | Every string the app shows a user                                                                       | `messages/<locale>.json` + `defaultLocale` — **this axis only** |
+"The entire UI is German" is a statement about the product, not about the
+codebase. Reading it as one about the codebase is the most expensive mistake
+available here.
 
-A non-English product moves the third row and nothing else.
+| Axis | What it covers | What sets it |
+| --- | --- | --- |
+| **Identifiers** | Function, component, type and file names; tables and columns | Nothing — always English |
+| **Meta** | `description` / `name` / `title` authored in code, rendered by the console | `metaLocale` in `pikku.config.json` |
+| **Product UI** | Every string the app shows a user | `messages/<locale>.json` + `defaultLocale` |
 
-### `baseLocale` stays `en`
+`baseLocale` stays `en` whatever language the product speaks — it names the
+message *source* catalogue every other locale is derived from, not the language
+the app is in. Set `defaultLocale` instead.
 
-`baseLocale` in `project.inlang/settings.json` does not mean "the language the
-app is in". It names the message **source** — the catalogue every other locale is
-cloned from and translated against. Setting it to the product's language looks
-like it works, because the app does come up in that language, and then:
+## Direction is one setting, not per-component work
 
-- there is no `en.json`, so `--add-locale` has no catalogue to translate from
-- the app can never gain a second language without re-authoring every key
-- a message missing from a locale falls back to a catalogue nobody wrote
-
-The setting that actually decides what a first-time visitor sees is
-`defaultLocale`, held in `apps/app/src/i18n/active.json` in the Fabric app
-template and read by `src/i18n/config.ts`. It is deliberately a separate file
-from `settings.json` for exactly this reason — the source language and the
-served language are different questions.
-
-So a German medical portal is **three** settings, not one:
-
-```jsonc
-// project.inlang/settings.json — the source catalogue is English
-{ "baseLocale": "en", "locales": ["en", "de"] }
-
-// apps/app/src/i18n/active.json — what a visitor opens in
-{ "defaultLocale": "de" }
-
-// pikku.config.json — the language the team reads their Console in
-{ "metaLocale": "de" }
-```
-
-In the Fabric template both of the first two have a command, so you rarely edit
-them by hand:
-
-```sh
-fabric i18n --add-locale de       # adds "de" to locales, seeds messages/de.json from en.json
-fabric i18n --default-locale de   # writes active.json — the app now OPENS in German
-```
-
-### The failure this is written from
-
-A real build, from this template. The brief said the UI was German; the agent
-set `baseLocale: "de"` with `locales: ["de"]` and no `en.json`, then carried the
-same reading into the code — RPC functions `getUebersicht` and
-`getPatientendetail`, components `Zeitstrahl` and `AufmerksamkeitStreifen`,
-helpers `datumDeutsch` and `voraussichtlichFertig`, database tables `vorgang`
-and `ereignis` with German columns.
-
-The German UI it was asked for needed none of that. It needed German **values**
-in a catalogue whose keys and source stayed English. What it got instead was a
-project that cannot add a second language and cannot be picked up by anyone who
-does not read German.
-
-If you find a project in this state, say so plainly rather than working around
-it: `baseLocale` cannot be repointed without re-keying every message, so it is a
-migration someone has to agree to, not a fix to slip in.
-
-## The moving parts (starter-template layout)
-
-- `messages/en.json` — flat keys, `{param}` interpolation, inlang message-format:
-  ```json
-  {
-    "$schema": "https://inlang.com/schema/inlang-message-format",
-    "auth__login__title": "Sign in",
-    "auth__login__description": "Welcome back to {name}."
-  }
-  ```
-  Key convention: lower snake_case, `__` (double underscore) between namespace segments, `_` within a segment — `auth__login__title`, `common__email_placeholder`.
-- `project.inlang/settings.json` — `baseLocale`, `locales`, the `@inlang/plugin-message-format` module, `pathPattern: "./messages/{locale}.json"`.
-- `vite.config.ts` — `paraglideVitePlugin({ project: './project.inlang', outdir: './src/paraglide' })` from `@inlang/paraglide-js` (devDependency), FIRST in the plugins array.
-- `src/paraglide/` — compiled output (`messages.js`, `runtime.js`, per-locale `messages/*.js`). Generated; it writes its own `.gitignore`.
-- `src/i18n/config.ts` — locale plumbing, and the ONLY hand-written i18n module: `supportedLocales`/`defaultLocale` (re-exported from `../paraglide/runtime.js`), `detectLocale`, `localeDir` (RTL for ar/he/fa/ur), a reactive locale store (`overwriteGetLocale` bridged to `useSyncExternalStore`), `setActiveLocale`, `useLocale()`. This is not a wrapper over messages — Paraglide's `getLocale()` is a module global with no React reactivity, and this bridges it. Wire `overwriteGetLocale` or `m.*()` will resolve a different locale than the app thinks is active.
-- `tsconfig.json` — `"allowJs": true, "checkJs": false` so `tsc` can consume Paraglide's JSDoc-typed JS output.
-
-## Using messages in components
-
-```tsx
-import { m } from '../paraglide/messages.js'
-import { useLocale } from '@/i18n/config'
-
-function LoginPage() {
-  useLocale() // subscribe: re-render m.*() when the locale switches
-  return (
-    <>
-      <Title>{m.auth__login__title()}</Title>
-      <Text>{m.auth__login__description({ name: m.app__name() })}</Text>
-    </>
-  )
-}
-```
-
-- Params: `{name}` in the JSON → `m.auth__login__description({ name })`. Params are typed per message.
-- Any component that renders `m.*()` calls `useLocale()` (bare call is enough); it also returns `{ locale, dir, setLocale }` for switchers.
-- Non-component helpers (formatters, status maps) call `m.some__key()` directly — the functions are plain ESM, no hook needed; the render-time subscription lives in the component that displays the result.
-- Locale switching: the root route persists to localStorage, sets `<html lang dir>` (`localeDir`), and calls `setActiveLocale` — in-SPA re-render, no page reload. Mirror `routes/__root.tsx` in the starter template.
-
-## Keys only known at runtime (enum labels, status maps)
-
-A DB value picking a label is the one case a generated message can't express.
-Paraglide's README (§ "What about dynamic or CMS-driven keys?") is explicit: use
-an **explicit mapping from value to message function**. Key it on the enum type,
-never `string`:
-
-```ts
-import { m } from '../paraglide/messages.js'
-
-const DOCUMENT_STATUS_LABEL: Record<DocumentStatus, () => string> = {
-  completed: m.enum__document_status__completed,
-  in_progress: m.enum__document_status__in_progress,
-  required: m.enum__document_status__required,
-}
-
-// call site — no fallback, because there is no missing case
-DOCUMENT_STATUS_LABEL[status]()
-```
-
-`Record<DocumentStatus, …>` is exhaustive: add a value to the enum without a
-label and the build fails. That is the entire point.
-
-**Don't write these maps by hand.** `@pikku/paraglide` generates them from the
-`enum__<group>__<member>` keys in the catalog and types each one against the DB
-enum it mirrors, so a migration adding a status is a compile error rather than a
-map someone forgot. Use the namespace above (singular `enum`, `__` between
-segments) so the generator picks the group up, and read `pikku-paraglide` before
-adding one.
-
-Do NOT write `Record<string, () => string>` with a `?? status` fallback, and do
-NOT index the namespace with a computed key (`m[\`enums__${name}__${value}\`]`).
-Both compile, both render the raw identifier to users when a label is missing,
-and both reintroduce exactly the silent-fallback failure Paraglide exists to
-eliminate. If you find yourself writing a `resolveDynamicKey(key: string)`
-helper, stop — that helper IS the bug.
-
-## Type safety — and why deploys block on i18n
-
-A message IS a function: a typo'd or deleted key (`m.auth__login__titel()`) is a missing export — a **TypeScript error**, not a silent runtime fallback string. Params are typed too. The deploy pipeline compiles Paraglide then runs each frontend's `tsc` (`"tsc": "tsc --noEmit"` script — keep it in every frontend's `package.json`) **before** building; a type error aborts the deploy. `vite build` does not type-check on its own, so this gate is the only thing standing between a broken message and production.
-
-The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/mantine` `I18nNode` prop typing catches those: a raw string literal fails to compile on a gated prop, because `I18nString` is a branded type a bare `string` can't satisfy. Between the two, `tsc` is the whole safety net — there is no runtime fallback to inspect, by design.
-
-## Compile step
-
-- **Dev/build:** the Vite plugin compiles automatically; editing `messages/*.json` under a running dev server recompiles + HMRs.
-- **Standalone `tsc` before Vite has run** (fresh clone, CI):
-  ```sh
-  npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/paraglide
-  ```
-  This is exactly what the deploy CI does before the per-app `tsc`.
-
-## Adding a second language
-
-1. `messages/fr.json` mirroring `en.json`'s keys (translate the values, keep `{param}` names identical).
-2. Add `"fr"` to `locales` in `project.inlang/settings.json`. **Leave `baseLocale` at `en`** — step 1 only works because there is an English catalogue to mirror.
-3. Recompile (restart/`vite dev` or the CLI compile). A locale file missing keys falls back to the base locale per message.
-4. Content is reachable via the `/<lang>` URL prefix (`detectLocale` already resolves it); the base locale needs no prefix. Expose the switcher via `useLocale().setLocale`.
-5. Only if the app should **open** in the new language rather than merely offer it: set `defaultLocale` (`active.json` / `fabric i18n --default-locale fr`). Adding a locale and changing the default are different asks — do the second only when asked.
-
-## i18n debug mode (find inlined strings)
-
-`tsc` catches invalid messages, and the `@pikku/mantine` gate catches raw strings on gated props — but neither sees a hardcoded string in plain JSX, an `aria-label`, `alt`, `document.title`, or anything passed to a non-Mantine component. Debug mode covers that gap: render every message as block glyphs (`█`), and whatever is still readable never went through a message.
-
-**Build it as a generated locale, never as a runtime wrapper.** Masked text is text, and rendering different text per locale is what Paraglide already does:
-
-1. A script generates `messages/zz.json` from `en.json`, replacing `\S` with `█` while leaving `{placeholders}` intact (they are message inputs — mangling them changes the compiled signature). Run it before `paraglide-js compile`; gitignore the output.
-2. Add `"zz"` to `locales` in `project.inlang/settings.json`.
-3. Switch to it in the locale bridge:
-   ```ts
-   overwriteGetLocale(() => (isI18nDebug() ? 'zz' : activeLocale))
-   ```
-
-Keep `zz` out of the app's own `supportedLocales` — that drives URL prefixes, hreflang and any backend `locale` param, none of which should see it.
-
-Generate the catalogue in dev only. With `messages/zz.json` absent, Paraglide compiles `zz` to an alias of the base locale (`const zz_x = en_x` — one line per message, no duplicated strings), so a production bundle carries the locale at effectively zero cost.
-
-Both the generator and the store bridge are being upstreamed (pikkujs/pikku#1036, #1035).
-
-The wrapper alternative — a module that walks the namespace and pipes each message through a `mask()` — is what this replaces. It defeats tree-shaking (touching every export), adds a check on every call, and forces every component to import `m` from the wrapper instead of Paraglide.
+Set `dir` once at the document root from the active locale and the browser (and
+Mantine) mirror everything — provided every custom style is flow-relative
+(`margin-inline-start`, `text-align: start`, Mantine `ms`/`me`) rather than
+physical (`margin-left`, `text-align: left`, `ml`/`me`'s physical twins). Write
+logical properties from the start even in an English-only app; that discipline
+is what makes an RTL language just another locale file.
 
 ## What NOT to do
 
-- Don't hardcode display strings "just for now" — the message is the work.
-- Don't set `baseLocale` to anything but `en`, whatever language the product speaks. It names the source catalogue, and a project without one can never add a language. Set `defaultLocale` instead.
-- Don't let a non-English UI reach the identifiers. Functions, components, types, files, tables and columns are English in every project; the product's language lives in `messages/*.json` and nowhere else.
-- Don't translate message **keys**. `auth__login__title` stays English in `de.json`; only the value changes.
-- Don't edit or commit anything under `src/paraglide/` — it's regenerated; change `messages/*.json` instead.
-- **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the `@pikku/mantine` `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
-
-  `packages/console` is the one place in this repo that still wraps it, in `src/i18n/messages.ts`, to keep the debug mask (`█`) it carried over from i18next. That wrapper is a leftover, not a pattern — the generated-locale approach above is how a new app gets the same masking without touching every export. Don't copy it.
-
-  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message _function_ and call it — the map is type-checked, a string is not.
-
-- Don't re-resolve messages by string key or re-implement `{param}` interpolation. A key-string resolver turns a missing key back into silent runtime text, surrendering the type safety that is the entire reason to use Paraglide.
-- Don't reach for i18next/react-i18next or a runtime-fetch translation loader — Paraglide's compiled functions are the whole delivery mechanism.
-- Don't tokenize backend error messages or logs here — those are not frontend display strings.
+- **Do not resolve a message key at runtime.** No `mKey('status.' + value)`, no
+  `m['enum__' + x]()`, no key-string resolver. A computed key cannot be
+  type-checked or tree-shaken, so a renamed message degrades to silent runtime
+  text. Where the key is genuinely dynamic, map the discriminant to a message
+  *function* — the map is checked, a string is not.
+- **Do not `asI18n()` a hardcoded English string.** `asI18n` exists to pass
+  opaque server data (a name, a slug, an id) through the i18n gate. An enum value
+  goes through its generated label map.
+- **Do not wrap `m`.** No re-export module, no branding layer. `m.some__key()`
+  already satisfies the `I18nNode` gate; a wrapper adds nothing and costs
+  per-message tree-shaking.
+- **Do not translate message keys.** `auth__login__title` stays English in
+  `de.json`; only the value changes.
+- **Do not edit or commit `src/paraglide/`, `i18n-enum.gen.ts` or `enums.gen.ts`.**
+  Change the catalogue or the migration and regenerate.
+- **Do not fake RTL** with `flex-direction: row-reverse`, reversed DOM order, or
+  per-locale layout branches. They double-flip the moment direction changes. DOM
+  order is logical order; let `dir` decide the visual one.
+- **Do not reach for i18next or a runtime translation loader.** Paraglide's
+  compiled functions are the whole delivery mechanism.

package/skills/{pikku-paraglide/SKILL.md → pikku-i18n/references/enum-labels.md}

@@ -1,9 +1,3 @@
----
-name: pikku-paraglide
-description: 'Generate typed, static enum-label maps for a Paraglide i18n frontend with `@pikku/paraglide`, and reconcile them against the database enum columns so a label can never silently drift from a DB value. Enum-valued labels live under a reserved `enum__<group>__<member>` message namespace; the generator emits `i18n-enum.gen.ts` typed `satisfies EnumLabel<DbEnum>`. TRIGGER when: labelling an enum/status/kind/role value in a Paraglide app, replacing a dynamic `mKey(...)`/`m[...]` lookup with a static map, wiring `@pikku/paraglide` into Vite, or reconciling i18n against `CHECK (col IN (...))` / Postgres enum columns. DO NOT TRIGGER for plain free-text UI copy (that is a normal `m.some_key()` message), backend errors, or logs.'
-installGroups: [client]
----
-
 # Pikku Paraglide enum labels
 
 ## Agent Operating Procedure

package/skills/pikku-i18n/references/messages.md

@@ -0,0 +1,218 @@
+# Pikku i18n (Paraglide JS)
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Every user-facing string in a frontend is a message. Never hardcode display text — add a key to `messages/en.json` and render `m.the__key()`. This holds even when the app ships only English; the messages are the seam a second language slots into later.
+2. One `messages/<locale>.json` per language at the app root (NOT under `src/`), declared in `project.inlang/settings.json`. English (`en`) is `baseLocale` and the only locale until someone adds another. **`baseLocale` stays `en` whatever language the product speaks** — see [The product's language is not the code's language](#the-products-language-is-not-the-codes-language), which is the first thing to read if the brief says the app is not in English.
+3. Messages compile to typed ESM functions in `src/paraglide/` (generated, self-gitignored — never edit or commit it). The Vite plugin compiles during `dev`/`build` with HMR on message edits; run the CLI compile only when you need `tsc` before Vite has ever run.
+4. Validate with the app's own `tsc` then its `build`. The deploy pipeline compiles Paraglide and runs each frontend's `tsc` before building it — an i18n mistake blocks the deploy.
+
+## The product's language is not the code's language
+
+A brief that says "the entire UI is German, no English strings visible anywhere"
+is a statement about **one** of three separate things, and reading it as a
+statement about the codebase is the single most expensive mistake available in
+this skill. Three axes:
+
+| Axis            | What it covers                                                                                          | What sets it                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; database tables and columns                                   | Nothing — always English, no setting                            |
+| **Meta**        | `description` / `name` / `title` / `template` authored inside the code, which the Pikku Console renders | `metaLocale` in `pikku.config.json`, default `en`                   |
+| **Product UI**  | Every string the app shows a user                                                                       | `messages/<locale>.json` + `defaultLocale` — **this axis only** |
+
+A non-English product moves the third row and nothing else.
+
+### `baseLocale` stays `en`
+
+`baseLocale` in `project.inlang/settings.json` does not mean "the language the
+app is in". It names the message **source** — the catalogue every other locale is
+cloned from and translated against. Setting it to the product's language looks
+like it works, because the app does come up in that language, and then:
+
+- there is no `en.json`, so `--add-locale` has no catalogue to translate from
+- the app can never gain a second language without re-authoring every key
+- a message missing from a locale falls back to a catalogue nobody wrote
+
+The setting that actually decides what a first-time visitor sees is
+`defaultLocale`, held in `apps/app/src/i18n/active.json` in the Fabric app
+template and read by `src/i18n/config.ts`. It is deliberately a separate file
+from `settings.json` for exactly this reason — the source language and the
+served language are different questions.
+
+So a German medical portal is **three** settings, not one:
+
+```jsonc
+// project.inlang/settings.json — the source catalogue is English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "metaLocale": "de" }
+```
+
+In the Fabric template both of the first two have a command, so you rarely edit
+them by hand:
+
+```sh
+fabric i18n --add-locale de       # adds "de" to locales, seeds messages/de.json from en.json
+fabric i18n --default-locale de   # writes active.json — the app now OPENS in German
+```
+
+### The failure this is written from
+
+A real build, from this template. The brief said the UI was German; the agent
+set `baseLocale: "de"` with `locales: ["de"]` and no `en.json`, then carried the
+same reading into the code — RPC functions `getUebersicht` and
+`getPatientendetail`, components `Zeitstrahl` and `AufmerksamkeitStreifen`,
+helpers `datumDeutsch` and `voraussichtlichFertig`, database tables `vorgang`
+and `ereignis` with German columns.
+
+The German UI it was asked for needed none of that. It needed German **values**
+in a catalogue whose keys and source stayed English. What it got instead was a
+project that cannot add a second language and cannot be picked up by anyone who
+does not read German.
+
+If you find a project in this state, say so plainly rather than working around
+it: `baseLocale` cannot be repointed without re-keying every message, so it is a
+migration someone has to agree to, not a fix to slip in.
+
+## The moving parts (starter-template layout)
+
+- `messages/en.json` — flat keys, `{param}` interpolation, inlang message-format:
+  ```json
+  {
+    "$schema": "https://inlang.com/schema/inlang-message-format",
+    "auth__login__title": "Sign in",
+    "auth__login__description": "Welcome back to {name}."
+  }
+  ```
+  Key convention: lower snake_case, `__` (double underscore) between namespace segments, `_` within a segment — `auth__login__title`, `common__email_placeholder`.
+- `project.inlang/settings.json` — `baseLocale`, `locales`, the `@inlang/plugin-message-format` module, `pathPattern: "./messages/{locale}.json"`.
+- `vite.config.ts` — `paraglideVitePlugin({ project: './project.inlang', outdir: './src/paraglide' })` from `@inlang/paraglide-js` (devDependency), FIRST in the plugins array.
+- `src/paraglide/` — compiled output (`messages.js`, `runtime.js`, per-locale `messages/*.js`). Generated; it writes its own `.gitignore`.
+- `src/i18n/config.ts` — locale plumbing, and the ONLY hand-written i18n module: `supportedLocales`/`defaultLocale` (re-exported from `../paraglide/runtime.js`), `detectLocale`, `localeDir` (RTL for ar/he/fa/ur), a reactive locale store (`overwriteGetLocale` bridged to `useSyncExternalStore`), `setActiveLocale`, `useLocale()`. This is not a wrapper over messages — Paraglide's `getLocale()` is a module global with no React reactivity, and this bridges it. Wire `overwriteGetLocale` or `m.*()` will resolve a different locale than the app thinks is active.
+- `tsconfig.json` — `"allowJs": true, "checkJs": false` so `tsc` can consume Paraglide's JSDoc-typed JS output.
+
+## Using messages in components
+
+```tsx
+import { m } from '../paraglide/messages.js'
+import { useLocale } from '@/i18n/config'
+
+function LoginPage() {
+  useLocale() // subscribe: re-render m.*() when the locale switches
+  return (
+    <>
+      <Title>{m.auth__login__title()}</Title>
+      <Text>{m.auth__login__description({ name: m.app__name() })}</Text>
+    </>
+  )
+}
+```
+
+- Params: `{name}` in the JSON → `m.auth__login__description({ name })`. Params are typed per message.
+- Any component that renders `m.*()` calls `useLocale()` (bare call is enough); it also returns `{ locale, dir, setLocale }` for switchers.
+- Non-component helpers (formatters, status maps) call `m.some__key()` directly — the functions are plain ESM, no hook needed; the render-time subscription lives in the component that displays the result.
+- Locale switching: the root route persists to localStorage, sets `<html lang dir>` (`localeDir`), and calls `setActiveLocale` — in-SPA re-render, no page reload. Mirror `routes/__root.tsx` in the starter template.
+
+## Keys only known at runtime (enum labels, status maps)
+
+A DB value picking a label is the one case a generated message can't express.
+Paraglide's README (§ "What about dynamic or CMS-driven keys?") is explicit: use
+an **explicit mapping from value to message function**. Key it on the enum type,
+never `string`:
+
+```ts
+import { m } from '../paraglide/messages.js'
+
+const DOCUMENT_STATUS_LABEL: Record<DocumentStatus, () => string> = {
+  completed: m.enum__document_status__completed,
+  in_progress: m.enum__document_status__in_progress,
+  required: m.enum__document_status__required,
+}
+
+// call site — no fallback, because there is no missing case
+DOCUMENT_STATUS_LABEL[status]()
+```
+
+`Record<DocumentStatus, …>` is exhaustive: add a value to the enum without a
+label and the build fails. That is the entire point.
+
+**Don't write these maps by hand.** `@pikku/paraglide` generates them from the
+`enum__<group>__<member>` keys in the catalog and types each one against the DB
+enum it mirrors, so a migration adding a status is a compile error rather than a
+map someone forgot. Use the namespace above (singular `enum`, `__` between
+segments) so the generator picks the group up, and read `references/enum-labels.md` before
+adding one.
+
+Do NOT write `Record<string, () => string>` with a `?? status` fallback, and do
+NOT index the namespace with a computed key (`m[\`enums__${name}__${value}\`]`).
+Both compile, both render the raw identifier to users when a label is missing,
+and both reintroduce exactly the silent-fallback failure Paraglide exists to
+eliminate. If you find yourself writing a `resolveDynamicKey(key: string)`
+helper, stop — that helper IS the bug.
+
+## Type safety — and why deploys block on i18n
+
+A message IS a function: a typo'd or deleted key (`m.auth__login__titel()`) is a missing export — a **TypeScript error**, not a silent runtime fallback string. Params are typed too. The deploy pipeline compiles Paraglide then runs each frontend's `tsc` (`"tsc": "tsc --noEmit"` script — keep it in every frontend's `package.json`) **before** building; a type error aborts the deploy. `vite build` does not type-check on its own, so this gate is the only thing standing between a broken message and production.
+
+The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/mantine` `I18nNode` prop typing catches those: a raw string literal fails to compile on a gated prop, because `I18nString` is a branded type a bare `string` can't satisfy. Between the two, `tsc` is the whole safety net — there is no runtime fallback to inspect, by design.
+
+## Compile step
+
+- **Dev/build:** the Vite plugin compiles automatically; editing `messages/*.json` under a running dev server recompiles + HMRs.
+- **Standalone `tsc` before Vite has run** (fresh clone, CI):
+  ```sh
+  npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/paraglide
+  ```
+  This is exactly what the deploy CI does before the per-app `tsc`.
+
+## Adding a second language
+
+1. `messages/fr.json` mirroring `en.json`'s keys (translate the values, keep `{param}` names identical).
+2. Add `"fr"` to `locales` in `project.inlang/settings.json`. **Leave `baseLocale` at `en`** — step 1 only works because there is an English catalogue to mirror.
+3. Recompile (restart/`vite dev` or the CLI compile). A locale file missing keys falls back to the base locale per message.
+4. Content is reachable via the `/<lang>` URL prefix (`detectLocale` already resolves it); the base locale needs no prefix. Expose the switcher via `useLocale().setLocale`.
+5. Only if the app should **open** in the new language rather than merely offer it: set `defaultLocale` (`active.json` / `fabric i18n --default-locale fr`). Adding a locale and changing the default are different asks — do the second only when asked.
+
+## i18n debug mode (find inlined strings)
+
+`tsc` catches invalid messages, and the `@pikku/mantine` gate catches raw strings on gated props — but neither sees a hardcoded string in plain JSX, an `aria-label`, `alt`, `document.title`, or anything passed to a non-Mantine component. Debug mode covers that gap: render every message as block glyphs (`█`), and whatever is still readable never went through a message.
+
+**Build it as a generated locale, never as a runtime wrapper.** Masked text is text, and rendering different text per locale is what Paraglide already does:
+
+1. A script generates `messages/zz.json` from `en.json`, replacing `\S` with `█` while leaving `{placeholders}` intact (they are message inputs — mangling them changes the compiled signature). Run it before `paraglide-js compile`; gitignore the output.
+2. Add `"zz"` to `locales` in `project.inlang/settings.json`.
+3. Switch to it in the locale bridge:
+   ```ts
+   overwriteGetLocale(() => (isI18nDebug() ? 'zz' : activeLocale))
+   ```
+
+Keep `zz` out of the app's own `supportedLocales` — that drives URL prefixes, hreflang and any backend `locale` param, none of which should see it.
+
+Generate the catalogue in dev only. With `messages/zz.json` absent, Paraglide compiles `zz` to an alias of the base locale (`const zz_x = en_x` — one line per message, no duplicated strings), so a production bundle carries the locale at effectively zero cost.
+
+Both the generator and the store bridge are being upstreamed (pikkujs/pikku#1036, #1035).
+
+The wrapper alternative — a module that walks the namespace and pipes each message through a `mask()` — is what this replaces. It defeats tree-shaking (touching every export), adds a check on every call, and forces every component to import `m` from the wrapper instead of Paraglide.
+
+## What NOT to do
+
+- Don't hardcode display strings "just for now" — the message is the work.
+- Don't set `baseLocale` to anything but `en`, whatever language the product speaks. It names the source catalogue, and a project without one can never add a language. Set `defaultLocale` instead.
+- Don't let a non-English UI reach the identifiers. Functions, components, types, files, tables and columns are English in every project; the product's language lives in `messages/*.json` and nowhere else.
+- Don't translate message **keys**. `auth__login__title` stays English in `de.json`; only the value changes.
+- Don't edit or commit anything under `src/paraglide/` — it's regenerated; change `messages/*.json` instead.
+- **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the `@pikku/mantine` `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
+
+  `packages/console` is the one place in this repo that still wraps it, in `src/i18n/messages.ts`, to keep the debug mask (`█`) it carried over from i18next. That wrapper is a leftover, not a pattern — the generated-locale approach above is how a new app gets the same masking without touching every export. Don't copy it.
+
+  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message _function_ and call it — the map is type-checked, a string is not.
+
+- Don't re-resolve messages by string key or re-implement `{param}` interpolation. A key-string resolver turns a missing key back into silent runtime text, surrendering the type safety that is the entire reason to use Paraglide.
+- Don't reach for i18next/react-i18next or a runtime-fetch translation loader — Paraglide's compiled functions are the whole delivery mechanism.
+- Don't tokenize backend error messages or logs here — those are not frontend display strings.

package/skills/{pikku-rtl/SKILL.md → pikku-i18n/references/rtl.md}

@@ -1,12 +1,6 @@
----
-name: pikku-rtl
-description: 'Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.'
-installGroups: [client]
----
-
 # Pikku RTL (Arabic + English)
 
-This skill sits **on top of** `pikku-i18n`. That skill compiles a locale's
+This reference sits **on top of** `references/messages.md`. That one compiles a locale's
 messages into typed `m.*()` functions; this one adds the second axis: a locale
 also has a **direction**. Arabic is not special-cased — it is just another
 `messages/ar.json` listed in `project.inlang/settings.json`, plus the document
@@ -23,7 +17,7 @@ _layout_ code — directional icons still need one manual step, covered below.
 ## Agent Operating Procedure
 
 1. **Messages first.** Every visible string is already an `m.*()` message via
-   `pikku-i18n`. Arabic copy goes in `messages/ar.json`, mirroring `en.json`'s
+   `references/messages.md`. Arabic copy goes in `messages/ar.json`, mirroring `en.json`'s
    keys with the `{param}` names kept identical.
 2. **Add the direction helper** to the i18n config (one home for locale→dir):
    ```ts
@@ -219,5 +213,5 @@ left` with the flow-relative equivalent; revert any manual `row-reverse`.
 - Don't set `dir` on individual components — it belongs on `<html>` so the whole
   document (and Mantine) agrees.
 - Don't translate Arabic copy outside the message system; an RTL language is a
-  normal locale, governed by `pikku-i18n`. There is no `t()` and no i18next in a
+  normal locale, governed by `references/messages.md`. There is no `t()` and no i18next in a
   Pikku frontend — the string comes from `m.some__key()`.