@mionjs/run-types 0.8.10 → 0.13.2

package/skills/rt-enrich-types/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: rt-enrich-types
+description: FriendlyText/MockData enrich loop: mion enrich CLI, @todo blanks, @rt* tags, i18n. Use to scaffold/fill.
+---
+
+# RunTypes enrichment: compiler scaffolds, you fill blanks
+
+- Enrichment = committed, type-keyed data RunTypes cannot generate on its own.
+  - `FriendlyText<T>`: human labels + error messages. `MockData<T>`: realistic sample values.
+- Validators/codecs: pure functions of the type, recomputed every build, never committed.
+- Enrichment: authored once, committed, validated against the type forever after.
+- Full design: [docs/AI_ENRICHMENT.md](https://github.com/MionKit/mion/blob/main/docs/AI_ENRICHMENT.md).
+- Compiler writes the code: real, type-accurate file, every field in place, gaps marked `@todo`.
+- You (the agent) fill the gaps with believable, valid content.
+- ⚠️ Never call an LLM inside a build. Authoring = explicit out-of-band step → reviewable, committed diff.
+
+## The loop
+
+1. **`enrich`**: scaffold the mirror file. One entry per field, correctly typed, each blank marked `@todo`.
+2. **Fill the `@todo`s**: labels, messages, sample values. Delete each `@todo` line when done.
+3. **`enrich --no-emit`**: health check. Validates every authored value against the live type.
+   - FAILS on WRONG or stale content (dead field, leftover carcass).
+   - Only REPORTS unfilled blanks: `@todo` lines, empty `''` labels/messages, empty `[]` pools.
+   - (A fresh scaffold is expected to carry blanks.) Fix what fails, repeat until clean.
+   - **3b. `enrich --require-complete`**: the "am I done?" gate. All `--no-emit` checks + FAILS on any blank.
+     A blank value ships blank to the app → treated exactly like an unresolved `@todo`.
+     Run before calling enrichment finished. CI and a production bundler build enforce it.
+4. **`enrich --update`**: type changed → value-preserving re-sync (property merge + field rename + orphaning).
+   Fill any new `@todo`s it adds.
+5. **`enrich --prune`**: the only destructive op. Removes `@rtOrphan`/`@rtOrphanChild` carcasses
+   left by deleted types/fields.
+6. **`enrich --i18n <locale|all> [<src.ts>] [--update|--prune]`**: scaffold, reconcile or prune
+   per-locale translation files of the friendly maps.
+7. **`enrich --i18n <locale|all> --no-emit`**: translation status (enrich-i18n-\*, warnings by default).
+   **`--require-complete`** (or tsconfig `i18n.strict`) makes it FAIL for CI.
+
+Translations (steps 6-7): CLI, `--update` rules, findings, tsconfig `i18n` block → [translations.md](translations.md).
+
+## tsconfig
+
+- Every verb takes **`--tsconfig <path>`**. Without it: found exactly as tsc does, searching upward from cwd.
+- ONE resolved config feeds genDir/i18n settings AND type resolution (same compiler options as the build).
+- Config named or discovered but missing/broken → command stops with an error.
+- Only a project with no tsconfig at all falls back to built-in defaults.
+
+## Mirror directory + JSDoc tags
+
+Where files live, consumer imports, tag ownership table → [mirror.md](mirror.md). Read before editing a mirror file.
+
+- `@rt`-prefixed tags = compiler-owned. Never edit by hand. Plain `@todo` = yours; compiler only emits it.
+- `--update` never edits your values. `--prune` is the only command that deletes.
+
+## `FriendlyText<T>`: labels + error messages
+
+- Combined per-field map: `rt$label` (human name) + `rt$errors`.
+- `rt$errors`: one template per declared failable constraint, or exclusive `{rt$default: '…'}` catch-all.
+  - `type` required. Other constraint keys optional in the type: `enrich` scaffolds each, a missing one is reported.
+  - Count-bearing constraints scaffold plural objects.
+  - Scaffold always per-constraint. Switch a node to `rt$default` by hand.
+- Pure data. Rendered at runtime by `createFriendlyText<T>(map)`, or `createFriendlyTextI18n` + committed translations.
+- Full DSL (node shape, constraint keys, `$[…]` placeholders, plurals, `rt$default`, enrich-text-\* checks,
+  runtime rendering) = **`runtypes-friendly-text`** skill. Use it whenever you author or fill a friendly map.
+
+## `MockData<T>`: realistic sample data
+
+- Per-field pools + ranges: `pool`, `min`/`max`, `rt$items`/`rt$length`, `rt$optional`.
+- Feeds `createMockDataFn<T>(undefined, { data })`.
+- Mechanical generator keeps handling structure + format-correctness; you supply _believable_ values.
+- Full DSL (node shapes per field kind, enrich-mock-\* checks, end-to-end wiring) = **`runtypes-mock-data`** skill.
+  Use it whenever you author or fill a mock map.
+
+## Authoring checklist
+
+- `enrich` scaffold lays out every field. Write values that fit each field's kind + format.
+- Fill **every `@todo`** AND every blank value (`''` label/message, `[]` pool), then **delete that `@todo` line**.
+  A leftover blank = unresolved `@todo` for the completeness gate.
+- Never touch `@rt*` tags or `@rtOrphan`/`@rtOrphanChild` comment blocks. Compiler owns them; `--prune` clears orphans.
+- After editing: `enrich --no-emit`, resolve every Error.
+- Before calling it finished: `enrich --require-complete` (+ `enrich --i18n <locale|all> --require-complete`
+  for translations). Fails until every `@todo` and blank is filled.
+- Type changed → prefer `enrich --update` (keeps your values) over regenerating.
+- Family rules (friendly constraint keys, plural arms, translation fill discipline, mock pools/ranges):
+  **`runtypes-friendly-text`** and **`runtypes-mock-data`** skills' checklists.

package/skills/rt-enrich-types/mirror.md

@@ -0,0 +1,58 @@
+# Mirror directory + JSDoc tags
+
+Where enrichment files live, how consumers import them, who owns each tag.
+
+## Mirror directory: one file per family
+
+- Enrichment is committed to a **mirror directory**: its tree shadows your source, split **per family**.
+- Type defined in `src/models/user.ts`:
+  - `friendly<Name>` consts (`FriendlyText<Name>`) → `<genDir>/enriched/friendly/src/models/user.ts`.
+  - `mock<Name>` consts (`MockData<Name>`) → `<genDir>/enriched/mock/src/models/user.ts`.
+- Path follows the source file from the tsconfig folder, or from `rootDir` when set.
+  `rootDir: "src"` gives `friendly/models/user.ts`.
+- Default `genDir`: `.mion` in the source folder (`rootDir`, else the folder all program files share).
+- Configure it via the `mion` entry under `compilerOptions.plugins` in `tsconfig.json`.
+- One mirror file per family per source file. Anchored at the type's **definition**, not its call sites.
+- One `export` per enriched type defined there: one enrichment home per type, however many files consume it.
+- The two families never share a file. Each family file imports only its own wrapper type.
+- First committed RunTypes artifact (every other output is gitignored cache). Hand-editable.
+- `enrich --no-emit` flags a mirror outside its family folder: enrich-mirror-moved (location drift).
+- `--out` writes one combined file instead: explicit escape hatch.
+- Each family file: strict `import type` back to the source (the rename **breadcrumb**)
+  - committed consts you import by name.
+- The `import type` is best-effort: consumed type not exported → file fails to compile → fix the export.
+
+```ts
+// src/.mion/enriched/mock/src/models/user.ts: GENERATED, COMMITTED, hand-editable
+import type {User} from '../../../../../models/user';
+import type {MockData} from '@mionjs/run-types';
+
+/** @rtType User#9f3a @rtIds {age: b2, name: a1} */
+// @todo: generated skeleton — fill in real data, then delete this line
+export const mockUser: MockData<User> = {name: {pool: []}, age: {pool: []}};
+```
+
+Consumers use a **real, committed import**. Never plugin-injected (enrichment is committed, so its link is too).
+
+```ts
+// src/services/userForm.ts
+import {createMockDataFn} from '@mionjs/run-types/mocking';
+import {friendlyUser} from '../.mion/enriched/friendly/src/models/user';
+import {mockUser} from '../.mion/enriched/mock/src/models/user';
+import type {User} from '../models/user';
+
+createMockDataFn<User>(undefined, {data: mockUser});
+```
+
+## The JSDoc tags
+
+| Tag                     | Owner    | Meaning                                                                       |
+| ----------------------- | -------- | ----------------------------------------------------------------------------- |
+| `@rtType <Name>#<id>`   | compiler | const's stable structural identity; reconcile matches by this, not var name   |
+| `@rtIds {field: id, …}` | compiler | each field's child type id: lets `--update` detect a **rename**, carry value  |
+| `@rtOrphan …`           | compiler | whole const whose source type is gone: commented out (value kept), `--prune`d |
+| `@rtOrphanChild …`      | compiler | one field removed from the type: commented out (value kept), `--prune`d       |
+| `@todo …`               | **you**  | a blank the compiler scaffolded: fill it in, then **delete the line**         |
+
+- Hand-authored comments survive `--update` and travel with a renamed field.
+- `--update` only adds blanks, flags stale values, orphans gone fields.

package/skills/rt-enrich-types/translations.md

@@ -0,0 +1,77 @@
+# Translations: per-locale friendly files
+
+CLI, file layout, reconcile rules and tsconfig block for `enrich --i18n`.
+
+## Layout
+
+- The friendly map you author IS the source language: tsconfig `i18n.sourceLocale`, default `en`.
+- No separate default catalog, no separate translation type.
+- Each target locale gets committed `FriendlyText<T>` files shadowing the friendly mirror tree:
+  `<i18nDir>/<locale>/<rel>.ts`.
+  - Default `i18nDir`: `<genDir>/enriched/i18n`, resolved under the project root.
+  - e.g. `src/.mion/enriched/i18n/pl/src/models/user.ts`.
+  - Locale is a path segment, so `pt-BR` works verbatim.
+- Const per type: `<locale>_friendly<Name>`. BCP-47 `-` becomes `_`: `pt_BR_friendlyUser`.
+  - Annotated `FriendlyText<Name>`, SAME `@rtType <Name>#<id> @rtIds {…}` markers as the source.
+  - Path + const prefix carry the locale. No i18n marker.
+- Every locale file is generated FROM THE SOURCE TYPE by the same driver as the friendly mirror.
+  - Mirror = discovery input only (which sources translate), never a content input.
+  - No generated file ever feeds the generation of another.
+
+## CLI
+
+```
+mion enrich --i18n <locale> [<src.ts>]           # scaffold (create-only)
+mion enrich --i18n <locale> --update [<src.ts>]  # reconcile from the SOURCE TYPE
+mion enrich --i18n <locale> --prune  [<src.ts>]  # strip @rtOrphan carcasses (the only delete)
+mion enrich --i18n all [--update]                # fan out over tsconfig i18n.locales
+mion enrich --i18n <locale|all> --no-emit        # report status (warnings, exit 0)
+mion enrich --i18n <locale|all> --require-complete  # completeness gate (fails CI)
+```
+
+- No `<src.ts>` → targets = sources that have a friendly mirror (path math over `<genDir>/enriched/friendly/`).
+  Mirror content never read.
+- Scaffold = type's tree, every string leaf + plural arm an `@todo` blank (`''`).
+  NEVER copies source text as if translated.
+- Fill rules (translate only blank leaves, arms locale-owned, prune freely): **`runtypes-friendly-text`** skill,
+  translations page.
+
+## `--update`
+
+- Same value-preserving reconcile as `enrich --update`: one driver for every friendly-family file.
+- Includes the one-level `rt$errors` descent:
+  - Newly declared constraint key → blank of the right kind (string, or plural with THAT FILE's locale arms).
+  - Dropped RECOGNIZED constraint key → `@rtOrphanChild` carcass. Unknown keys = author-owned, untouched.
+  - Same-key leaf kept byte-identical. `rt$default`-only node never descended.
+- Plural arms never orphaned, renamed or down-scoped.
+- Type renames carry across locales via shared `@rtType` id.
+  Const, annotation, marker AND intra-file references renamed in place.
+
+## `enrich --i18n --no-emit` findings
+
+- enrich-i18n-missing-translation: translation file missing.
+- enrich-i18n-todo-left: unfilled `@todo` blanks.
+- enrich-i18n-out-of-date: out of date vs the SOURCE TYPE (a src-driven reconcile would change the file).
+- enrich-i18n-orphans: orphan carcasses awaiting review/prune.
+- All Warnings (exit 0). tsconfig `i18n.strict: true` OR `--require-complete` → Errors (exit 1).
+- Runtime always lenient regardless.
+
+## tsconfig `i18n` block
+
+Lives on the `mion` tsconfig plugin entry. Dormant by default: zero change when absent.
+
+```jsonc
+{
+  "name": "mion",
+
+  "i18n": {
+    "sourceLocale": "en", // language the source FriendlyText maps are written in
+    "dir": "src/.mion/enriched/i18n", // translation subtree root (default <genDir>/enriched/i18n)
+    "locales": ["es", "pl", "pt-BR"], // target locales (the source locale is NOT listed)
+    "strict": false, // when true, the i18n check fails on incompleteness by default (same as --require-complete)
+  },
+}
+```
+
+Runtime rendering (`createFriendlyTextI18n`, `resolveLocale` matching, per-leaf fallback,
+type-driven `$[val]` for Currency / date bounds): **`runtypes-friendly-text`** skill.

package/skills/runtypes-friendly-text/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: runtypes-friendly-text
+description: FriendlyText<T> rt$label/rt$errors ($[val], plurals, createFriendlyText). Use for friendly errors/labels.
+---
+
+# Authoring & using `FriendlyText<T>`
+
+- One of two AI-enrichment artifacts in RunTypes. Other: `MockData<T>` (`runtypes-mock-data` skill).
+- Enrichment is authored once, committed, validated against the type. CLI loop: `rt-enrich-types` skill.
+- Full design: [docs/AI_ENRICHMENT.md](https://github.com/MionKit/mion/blob/main/docs/AI_ENRICHMENT.md).
+- `FriendlyText<T>` = combined per-field map of:
+  - **labels**: `rt$label`, human name per field (`'Full name'` for `name`).
+  - **error-message templates**: `rt$errors`, one template per failed constraint.
+- **Pure data.** `createFriendlyText<T>(map)` renders `createGetValidationErrorsFn<T>()` output as readable messages.
+- No type-id injection, no `rtUtils`: error rendering needs only `(map, errors)`.
+
+## When to use it
+
+- Turn `createGetValidationErrorsFn<T>()` errors into readable text, not raw `{ path, expected, format }`.
+- You need stable human field **labels** (form building, error summaries).
+- Scaffolding a type's committed friendly mirror file.
+- Filling a locale's translation file (also typed `FriendlyText<T>`, rendered via `createFriendlyTextI18n`).
+- Boolean pass/fail only → `createValidateFn<T>()` directly, no friendly map.
+
+## Shipped vs designed
+
+- **Shipped**, all exported from `@mionjs/run-types`:
+  - [`friendlyText.ts`][ft]: `FriendlyText<T>` + plural types `PluralTemplate`, `TemplateLeaf`, `PluralCategory`.
+  - [`createFriendlyText.ts`][cft]: plural-aware `createFriendlyText<T>(map)`, `createFriendlyTextI18n`,
+    `resolveLocale`.
+  - `enrich` / `enrich --no-emit` CLI (incl. `--i18n`) scaffolds + validates the committed maps.
+- **Designed (not yet wired):** `ShapeCheckedArgs<T>` compile-time axis, `rtUtils` registry accessors.
+
+## Node model: `{ rt$label, rt$errors, ...children }`
+
+- One recursive node, uniform at every depth. No `fields:` wrapper: leaf nodes simply have no children.
+- `rt$`-prefixed keys = **meta**. Every other key = **child field**. A plain `$foo` property is just a field.
+- `rt$` prefix RESERVED: source-type property named `rt$…` is refused by `enrich` (enrich-text-reserved-prefix).
+- `rt$label: string`: field's human name, always a plain string. REQUIRED.
+- `rt$errors`: field's error templates. REQUIRED. Per-constraint record OR exclusive `{rt$default: '…'}` catch-all.
+  - Template leaf: plain string, or a **plural object** on count-bearing constraints (`TemplateLeaf`).
+- Arrays + rest tuples: `rt$items` (element node). Fixed tuples: positional `rt$slots`.
+- `Map`: `rt$keys` / `rt$values`. `Set`: `rt$values`.
+- Nested objects recurse with the _same_ node shape, every field of `T` present.
+- ⚠️ **The map is TOTAL.** Every field appears, every node carries both meta keys.
+  - Blank `''` = "no custom text" (renderer falls back gracefully), so blanks are always safe.
+  - Never delete a key to opt out: next `enrich --update` scaffolds it back. One type maps to exactly one shape.
+- `FriendlyText<T>` mapped type checks structure against `T`: missing field, object node where `T` is scalar
+  (or vice-versa), unknown `rt$errors` key = TYPE errors, caught in the IDE before `enrich --no-emit` runs.
+
+## Detail pages
+
+- `rt$errors` keys, `rt$default` mode, `$[…]` placeholders, plurals:
+  [error-templates.md](references/error-templates.md). Read before writing any template.
+- enrich-text-\* checks and levels → [checks.md](references/checks.md). Read when `enrich --no-emit` reports one.
+- `createFriendlyText` / `createFriendlyTextI18n` runtime → [rendering.md](references/rendering.md).
+- Locale files, fill rules → [translations.md](references/translations.md). Read before filling a translation.
+- Full type → map → consumer example → [example.md](references/example.md).
+
+## Where the map lives: friendly mirror file
+
+- At the file where the type is **defined**, not consumed: `src/models/user.ts` →
+  `<genDir>/enriched/friendly/src/models/user.ts` (default `src/.mion/enriched/friendly/src/models/user.ts`).
+- Holds `friendly<Name>` consts. `MockData<T>` consts live separately under `<genDir>/enriched/mock/…`.
+- Mirrors the cache's "one canonical entry per structural id, app-wide" rule.
+- Layout rules (genDir, `rootDir`, `import type` breadcrumb): `rt-enrich-types` skill.
+
+```ts
+// src/.mion/enriched/friendly/src/models/user.ts: committed, hand-editable
+import type {User} from '../../../../../models/user';
+import type {FriendlyText} from '@mionjs/run-types';
+
+/** @rtType User#9f3a @rtIds {…} */
+export const friendlyUser: FriendlyText<User> = {
+  /* … */
+};
+```
+
+## Authoring checklist
+
+- Map goes in the **definition's friendly mirror file** (`<genDir>/enriched/friendly/<rel>.ts`), not the consumer's.
+- Type it `FriendlyText<T>` so structure is checked against `T`. Keep it TOTAL (Node model above).
+- `rt$errors` key set = `type` + the field's **declared failable format params**.
+  Others optional in the type, any other key rejected. A bare `string` takes `type` only.
+- One sentence per field? `rt$errors: {rt$default: '…'}`. Exclusive, never mixed with per-constraint keys
+  (enrich-text-default-and-messages). Scaffolds always per-constraint: switch a node by hand.
+- Count-bearing constraints: fill scaffolded plural arms in place, never restructure the object.
+  Keep `other` (enrich-text-plural-missing-other), prune unused arms.
+  Count = the violated bound, not the received value's length.
+- Locale file: translate only blank leaves, never copy source text, prune arms your language doesn't use
+  (they stay pruned).
+
+[ft]: https://github.com/MionKit/mion/blob/main/packages/run-types/src/enrich/friendlyText.ts
+[cft]: https://github.com/MionKit/mion/blob/main/packages/run-types/src/enrich/createFriendlyText.ts

package/skills/runtypes-friendly-text/references/checks.md

@@ -0,0 +1,37 @@
+# Build-time checks: enrich-text-\*
+
+`enrich --no-emit` cross-references the authored literal against the live `RunType` and reports these.
+
+## Shipped
+
+- enrich-text-unknown-field (Warning): key is not a field of `T`. Stale (field renamed/removed), nothing reads it.
+  Catches drift: rename a field → this flags the now-stale entry.
+- enrich-text-unknown-error-key (Warning): `rt$errors` key is not an error this field can produce.
+  TS catches keys the FORMAT never produces as an excess-property error.
+- enrich-text-unknown-placeholder (Warning): unknown `$[…]` placeholder for this constraint/context.
+  Checked per plural arm.
+- enrich-text-plural-missing-other (Warning): plural object missing the mandatory `other` arm.
+- enrich-text-unknown-plural-arm (Warning): plural-object arm key is not a CLDR category.
+- enrich-text-plural-without-count (Info): plural object on a non-count-bearing constraint (dead arms).
+- enrich-text-default-and-messages (Warning): `rt$default` beside any other `rt$errors` key.
+  Modes are mutually exclusive; the catch-all silently wins.
+- enrich-text-missing-message (Warning): a failure this field can produce has no `rt$errors` key
+  (and no `rt$default`) → shows a generic message.
+- enrich-text-reserved-prefix (Error): a property of `T` is named `rt$…`, the reserved meta prefix.
+  `enrich` refuses the type up front, writes no mirror. Rename the property.
+- Unfilled scaffold: enrich-text-todo-left / enrich-text-blank-value (Warning).
+
+## Designed (not yet wired)
+
+- enrich-text-missing-label (Info): field of `T` has no label (renders the raw name).
+- enrich-text-shape-mismatch: object node where `T` is scalar, or vice-versa. `FriendlyText<T>` mapped type catches it.
+- enrich-text-type-drift: `T`'s structural id changed since authored, review for drift.
+
+## Levels
+
+- Content checks are **Warnings** (one Info): message still renders, falls back to something less specific
+  (generic "value is invalid", the `other` plural arm, the raw field name).
+- Degraded text = enrichment that did not apply, not a broken function.
+- **enrich-text-reserved-prefix is the one Error**: enrich plan fails, no mirror file written at all.
+- enrich-text-todo-left / enrich-text-blank-value fail `enrich --require-complete` through their
+  completeness flag, not their level.

package/skills/runtypes-friendly-text/references/error-templates.md

@@ -0,0 +1,94 @@
+# Error templates: keys, modes, placeholders, plurals
+
+What goes inside `rt$errors`.
+
+## `rt$errors` keys = the failed-constraint name
+
+- Each key names the sub-constraint that failed. Not an invented set:
+  maps 1:1 onto what `createGetValidationErrorsFn<T>()` emits.
+- Renderer picks the template by the error's `(format.name, formatPath-tail)` discriminator.
+- `type`: base type-shape failure (a `RunTypeError` with no `.format`), "not even the right kind of value".
+  Always present.
+- Format sub-constraints, exactly as the type declares them:
+  - string: `minLength`, `maxLength`, `pattern`, `allowedChars`
+  - number: `min`, `max`, `lt`, `gt`, `integer`
+  - datetime: `date`, `time`, `splitChar`
+  - `Date` bound: `min` / `max`; `uuid`: `version`
+- **Keys come from the format's own error code.** `ErrorTemplates<F>` reads the field's format NAME,
+  allows the keys in the generated `FormatErrorKeys` table (`src/go-generated/formatErrorKeys.generated.ts`,
+  built from each format's validation-errors code).
+- Every constraint key is optional in the type. Unknown key = excess-property TYPE error.
+- `enrich --no-emit` reports a missing key (enrich-text-missing-message)
+  or one this field can never fail on (enrich-text-unknown-error-key).
+- `enrich --update` adds missing keys as blanks.
+- Params that never fail (`float`, `isCurrency`, `mockSamples`, `separators`, the transformers) never become keys.
+- JSON Schema bounds (`minimum`, `exclusiveMinimum`, ...) use `min` / `max` / `gt` / `lt`.
+- Bare `name: string` takes `type` only. Richer friendly map requires a richer type annotation.
+
+## Two exclusive modes: per-constraint vs `rt$default`
+
+`rt$errors` is EITHER the per-constraint record OR the single catch-all. Never a mix.
+Never a function: only data survives translation, reconcile and the checker.
+
+- **Per-constraint**: `{type: '…', minLength: '…', …}`. **One message per failed constraint**.
+  Every key compiler-validated, placeholders too (enrich-text-unknown-placeholder).
+- **`rt$default`**: `{rt$default: '…'}`. ONE message for the whole field, whatever failed.
+  Plain data: translates and reconciles like any other leaf.
+- Mixing = TS union error + enrich-text-default-and-messages (Warning).
+- Each node picks its own mode. `enrich` always scaffolds NEW nodes per-constraint: switch to `rt$default` by hand.
+  Once a node exists, every sync follows its authored mode.
+- Errors **accumulate**: violating `minLength` _and_ `pattern` → two messages (a list).
+  A `rt$default` node collapses them to one message.
+
+```ts
+// rt$default mode: one sentence covers every failure of the field
+name: {
+  rt$label: 'Full name',
+  rt$errors: {rt$default: 'Enter a name between 2 and 60 characters'},
+},
+```
+
+## Placeholder DSL
+
+Templates are plain strings with `$[…]` tokens the renderer substitutes:
+
+- `$[label]`: node's `rt$label`, falling back to the raw field name.
+- `$[val]`: failed constraint's bound (`error.format.val`; e.g. `2`).
+- `$[path]`: dotted path to the field (`profile.email`).
+- `$[index]`: array element index, for `rt$items` failures.
+- Type-driven: on the i18n path `$[val]` renders by the bound's TYPE, no per-template syntax.
+  `isCurrency`-marked bound (`TF.Currency`) → renderer's `currency` option. Date-family bound → `Intl.DateTimeFormat`.
+- Unknown `$[…]` tokens left verbatim; `enrich --no-emit` flags them (enrich-text-unknown-placeholder).
+- Literal colon in prose (`ratio 3:1`) never touched.
+- `$[value]` (actual received value) out of scope for v1: `RunTypeError` carries no value.
+
+## Plural templates on count-bearing constraints
+
+- Count-bearing: `minLength`, `maxLength`, `min`, `max`, `lt`, `gt`.
+- Their leaf = plain string or **plural object** with CLDR cardinal category arms.
+- `TemplateLeaf = string | PluralTemplate`.
+- `PluralTemplate` = `{other: string}` + optional `zero`/`one`/`two`/`few`/`many` arms.
+
+```ts
+name: {
+  rt$label: 'Full name',
+  rt$errors: {
+    type: '$[label] must be text',                        // plain string, as before
+    minLength: {                                          // plural object
+      one: '$[label] needs at least $[val] character',
+      other: '$[label] needs at least $[val] characters',
+    },
+  },
+},
+```
+
+- `enrich` scaffolds the plural object (`minLength: {one: '', other: ''}`).
+  - Arms from the SOURCE locale's CLDR cardinal set (tsconfig `i18n.sourceLocale`, default `en`).
+  - Built-in table: en, es, zh, hi, ar, pt, ru, ja, de, fr, pl. Other locale → all six `zero one two few many other`.
+- **Fill the arms; never restructure the object.** Only `other` mandatory. Prune arms you don't use.
+- All other constraints (`type`, `pattern`, `allowedChars`, …) stay plain strings. `rt$label` always a plain string.
+- Plain string on a count-bearing constraint stays legal.
+- **Plural count = the VIOLATED BOUND** (`$[val]`: `minLength: 3` failure selects the arm for `3`).
+  NOT the received value's length.
+- Arm picked via `Intl.PluralRules(locale)`. `other` = backstop. Non-finite bound → `other` directly.
+- Plain `createFriendlyText` uses `en` rules (deterministic, matches default `sourceLocale`).

package/skills/runtypes-friendly-text/references/example.md

@@ -0,0 +1,80 @@
+# FriendlyText end-to-end example
+
+Type definition → filled friendly mirror → consumer.
+
+```ts
+// src/models/user.ts: the DEFINITION
+import type * as TF from '@mionjs/run-types/formats';
+
+export interface User {
+  name: TF.String<{minLength: 2; maxLength: 60}>;
+  age: TF.Number<{min: 0; max: 120}>;
+  isActive: boolean;
+  tags: string[];
+  profile: {
+    email: TF.Email;
+    score: TF.Number<{min: 0; max: 100}>;
+  };
+}
+```
+
+```ts
+// src/.mion/enriched/friendly/src/models/user.ts: the committed friendly mirror
+import type {User} from '../../../../../models/user';
+import type {FriendlyText} from '@mionjs/run-types';
+
+export const friendlyUser: FriendlyText<User> = {
+  rt$label: 'User account',
+  rt$errors: {type: '$[label] must be an object'},
+
+  name: {
+    rt$label: 'Full name',
+    rt$errors: {
+      type: '$[label] must be text',
+      minLength: '$[label] needs at least $[val] characters',
+      maxLength: '$[label] allows at most $[val] characters',
+    },
+  },
+  age: {
+    rt$label: 'Age',
+    rt$errors: {
+      type: '$[label] must be a number',
+      min: '$[label] must be at least $[val]',
+      max: '$[label] must be no more than $[val]',
+    },
+  },
+  isActive: {rt$label: 'Active?', rt$errors: {type: ''}},
+
+  tags: {
+    rt$label: 'Tags',
+    rt$errors: {type: ''},
+    rt$items: {rt$label: '', rt$errors: {type: 'each tag must be text'}}, // element node
+  },
+
+  profile: {
+    // nested object: recurse
+    rt$label: 'Profile',
+    rt$errors: {type: ''},
+    email: {
+      rt$label: 'Email',
+      rt$errors: {type: '', minLength: '', maxLength: '', pattern: 'Enter a valid email address'},
+    },
+    score: {rt$label: 'Score', rt$errors: {rt$default: 'Score must be between 0 and 100'}}, // rt$default mode
+  },
+};
+```
+
+```ts
+// src/services/userForm.ts: the CONSUMER
+import {createGetValidationErrorsFn, createFriendlyText} from '@mionjs/run-types';
+import {friendlyUser} from '../.mion/enriched/friendly/src/models/user';
+import type {User} from '../models/user';
+
+const getUserErrors = createGetValidationErrorsFn<User>();
+const friendly = createFriendlyText<User>(friendlyUser);
+
+const messages = friendly.errors(getUserErrors({name: 'A', age: 200, profile: {email: 'nope', score: 5}}));
+// name     → 'Full name needs at least 2 characters'
+// age      → 'Age must be no more than 120'
+// profile.email → 'Enter a valid email address'
+```

package/skills/runtypes-friendly-text/references/rendering.md

@@ -0,0 +1,77 @@
+# Rendering at runtime
+
+`createFriendlyText<T>(map)` for one language, `createFriendlyTextI18n` for locales.
+
+## `createFriendlyText<T>(map)`
+
+```ts
+// src/services/userForm.ts
+import {createGetValidationErrorsFn, createFriendlyText} from '@mionjs/run-types';
+import {friendlyUser} from '../.mion/enriched/friendly/src/models/user';
+import type {User} from '../models/user';
+
+const getUserErrors = createGetValidationErrorsFn<User>();
+const friendly = createFriendlyText<User>(friendlyUser);
+
+const badInput: unknown = {name: 'A', age: 200, profile: {email: 'nope'}};
+friendly.errors(getUserErrors(badInput));
+// → [{ path: 'profile.email', label: 'Email', message: 'Enter a valid email address' }, …]
+
+friendly.label('profile.email'); // → 'Email'  (falls back to the raw field name)
+```
+
+Returns `{ errors(errs), label(path) }`:
+
+- `errors(errs)`: groups `RunTypeError[]` by path, looks up the node,
+  interpolates the matching template per failed constraint.
+  - `rt$default` node → single message for the whole field.
+  - Returns `FriendlyMessage[]` (`{ path, label, message }`).
+- `label(path)`: friendly label for a dotted path or a raw path-segment array.
+
+## `createFriendlyTextI18n(source, options)`
+
+Same `FriendlyRenderer` interface as `createFriendlyText`.
+
+```ts
+// src/services/userForm.ts
+import {createFriendlyTextI18n, createGetValidationErrorsFn} from '@mionjs/run-types';
+import {friendlyUser} from '../.mion/enriched/friendly/src/models/user';
+import {es_friendlyUser} from '../.mion/enriched/i18n/es/src/models/user';
+import {pl_friendlyUser} from '../.mion/enriched/i18n/pl/src/models/user';
+import type {User} from '../models/user';
+
+const getUserErrors = createGetValidationErrorsFn<User>();
+const currentLocale = navigator.language;
+const badInput: unknown = {name: 'A', age: 200};
+
+const friendly = createFriendlyTextI18n(friendlyUser, {
+  locale: currentLocale, // string | {value: string}: a {value} ref (e.g. a Vue Ref)
+  translations: {es: es_friendlyUser, pl: pl_friendlyUser},
+  currency: 'EUR', // optional ISO 4217 code (string or {value} ref) for TF.Currency bounds
+  sourceLocale: 'en', // optional (default 'en'): plural rules when rendering from the SOURCE map
+});
+
+friendly.errors(getUserErrors(badInput)); // arm + template picked per the active locale
+```
+
+- `{value}` locale ref is re-read on EVERY render. Renderer itself is not reactivity-tracked:
+  call `errors()` per render / inside `computed()`.
+- Locale matching: `resolveLocale(locale, translations)`, naive BCP-47 truncation.
+  - Exact tag, then subtags dropped right-to-left (`pt-BR` → `pt`).
+  - Then any available tag sharing the base language (`zh-Hant` matches a `zh-Hans` file when nothing closer).
+  - Nothing shares the base language → `undefined` → renderer uses the source.
+- Fallback is per-leaf, never throws on a partial translation.
+  - Reserved `strict` option exists; runtime is always lenient.
+  - Blank (`''`) or missing translated leaf → source. `rt$label` and each `rt$errors` key independently.
+  - Node's own authored `rt$default` tried before falling cross-map.
+  - Plural leaf falls through as a WHOLE unit: never mixes a target arm with a source arm.
+- Type-driven `$[val]`: the error's format payload says what the bound IS.
+  - `isCurrency`-marked number bound (`TF.Currency<P>` = `Number<P & {isCurrency: true}>`):
+    pure-metadata param echoed onto every error the field produces.
+    Renders via `Intl.NumberFormat(locale, {style: 'currency', currency})` with the app-supplied `currency` option.
+  - `currency` omitted → plain localized number, never a guessed symbol.
+    WHICH currency a value is in = app DATA, not fixed in the type.
+  - Date-family bound → `Intl.DateTimeFormat(locale)`. Unparseable relative bound (`now-P1D`) stays verbatim.
+  - Everything else → `String(val)`. Unknown tokens stay verbatim.
+- `Intl` instances memoized: `PluralRules` per locale, bound formatters per locale + currency / style.
+- Plain `createFriendlyText` stays byte-stable: `String(val)` everywhere.

package/skills/runtypes-friendly-text/references/translations.md

@@ -0,0 +1,38 @@
+# Translations: per-locale `FriendlyText<T>` files
+
+Filling locale files under `<genDir>/enriched/i18n`.
+
+- Locale file = `FriendlyText<T>` map authored in another language.
+  The source map you authored IS the source language (tsconfig `i18n.sourceLocale`, default `en`).
+- File: `<i18nDir>/<locale>/<rel>.ts`, e.g. `src/.mion/enriched/i18n/pl/src/models/user.ts`.
+- Const: `<locale>_friendly<Name>` (`pt_BR_friendlyUser`), same `@rtType` / `@rtIds` markers as the source.
+- Layout, CLI (`mion enrich --i18n <locale|all>`, `--update`, `--prune`, `--no-emit`), enrich-i18n-\* findings,
+  tsconfig `i18n` block: `rt-enrich-types` skill.
+- Translation is optional per leaf: anything unfilled falls back to the source at render time.
+
+## Scaffold
+
+- Type's tree with every string leaf + plural arm as an `@todo` blank (`''`).
+- NEVER copies source text as if translated (the type has no strings).
+- Plural objects carry the TARGET locale's CLDR arm set.
+- Const references rename to their locale siblings (`home: pl_friendlyAddress`).
+
+## Filling a translation file
+
+- Translate ONLY blank (`''`) leaves. Never edit an already-filled leaf. Never copy the source text across.
+- Prune plural arms your language doesn't use. Arms are locale-owned: a pruned arm stays pruned across reconciles.
+  Only the mandatory `other` is ever re-inserted.
+- `rt$default`-mode node: exactly one string to translate, never descended.
+
+```ts
+// src/.mion/enriched/i18n/pl/src/models/user.ts: committed, filled by a translator/agent
+import type {User} from '../../../../../../models/user';
+import type {FriendlyText} from '@mionjs/run-types';
+
+/** @rtType User#9f3a @rtIds {…} */
+export const pl_friendlyUser: FriendlyText<User> = {
+  /* … */
+};
+```
+
+Rendering locale files: `createFriendlyTextI18n` → [rendering.md](rendering.md).