@pikku/skills 0.12.18 → 0.12.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.18",
+  "version": "0.12.20",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-better-auth/SKILL.md

@@ -474,8 +474,21 @@ plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
 ```
 
 `POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
-session cookie. `secret` may also be a (possibly async) function, so it can come
-off the secrets service instead of a captured value.
+session cookie. The plugin's `secret` is the **root**, and it may be a (possibly
+async) function so it can come off the secrets service instead of a captured
+value.
+
+**What a caller presents is not the root.** It is
+`deriveActorSecret(root, email)` from `@pikku/core/services` — HKDF-expanded
+HMAC-SHA256 over the lowercased address. The endpoint re-derives the expected
+value for the address being signed in as and compares, so a credential minted
+for one persona is refused for every other, and the root itself is never a valid
+credential. A root under 32 characters refuses the endpoint outright rather than
+deriving weak credentials from it (the server log names the problem; the client
+is not told which). Callers rarely derive by hand — `pikku dev` mints one per
+persona into `VITE_DEV_ACTOR_SECRETS` for the browser switcher, `pikku persona
+secret <id>` mints them for a run, and the two `PersonaSignIn` implementations
+derive on the fly.
 
 **Which command is running decides whether it works, not whether a secret is
 set.** `pikku dev` sets `PIKKU_DEV_ACTOR_SIGN_IN` and mints an ephemeral
@@ -516,8 +529,10 @@ actor`. So the secret cannot take over a **real user's** account — the blast
 - **Unknown emails are created only under `pikku dev`**, flagged `actor: true`,
   so a local scenario declaring a new persona needs no seed step. Anywhere else
   the account has to have been provisioned at boot first.
-- **The comparison is constant-time and length-hiding**, so a wrong secret leaks
-  neither the length nor a prefix of the right one.
+- **A credential is bound to one address**, so a leaked one is one synthetic
+  account rather than the whole actor population; only the root is worth the
+  paragraph above. The comparison is constant-time and length-hiding, so a wrong
+  credential leaks neither the length nor a prefix of the right one.
 
 This is the endpoint `pikku scenario` signs its actors in through, and the one
 the frontend dev switcher posts to — see `pikku-scenario` for declaring the

package/skills/pikku-build-app/SKILL.md

@@ -28,7 +28,7 @@ project shaped so `pikku fabric init` later adopts it with zero rework.
 ## Agent Operating Procedure
 
 1. Discover before editing. Run `pikku info functions --verbose --silent` and
-   read `AGENTS.md` before your first change. Read `locale` in
+   read `AGENTS.md` before your first change. Read `metaLocale` in
    `pikku.config.json` too: it is the language every `description`, `title` and
    step `template` you write must be in (§1a). Identifiers stay English whatever
    it says.
@@ -92,21 +92,21 @@ settle all three explicitly before you write code.
 | Axis            | What it covers                                                                                                                       | Where it goes                                                                     |
 | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
 | **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                                    | Nowhere — **always English**, no setting, not negotiable                          |
-| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions        | `locale` in `pikku.config.json`, default `en`                                     |
+| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions        | `metaLocale` in `pikku.config.json`, default `en`                                     |
 | **Product UI**  | Every string the app shows a user                                                                                                    | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
 
 **Identifiers are English.** The product's market does not change this and
-neither does `locale`. Identifiers are the surface the generated `#pikku/*`
+neither does `metaLocale`. Identifiers are the surface the generated `#pikku/*`
 clients, `pikku info`, the typed RPC map and the Kysely types all bind to, and
 unlike a string an identifier cannot be translated later — renaming one is a
 migration. A German practice management tool gets `getWorklist`, `case`,
 `event`, not `getUebersicht`, `vorgang`, `ereignis`.
 
-**Meta follows `locale`.** Write the team's answer into `pikku.config.json` in
+**Meta follows `metaLocale`.** Write the team's answer into `pikku.config.json` in
 this phase, before there is any meta to be wrong:
 
 ```json
-{ "locale": "de" }
+{ "metaLocale": "de" }
 ```
 
 It exists for the Pikku Console. Meta is the one part of a project the Console
@@ -114,7 +114,7 @@ renders back to a human, so a team working in German reads their own functions,
 features and scenario reports in German. Default `en` and do not ask when the
 project is obviously English. **On every later run, read this field first and
 author descriptions, titles and step templates in it** — a project whose
-`locale` you ignored reports half in one language and half in another.
+`metaLocale` you ignored reports half in one language and half in another.
 
 **Product UI is the message catalogue.** `messages/<locale>.json` via
 `pikku-i18n`, with `defaultLocale` deciding what a visitor opens in.
@@ -131,7 +131,7 @@ A German medical portal, correctly:
 // apps/app/src/i18n/active.json   (or: fabric i18n --default-locale de)
 { "defaultLocale": "de" }
 // pikku.config.json
-{ "locale": "de" }
+{ "metaLocale": "de" }
 ```
 
 Record the two non-obvious answers as a `decisions/` note in §2 — neither is
@@ -464,8 +464,16 @@ built-in module: node:sqlite`.
 
 Open it, sign up, and click through what you built. **HTTP 200 is not evidence.**
 The pages are client-rendered: the server returns 200 with an empty shell, so a
-page whose component throws still looks fine to `curl`. Open it in a browser, or
-drive it headlessly and assert on the text that actually rendered.
+page whose component throws still looks fine to `curl`.
+
+That click-through is a smoke check, and it is the only thing it is. **Do not
+hand-drive a browser tool in place of a test.** Steering Playwright yourself
+proves a page rendered once, on your machine, in an order only you remember —
+nothing about it re-runs, so the next agent inherits a claim rather than a test,
+and a regression lands silently. When a journey is worth driving through the UI,
+it is worth writing as a browser step on §7's scenario and running
+`pikku scenario run local --spawn --run browser`: same clicks, same assertions,
+in the repo, green or red on every future run.
 
 ## 7. Prove it — scenarios
 

package/skills/pikku-build-platform/SKILL.md

@@ -158,7 +158,7 @@ that is the finding.
 every added locale is cloned from, so three locales is `locales: ["en", …]` and
 never a repointed base. Shipping locales is also not a reason for anything in
 the code to stop being English: identifiers are English in every project, and
-the language of `description`/`title`/`template` is `locale` in
+the language of `description`/`title`/`template` is `metaLocale` in
 `pikku.config.json`. See `pikku-build-app` §1a.
 
 ### Emails — `pikku-emails`

package/skills/pikku-build-quick/SKILL.md

@@ -54,7 +54,7 @@ defaults are the point.
 
 Do not ask about language either — take the defaults and note them in §6.
 Identifiers are English in every project, whatever the product's market;
-`locale` in `pikku.config.json` (the language of `description`/`title`/step
+`metaLocale` in `pikku.config.json` (the language of `description`/`title`/step
 `template`, which the Console renders) stays `en` unless the user already told
 you otherwise. If the request says the app's UI is not English, that is the
 message catalogue only: add the locale and set `defaultLocale`, and leave
@@ -178,8 +178,11 @@ exactly like an app bug, so if every request fails, check both came up.
 
 Sign up, click every screen. **HTTP 200 is not evidence:** pages are
 client-rendered, so the server returns 200 with an empty shell and a page whose
-component throws still looks fine to `curl`. Open a browser, or drive it
-headlessly and assert on rendered text.
+component throws still looks fine to `curl`.
+
+Looking is for the layout — the part only eyes catch. Assertions belong in the
+smoke scenario, not in a browser session you steered by hand: that session proves
+a screen rendered once, here, and nothing about it re-runs.
 
 **Screenshot at 390px too.** A layout that is fine at 1440 routinely breaks on a
 phone — an overflowing table, a row of buttons wrapped into a pile, a modal

package/skills/pikku-concepts/SKILL.md

@@ -138,7 +138,7 @@ Services can be destructured inline in the `func` signature (e.g. `async ({ logg
 
 ```typescript
 pikkuFunc({
-  // Identity and documentation — prose, so it follows `locale` in
+  // Identity and documentation — prose, so it follows `metaLocale` in
   // pikku.config.json (default `en`). The identifier does not; see
   // "What Language You Write In".
   title?: string,           // Human-readable name
@@ -333,12 +333,12 @@ bottom.
 | Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
-| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `locale` in `pikku.config.json`. Defaults to `en`.                                                          |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                          |
 | **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
 
 ### Identifiers are English, and nothing changes that
 
-Not the product's market, not the team's working language, and **not `locale`**.
+Not the product's market, not the team's working language, and **not `metaLocale`**.
 A German medical practice, an Arabic marketplace and a Japanese logistics tool
 all get `getOverview`, `AttentionStripe`, `case`, `event`.
 
@@ -350,10 +350,10 @@ A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone wh
 did not name it, and unlike a string it cannot be translated later — renaming an
 identifier is a migration, not an edit.
 
-### Meta follows `locale`, and that is what the field is for
+### Meta follows `metaLocale`, and that is what the field is for
 
 ```json
-{ "locale": "de" }
+{ "metaLocale": "de" }
 ```
 
 Meta is the one part of a project the **Pikku Console** renders back to a human.
@@ -366,7 +366,7 @@ Read it before you author meta, and write descriptions, titles and templates in
 it. Absent, it is `en`. It is a BCP-47 tag (`en`, `de`, `pt-BR` — a hyphen, not
 an underscore), and the CLI rejects anything else by name.
 
-`locale` is **not** licence to rename anything. `locale: "de"` buys a German
+`metaLocale` is **not** licence to rename anything. `metaLocale: "de"` buys a German
 `description: 'Zeigt die Arbeitsliste'` on a function still called
 `getWorklist`.
 
@@ -405,7 +405,7 @@ settings, each on its own axis:
 { "defaultLocale": "de" }
 
 // pikku.config.json — the language the team reads their Console in
-{ "locale": "de" }
+{ "metaLocale": "de" }
 ```
 
 Identifiers stay English throughout. When a brief tells you the product speaks a

package/skills/pikku-concepts/references/concept-mapping.md

@@ -449,7 +449,7 @@ src/
 
 // Use tags for cross-cutting concerns:
 wireHTTP({ route: '/todos', func: listTodos, tags: ['todos', 'public'] })
-addMiddleware('todos', [loggingMiddleware])  // Applies to all 'todos'-tagged functions
+addTagMiddleware('todos', [loggingMiddleware])  // Applies to all 'todos'-tagged functions
 ```
 
 ---

package/skills/pikku-fabric/SKILL.md

@@ -268,8 +268,12 @@ bun run dev
 Then open the app, sign up as a real user, and click through what you built.
 **HTTP 200 is not evidence.** These are client-rendered pages: the server returns
 200 with an empty shell, so a page whose component throws still looks fine to
-curl. Either open it in a browser or drive it headlessly and assert on rendered
-text.
+curl.
+
+That pass is a smoke check. Anything you would otherwise verify by hand-driving a
+browser tool belongs in a scenario's browser step, run with
+`pikku scenario run local --spawn --run browser` — a browser session you steered
+yourself proves nothing that re-runs.
 
 Secrets come from `process.env`, which the CLI populates from a `.env` in the
 working directory. `BETTER_AUTH_SECRET` is required — without it the first
@@ -416,7 +420,7 @@ These apply in every Fabric app:
 - **No hand-editing `.pikku/db/schema.gen.ts`** — write a migration and re-run `pikku db migrate`.
 - **One runtime unit per file** — never define multiple functions/workflows in a single source file.
 - **Workflow steps don't need manual wiring** — `pikkuSessionlessFunc` step functions in `*.steps.ts` files are auto-discovered by codegen.
-- **Identifiers are English** — functions, components, types, files, database tables and columns, in every app whatever market it serves. The team's language is `locale` in `pikku.config.json` and reaches `description`/`title`/`template` only; the app's language is the message catalogue, where `baseLocale` stays `en` and `defaultLocale` decides what a visitor opens in. `pikku fabric validate` warns (`app-base-locale-not-english-<app>`) when an app repoints its base.
+- **Identifiers are English** — functions, components, types, files, database tables and columns, in every app whatever market it serves. The team's language is `metaLocale` in `pikku.config.json` and reaches `description`/`title`/`template` only; the app's language is the message catalogue, where `baseLocale` stays `en` and `defaultLocale` decides what a visitor opens in. `pikku fabric validate` warns (`app-base-locale-not-english-<app>`) when an app repoints its base.
 
 ## Converting an existing app to Fabric format
 
@@ -432,7 +436,7 @@ Fix every `error` and `warn` in the output before continuing. Then:
 2. **Replace route handlers with pikkuFuncs**: extract business logic into `pikkuFunc`/`pikkuSessionlessFunc`, add `wireHTTP` or `expose: true` for transport.
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
 4. **Replace `process.env` calls**: plain config becomes `defineVariable` + `variables.get()`, anything sensitive becomes `defineSecret` + `secrets.getSecret()`.
-5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles` — plus `locale` if the team does not work in English, which is the language every `description`, `title` and step `template` is then authored in.
+5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles` — plus `metaLocale` if the team does not work in English, which is the language every `description`, `title` and step `template` is then authored in.
 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.

package/skills/pikku-feature/SKILL.md

@@ -41,7 +41,7 @@ schemas (`yarn pikku meta functions get <id>`) or workflow steps
 **Capability rule:** do not introduce new wires of a type whose
 `capabilities.<type>` is `false` unless the user explicitly asked for it.
 
-**Language rule:** read `locale` in `pikku.config.json` (default `en`). It is
+**Language rule:** read `metaLocale` in `pikku.config.json` (default `en`). It is
 the language of every `description`, `title` and step `template` you author —
 the meta the Pikku Console renders back to the team. It renames nothing:
 functions, components, types, files, tables and columns are English in every

package/skills/pikku-i18n/SKILL.md

@@ -25,7 +25,7 @@ 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 | `locale` in `pikku.config.json`, default `en`                   |
+| **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.
@@ -57,7 +57,7 @@ So a German medical portal is **three** settings, not one:
 { "defaultLocale": "de" }
 
 // pikku.config.json — the language the team reads their Console in
-{ "locale": "de" }
+{ "metaLocale": "de" }
 ```
 
 In the Fabric template both of the first two have a command, so you rarely edit

package/skills/pikku-react/SKILL.md

@@ -240,11 +240,11 @@ their own sandbox.
 import { useDevActors } from '@pikku/react'
 
 const { actors, signInAs, pendingEmail, isPending, error } = useDevActors({
-  // Gate both reads on the bundler's dev flag so the secret cannot reach a
+  // Gate both reads on the bundler's dev flag so no credential can reach a
   // production bundle. The sandbox dev server bakes them from your personas.
   actors: import.meta.env.DEV ? import.meta.env.VITE_DEV_ACTORS : undefined,
-  secret: import.meta.env.DEV
-    ? import.meta.env.VITE_SCENARIO_ACTOR_SECRET
+  secrets: import.meta.env.DEV
+    ? import.meta.env.VITE_DEV_ACTOR_SECRETS
     : undefined,
   apiUrl: apiUrl(),
   onSignedIn: () => navigate({ to: '/' }),
@@ -255,8 +255,11 @@ const { actors, signInAs, pendingEmail, isPending, error } = useDevActors({
   `<DevActorSwitcher />` from `@pikku/mantine/dev` — a separate entry point from
   `@pikku/mantine/core`, whose contract is "drop-in alias for `@mantine/core`"
   and so must not export components Mantine has no counterpart for.
-- **`actors` is empty unless the host supplied both a list and a secret**, so a
-  production build renders nothing without you testing for it.
+- **`secrets` is `{ address: credential }`, not one shared value** — a
+  credential opens the one persona it was minted for (see
+  **pikku-better-auth**). `actors` is empty unless the host supplied both a list
+  and the credentials for it, and an actor with no credential is not offered, so
+  a production build renders nothing without you testing for it.
 - **It takes `onSignedIn` rather than a router**, and takes the env values rather
   than reading them, because how env is spelled is a bundler fact
   (`import.meta.env.VITE_*` vs `process.env.NEXT_PUBLIC_*`).
@@ -268,6 +271,37 @@ Do not hand-write the `devActors()` / `signInAsActor()` pair per app; that
 copy-paste, including the `import.meta.env.DEV` gate, is exactly what this
 replaced.
 
+### Linking from a Mantine element: `renderRoot`, not `component`
+
+Handing TanStack's `Link` to a Mantine element as `component={Link}` compiles,
+renders, and navigates — and silently unties the type. Mantine's polymorphic
+`component` prop widens the router generic to `AnyRouter`, so `to` and
+`params` stop being checked against your actual routes. Renaming a route then
+breaks the running app instead of the build, which is the one thing the typed
+router exists to prevent.
+
+Wrap the typed `Link` once and reach it through `renderRoot`, which passes the
+props through without re-typing the element:
+
+```tsx
+// components/links.tsx — one wrapper the whole app links through
+import { Link } from '@tanstack/react-router'
+
+export const AssessmentLink = (props: { assessmentId: string; children: React.ReactNode }) => (
+  <Link to="/assessments/$assessmentId" params={{ assessmentId: props.assessmentId }}>
+    {props.children}
+  </Link>
+)
+```
+
+```tsx
+<Button renderRoot={(p) => <AssessmentLink assessmentId={id} {...p} />}>
+  Open
+</Button>
+```
+
+The wrapper is where `to` and `params` are checked, and it is checked once.
+
 ## What NOT to do
 
 - Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`

package/skills/pikku-scenario/SKILL.md

@@ -213,14 +213,14 @@ The **feature is the run unit**: `--flows` on a scenario whose every feature ent
 
 A scenario records what someone was **trying to do**, never the keystrokes they used to do it. This is the one decision that determines whether a suite survives its first redesign, and it applies to every step name you write.
 
-| Action ladder — wrong               | Intent ladder — right                               |
-| ----------------------------------- | --------------------------------------------------- |
-| `Given opens /shop`                 | `Given the shopper is browsing the shop`            |
-| `When clicks the category filter`   | `When the shopper buys the £5 strawberry milkshake` |
-| `And clicks "Drinks"`               | `Then it is in their basket`                        |
-| `And clicks the first product card` |                                                     |
-| `And clicks Add to basket`          |                                                     |
-| `Then sees "1 item"`                |                                                     |
+| Action ladder — wrong               | Intent ladder — right                           |
+| ----------------------------------- | ----------------------------------------------- |
+| `Given opens /shop`                 | `Given shopper is browsing the shop`            |
+| `When clicks the category filter`   | `When shopper buys the £5 strawberry milkshake` |
+| `And clicks "Drinks"`               | `Then it is in their basket`                    |
+| `And clicks the first product card` |                                                 |
+| `And clicks Add to basket`          |                                                 |
+| `Then sees "1 item"`                |                                                 |
 
 Three things go wrong with the left-hand column, and all three are expensive:
 
@@ -313,7 +313,7 @@ await scenario.when(
   { name: '£5 strawberry milkshake' },
   { actor: actors.shopper }
 )
-// reporter renders: When the shopper buys the £5 strawberry milkshake  ✓  1.2s
+// reporter renders: When shopper buys the £5 strawberry milkshake  ✓  1.2s
 ```
 
 **Every intent step begins by arriving.** `ensureOnShop` is not defensive noise — it is what lets a scenario start at any step, run alone, and be reordered without touching it. It checks first and navigates only if needed, so a scenario already on the shop pays nothing. This is about the _browser's_ starting position, not the database: there is still no state reset (see above), and you still scope what you create.
@@ -367,7 +367,7 @@ string the generated step map is keyed by — the file name, and every helper in
 are English in every project regardless of who the product is for or what
 language the team speaks. There is no setting that changes this.
 
-**Prose follows `locale` in `pikku.config.json`** (default `en`). That is a
+**Prose follows `metaLocale` in `pikku.config.json`** (default `en`). That is a
 step's `description` and `template`, a feature's `name` and `description`, a
 scenario's `title`, and the positional step names passed to
 `scenario.given/when/then`. Read the field before you write any of them.
@@ -378,7 +378,7 @@ language. The report is the deliverable, and it is read by the team; the
 identifier is an API, and it is read by the toolchain.
 
 ```typescript
-// pikku.config.json: { "locale": "de" }
+// pikku.config.json: { "metaLocale": "de" }
 export const buysAnApple = pikkuScenarioStep<{ qty: number }, { orderId: string }>({
   name: 'buysAnApple',          // identifier — English, always
   description: 'kauft einen Apfel',  // prose — follows locale
@@ -392,19 +392,19 @@ export const buysAnApple = pikkuScenarioStep<{ qty: number }, { orderId: string
 Note what does **not** change: `placeOrder` is still `placeOrder`, and the file
 is still `apple.scenario.ts`.
 
-A product with a non-English UI is not on its own a reason to set `locale` — that
+A product with a non-English UI is not on its own a reason to set `metaLocale` — that
 is the app's language, not the team's. Ask, or leave it `en`.
 
-**Where a non-`en` `locale` still shows English, today.** The reporter composes a
+**Where a non-`en` `metaLocale` still shows English, today.** The reporter composes a
 sentence as `<Keyword> the <actor> <template>` (`composeStepProse`), and both the
 keyword and the article `the` are English literals. The Console translates the
 Given/When/Then keywords into its own UI language; the CLI reporter does not, and
-nothing translates `the`. So `locale: "de"` gives you German step prose inside an
+nothing translates `the`. So `metaLocale: "de"` gives you German step prose inside an
 English frame — `Given the shopper kauft 1 Äpfel`. Write templates that read
 acceptably in that frame rather than trying to defeat it. A second gap: where a
 function or scenario declares no `title`, the Console falls back to splitting the
 **identifier** into an English-looking label (`toEnglishName`), so under a
-non-`en` `locale` meta is worth authoring rather than leaving to the fallback.
+non-`en` `metaLocale` meta is worth authoring rather than leaving to the fallback.
 
 ### `then` bindings are witnesses, not alternatives
 
@@ -489,7 +489,7 @@ await scenario.given(
   { qty: 1 },
   { actor: actors.shopper }
 )
-// reporter renders: Given the shopper buys 1 apples   ✓  412ms
+// reporter renders: Given shopper buys 1 apples   ✓  412ms
 ```
 
 Rules that bite:
@@ -606,7 +606,7 @@ await page.getByRole('button', { name: t('jobs_apply_submit'), exact: true }).cl
 
 - Type off `messages/<baseLocale>.json`, **not** the generated Paraglide output — `i18n/paraglide/` is build output, so typing against it makes the tests unbuildable until the app has been built. The JSON is the tracked source.
 - Fall back to the base locale for a key a locale has not translated. That is what Paraglide does at run time, so a helper that throws instead would disagree with the screen the test is looking at.
-- This is not only about locators. A copy literal passed to a **project helper** (`pick('Where would you like to work?', …)`) reaches the DOM the same way, and so does a pane name quoted back in a failure message. `pikku fabric validate` scans every string in a `*.steps.ts` / `*.scenario.ts` against the base catalogue and errors on any verbatim match, wherever it sits.
+- This is not only about locators. A copy literal passed to a **project helper** (`pick('Where would you like to work?', …)`) reaches the DOM the same way, and so does a pane name quoted back in a failure message. `pikku fabric validate` scans every string in a `*.steps.ts` / `*.scenario.ts` against the base catalogue and errors on any verbatim match, wherever it sits — except comments, and the `name` / `description` / `template` declared directly on a `pikkuFeature`, `pikkuScenario` or `pikkuScenarioStep`, which are Console meta written in the project's `locale` rather than app copy.
 - A regex locator (`{ name: /^Next$/i }`) hides the literal but not the problem. `{ name: t('key'), exact: true }` is both stricter and locale-correct.
 - Strings the catalogue does not own — a test id, a fixture filename, a seeded value — stay literal. The catalogue is the test for whether something is copy.
 
@@ -709,11 +709,12 @@ frontend gets a one-click "Sign in as …" switcher over the **same** list, and
 app can be reviewed as each kind of user without anyone knowing a seed password.
 
 The sandbox dev server bakes both halves into the frontend from the declared
-personas: `VITE_DEV_ACTORS` (the JSON actor list) and
-`VITE_SCENARIO_ACTOR_SECRET`. Neither is set in a production build, so the
-control renders nothing there — but gate the reads on your bundler's dev flag
-anyway (`import.meta.env.DEV ? … : undefined`) so the secret never reaches a
-production bundle in the first place.
+personas: `VITE_DEV_ACTORS` (the JSON actor list) and `VITE_DEV_ACTOR_SECRETS`
+(`{ email: credential }`, one per persona — `SCENARIO_ACTOR_SECRET` itself never
+goes in a bundle; see **pikku-better-auth**). Neither var is set in a production
+build, so the control renders nothing there — but gate the reads on your
+bundler's dev flag anyway (`import.meta.env.DEV ? … : undefined`) so no
+credential reaches a production bundle in the first place.
 
 Do not hand-roll the switcher: `useDevActors()` (`pikku-react`, a separate install) is the logic and
 `<DevActorSwitcher />` from `@pikku/mantine/dev` is a ready rendering of it.
@@ -833,7 +834,7 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 | Assuming a clean database                           | There is no state reset — it may be a staging server. Scope what you create.                                                |
 | `sleep()` before asserting                          | Use `expectEventually`.                                                                                                     |
 | A step named `clicksAddToBasket` / `opensThePage`   | That is an action, not an intent. Name the step for what the actor wanted; put the clicking in a utility.                   |
-| A step named `kauftEinenApfel` / a `vorgang` table   | Identifiers are English in every project. The German belongs in `description` / `template`, and only when `pikku.config.json` sets `locale`.  |
+| A step named `kauftEinenApfel` / a `vorgang` table   | Identifiers are English in every project. The German belongs in `description` / `template`, and only when `pikku.config.json` sets `metaLocale`.  |
 | A browser step that assumes it is already on a page | It can then only run mid-flow. Arrive first — check the URL, navigate if needed.                                            |
 | `getByLabel('Full Name')` in a translated app        | Passes only in the base locale, and a copy edit breaks it as an unexplained timeout. Locate by message key.                 |
 | A `browser` binding guarding `if (!browser)`        | The binding guarantees it. The guard hides the real error, which is a missing actor (`PKU677`).                             |