@pikku/skills 0.12.15 → 0.12.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.15",
+  "version": "0.12.17",
   "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

@@ -137,21 +137,21 @@ resolves the caller's scopes through the registered `ScopeService` and checks th
 `admin:*` tree (`ADMIN_SCOPES` exports the ids so you never spell them as bare
 strings):
 
-| Gate                                                                 | Scope required           |
-| -------------------------------------------------------------------- | ------------------------ |
-| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate`      |
-| `credentialOAuth`'s `canLinkSingleton`                               | `admin:credentials:link` |
-| the console's user directory                                         | `admin:users:list`       |
-| create a user out of band                                            | `admin:users:create`     |
-| ban / unban                                                          | `admin:users:ban`        |
-| delete a user and their data                                         | `admin:users:remove`     |
-| revoke a user's sessions                                             | `admin:users:sessions`   |
-| set a user's password                                                | `admin:users:password`   |
-| read credential values and who holds them                            | `admin:credentials:read` |
+| Gate                                                                 | Scope required             |
+| -------------------------------------------------------------------- | -------------------------- |
+| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate`        |
+| `credentialOAuth`'s `canLinkSingleton`                               | `admin:credentials:link`   |
+| the console's user directory                                         | `admin:users:list`         |
+| create a user out of band                                            | `admin:users:create`       |
+| ban / unban                                                          | `admin:users:ban`          |
+| delete a user and their data                                         | `admin:users:remove`       |
+| revoke a user's sessions                                             | `admin:users:sessions`     |
+| set a user's password                                                | `admin:users:password`     |
+| read credential values and who holds them                            | `admin:credentials:read`   |
 | set and delete credentials                                           | `admin:credentials:manage` |
-| view declared scopes, roles, and who holds them                      | `admin:scopes:read`      |
-| create roles, change their scopes, grant them                        | `admin:scopes:manage`    |
-| read the audit trail                                                 | `admin:audit:read`       |
+| view declared scopes, roles, and who holds them                      | `admin:scopes:read`        |
+| create roles, change their scopes, grant them                        | `admin:scopes:manage`      |
+| read the audit trail                                                 | `admin:audit:read`         |
 
 Holding the bare `admin` scope satisfies all of them — a parent grant covers
 everything nested beneath it — so `admin` is the direct replacement for the old
@@ -247,6 +247,112 @@ create a session for a banned user, lapsing an expired ban as it goes. It makes
 no authorization decision — who may ban is decided by `admin:users:ban` — so it
 never needs to know about scopes or roles.
 
+### The plugins `@pikku/better-auth` ships
+
+Five, all imported from the package root and passed to `betterAuth({ plugins })`
+like any other. None is automatic — an app wires the ones it needs.
+
+| Plugin              | Plugin `id`        | Adds                                                                    | Use it when                                                   |
+| ------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `ban()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
+| `actor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
+| `credentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
+| `delegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
+| `fabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+
+The plugin's `id` is what better-auth stores; the **export name** is what the
+inspector reads off your `plugins` array and what generated metadata is keyed
+by, so the two differ for `ban` and `delegatedAuth`.
+
+#### `credentialOAuth()` — link API credentials, not identities
+
+```typescript
+credentialOAuth({
+  config: [
+    {
+      providerId: 'github',
+      type: 'wire',
+      clientId,
+      clientSecret,
+      authorizationUrl,
+      tokenUrl,
+      scopes: ['repo'],
+    },
+    { providerId: 'slack', type: 'singleton' /* … */ },
+  ],
+  scopeService,
+  logger,
+})
+```
+
+Wraps better-auth's `genericOAuth` to keep its token exchange and refresh, and
+replaces only the two identity-bound endpoints. `genericOAuth`'s own
+`/oauth2/link` models an identity **provider**: it demands a userinfo response
+and refuses to link when the provider's email differs from the user's. A
+credential is not an identity — most credential providers expose only
+`/authorize` and `/token` — so the account row is keyed on _whose_ credential it
+is (`accountId` = the linking user's id), making `(providerId, userId)` unique
+by construction. Tokens land in better-auth's `account` table, so
+`auth.api.getAccessToken()` refreshes them on read.
+
+`type` decides the blast radius:
+
+- **`wire`** — every user links their own, and the credential is read on
+  the wire that runs as them. Signed in is enough.
+- **`singleton`** — one token the whole app shares, owned by a reserved
+  `pikku-platform` user row created on demand. Rebinding it changes the
+  credential for _everyone_, so it is gated on `admin:credentials:link` (or the
+  `admin` root above it), and **fails closed** with no `ScopeService`. Override
+  the whole gate with `canLinkSingleton`.
+
+An undeclared `providerId` is a 404; an anonymous caller a 401; a refused
+singleton a 403 that leaves no platform user behind.
+
+#### `delegatedAuth()` — the upstream API is the identity provider
+
+```typescript
+delegatedAuth({
+  authenticate: async ({ email, password, apiKey }) => upstream.login(...),
+  storeCredential: (userId, identity) =>
+    credentialService.set('acme', identity.credential, userId),
+  defaultRole: 'member',
+  mapRole: (upstreamRole) => ROLE_MAP[upstreamRole],
+  scopeService,
+  logger,
+})
+```
+
+`POST /sign-in/delegated` forwards the credentials the user already has to
+`authenticate`. On success it JIT-provisions a real user row (email-keyed and
+`emailVerified` — the upstream just verified them), links it via an `account`
+row (`providerId: 'delegated'`, `accountId: externalId`), persists the upstream
+token **before** minting the session, and returns a normal session cookie.
+Passwords are never stored. Exactly one upstream per app: additional imported
+APIs are linked integrations (`credentialOAuth`), not extra login methods.
+
+A resolved role is granted through the `ScopeService` as a pikku role, so it
+lands in `pikku_user_role` rather than on a column. A role the app never
+defined is a provisioning gap, not a sign-in failure — the grant is dropped with
+a warning and the user still gets in.
+
+`storeCredential` failing, by contrast, **fails the sign-in**: every proxied
+call would be dead anyway.
+
+#### `fabric()` — control-plane operator sign-in
+
+```typescript
+fabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
+```
+
+`POST /sign-in/fabric` verifies a short-lived RS256 token that the Fabric
+control plane signed for an operator session, then signs them into a synthetic
+`fabric-<id>@fabric.internal` row holding the `admin` scope. Asymmetric on
+purpose: the app holds only the public key, so it can never forge an operator
+login, and the same `FABRIC_AUTH_PUBLIC_KEY` is distributed to every stage with
+no per-environment secret. A missing or empty key disables the endpoint, and a
+token whose `purpose` claim is not `fabric-admin` is rejected. Without a
+`ScopeService` the operator signs in holding nothing.
+
 ### 2. Production database adapter
 
 For real deployments swap `memoryAdapter` for the Kysely adapter backed by an injected DB. Better Auth owns its own tables (`user`, `session`, `account`, `verification`, plus plugin tables) — generate its schema with `npx @better-auth/cli generate` and apply it as a migration.
@@ -371,14 +477,35 @@ plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
 session cookie. `secret` may also be a (possibly async) function, so it can come
 off the secrets service instead of a captured value.
 
+**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
+`SCENARIO_ACTOR_SECRET` for the run, so local development needs no configuration
+at all. Everywhere else the endpoint refuses (`Actor sign-in is disabled outside
+\`pikku dev\``) — `pikku serve` clears the marker outright, so a secret that
+leaked into a production environment enables nothing and gets a warning naming
+itself instead.
+
+A stage that genuinely must run scenarios opts in on purpose, with
+`PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in`. Any other value is
+ignored and warned about, so the hatch cannot be opened by copying a `true` from
+the line above, and it is the only hatch — there is no build-time option, because
+an option compiled into the bundle cannot be audited from the environment it
+runs in.
+
+**Signing in and provisioning are separate powers.** An unknown address becomes
+an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
+in as the personas the deployment provisioned when it started and refuses
+everything else (`No actor account exists for that address`), so holding the
+secret on such a stage does not let anyone invent identities. Those rows are
+written by `provisionPersonas` from `@pikku/better-auth`, called in the server's
+own lifecycle, so provisioning needs no actor secret and works on a stage whose
+endpoint is shut.
+
 **`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
-persona.** `pikku persona sync` grants declared roles to actor accounts, so an
-`admin` persona is an actor holding real admin — anyone with the secret can take
-a session as one. Keep the endpoint **off outside development and sandbox
-deployments**: leave the secret unset on any stage that should not run scenarios,
-which is the supported switch (`Actor sign-in is not configured`), rather than
-conditionally registering the plugin. Do not treat "actors only" as a licence to
-enable it in production.
+persona.** Provisioning grants declared roles to actor accounts, so an
+`admin` persona is an actor holding real admin — anyone with the secret _and_ the
+opt-in can take a session as one. Do not treat "actors only" as a licence to open
+the hatch in production.
 
 Within that boundary, three properties bound the damage:
 
@@ -386,9 +513,9 @@ Within that boundary, three properties bound the damage:
   column; an email matching a row without it is refused with `User is not an
 actor`. So the secret cannot take over a **real user's** account — the blast
   radius is the actor accounts and whatever roles they were granted.
-- **Unknown emails are created**, flagged `actor: true`, so a scenario that
-  declares a new persona needs no seed step. Note the flip side: the secret
-  mints accounts, it does not merely use existing ones.
+- **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.
 
@@ -396,6 +523,65 @@ 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
 actors and `pikku-react` for `useDevActors()`.
 
+### Provisioning personas (`provisionPersonas`)
+
+Anywhere but `pikku dev`, the accounts have to exist before anyone signs in.
+The deployment creates them itself, from its own lifecycle:
+
+```ts
+import { provisionPersonas } from '@pikku/better-auth'
+import {
+  personaConfigs,
+  personaEnvironments,
+} from '#pikku/pikku-personas.gen.js'
+
+await provisionPersonas(singletonServices, {
+  personas: personaConfigs,
+  environments: personaEnvironments,
+})
+```
+
+It runs where the database already is, which is the point: the CLI has no
+connection to a deployed environment's database — it resolves one from the local
+project config — so a `pikku persona sync staging` that wrote rows would write
+them to whatever database the checkout happened to point at. `pikku persona sync
+<environment>` still exists, and reports who that environment will provision and
+why anyone was skipped, which is what you run _before_ the deploy.
+
+It creates missing accounts as `actor: true`, applies the roles each persona
+declares, and is additive — it never revokes. `PIKKU_ENV` (or an explicit
+`environment`) selects who is eligible, through the same rule that decides who
+may run there; an address already held by a real, non-actor user throws rather
+than being granted the persona's roles.
+
+**Deleting a persona does not delete its account.** Being additive leaves a hole:
+the account keeps every role it was granted, and the actor endpoint authenticates
+on the `actor` column alone without consulting the declaration — so an `admin`
+persona nobody declares any more is still a live way in wherever that endpoint is
+open. By default provisioning warns about those accounts and changes nothing.
+`orphans: 'ban'` shuts them:
+
+```ts
+await provisionPersonas(singletonServices, {
+  personas: personaConfigs,
+  environments: personaEnvironments,
+  orphans: 'ban',
+})
+```
+
+It writes the same `banned` column the console's ban RPC writes (so it needs the
+`ban()` plugin wired, and says so if it isn't), revokes the account's sessions,
+and leaves the row, its grants and its history intact — provisioning lifts the
+ban again by itself if the persona comes back. Deleting is deliberately not
+offered: an actor row is referenced by whatever those scenarios did while it
+existed.
+
+`report` is the default because a rolling deploy runs the new replica's
+provisioning while the old replica is still serving, so for the length of that
+overlap "no persona claims this" is a statement about the newer declaration only.
+A persona pinned to another environment counts as unclaimed here — it has no
+business holding a signable account in an environment its own rule refuses it.
+
 ---
 
 ## Secret Management

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

@@ -28,7 +28,10 @@ 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 `AGENTS.md` before your first change. Read `locale` 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.
 2. Make the smallest source change that satisfies the task. Keep generated files
    generated — never hand-edit `.pikku/`, `*.gen.*`, or the SDK.
 3. Validate with the narrowest relevant command, then `pikku all` when functions,
@@ -72,10 +75,68 @@ in one message. Then stop; do not interview the user.
   Neutral (fine for an internal tool, but say so out loud); a direction in words;
   a reference (brand guide, screenshots, a site whose register they want); or
   their own design agent/prompt, whose output you take as the direction.
+- **What language should the app speak, and what language does the team work
+  in?** Two answers, not one — see §1a, which is where they go. Ask only if the
+  request is not obviously English; a brief written in English about an English
+  product answers both.
 
 Skip anything you can decide yourself. If nobody answers, assume one app with
 paths, the roles implied by the request, Neutral, English — and say so.
 
+## 1a. Three languages, and you must not collapse them
+
+A brief saying "the entire UI is German" is about **one** of these. Getting this
+wrong has already shipped a project that can never add a second language, so
+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`                                     |
+| **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/*`
+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
+this phase, before there is any meta to be wrong:
+
+```json
+{ "locale": "de" }
+```
+
+It exists for the Pikku Console. Meta is the one part of a project the Console
+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.
+
+**Product UI is the message catalogue.** `messages/<locale>.json` via
+`pikku-i18n`, with `defaultLocale` deciding what a visitor opens in.
+`baseLocale` in `project.inlang/settings.json` **stays `en`**: it names the
+message source, the catalogue every other language is cloned from, so a project
+that repoints it has nothing to translate from and `--add-locale` is broken
+forever.
+
+A German medical portal, correctly:
+
+```jsonc
+// project.inlang/settings.json
+{ "baseLocale": "en", "locales": ["en", "de"] }
+// apps/app/src/i18n/active.json   (or: fabric i18n --default-locale de)
+{ "defaultLocale": "de" }
+// pikku.config.json
+{ "locale": "de" }
+```
+
+Record the two non-obvious answers as a `decisions/` note in §2 — neither is
+discoverable from code, and the next agent will otherwise re-derive them wrong.
+
 ---
 
 ## PHASE 1 — What the app is
@@ -325,7 +386,9 @@ or not the note says `built`.
    for working on an empty state the test data would hide). Because reset always
    arrives at a database it just wiped, **the seed file is plain `INSERT`s** — no
    `ON CONFLICT DO NOTHING`, no `INSERT OR IGNORE`. Nothing ever applies it
-   twice, so it never has to defend itself.
+   twice, so it never has to defend itself. It is also **local only** — no deploy
+   applies it, so anything the app would be broken without in production is
+   configuration and belongs in a migration, not here.
    Do this generously and do it now: an empty app demos badly and critiques
    badly, and you cannot judge a screen's hierarchy, overflow, or truncation
    against zero rows. Seed rows each persona sees differently — with an ownership

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

@@ -154,6 +154,13 @@ icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
 Adding a language means adding a locale file. If it means touching components,
 that is the finding.
 
+`baseLocale` stays `en` through all of this — it names the message source that
+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
+`pikku.config.json`. See `pikku-build-app` §1a.
+
 ### Emails — `pikku-emails`
 
 Templates in `emails/`, rendered and sent through the injected `email` service,

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

@@ -52,6 +52,15 @@ it — one kind of person, or several?** Everything else you decide yourself.
 Do not ask about design, deployment, or scope. This is the quick mode; the
 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
+`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
+`baseLocale` at `en`. `pikku-build-app` §1a has the three axes in full; getting
+them confused is how a project ends up unable to add a second language.
+
 ## 2. Personas — 60 seconds, not optional
 
 `packages/functions/src/personas.ts` ships with a `visitor`. Add one persona per
@@ -115,7 +124,9 @@ Then, in this order — it is the order codegen depends on:
 2. **Seed** — rows in `db/sqlite-dev-seed.sql`. There is no seed command:
    `bunx --bun pikku db reset` wipes, migrates and seeds in one go, and is the
    only thing that applies the file. It always starts from a wiped database, so
-   the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. **Be generous, and
+   the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. It is local only:
+   no deploy applies it, so anything the app cannot run without belongs in a
+   migration instead. **Be generous, and
    seed rows for both personas.** An empty app demos badly, and you cannot see a
    layout break against zero rows.
 3. **Functions** — one `pikkuFunc` per `*.function.ts`, `expose: true`. Pikku

package/skills/pikku-concepts/SKILL.md

@@ -138,7 +138,9 @@ Services can be destructured inline in the `func` signature (e.g. `async ({ logg
 
 ```typescript
 pikkuFunc({
-  // Identity and documentation
+  // Identity and documentation — prose, so it follows `locale` in
+  // pikku.config.json (default `en`). The identifier does not; see
+  // "What Language You Write In".
   title?: string,           // Human-readable name
   description?: string,     // What the function does
   version?: number,         // Contract version (see pikku-versioning)
@@ -321,6 +323,94 @@ src/
     └── pikku-bootstrap.gen.ts
 ```
 
+## What Language You Write In
+
+Three different things in a Pikku project have a human language, and they are
+**not** the same language. Collapsing them is the mistake this section exists to
+prevent, and it has already shipped in a real product — the failure is at the
+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`.                                                          |
+| **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`**.
+A German medical practice, an Arabic marketplace and a Japanese logistics tool
+all get `getOverview`, `AttentionStripe`, `case`, `event`.
+
+This is not linguistic preference, it is mechanics. Identifiers are the surface
+every other tool binds to: the generated `#pikku/*` clients, `pikku info` and
+`pikku meta`, the RPC map a scenario's `actor.invoke` is typed over, the
+generated SQL types, every skill and every agent that ever picks the project up.
+A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone who
+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
+
+```json
+{ "locale": "de" }
+```
+
+Meta is the one part of a project the **Pikku Console** renders back to a human.
+A team reviewing their own functions, features and scenario reports in the
+Console is reading meta and nothing else, so a team whose working language is
+German should be able to read their Console in German. That is the entire reason
+the field exists.
+
+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
+`description: 'Zeigt die Arbeitsliste'` on a function still called
+`getWorklist`.
+
+### Product UI language lives in the catalogue, and only there
+
+What the app says to its users is a translation concern, not a code concern. It
+belongs in `messages/<locale>.json`; `pikku-i18n` owns the details. The one rule
+worth repeating here: **`baseLocale` in `project.inlang/settings.json` stays
+`en`.** It names the message _source_ — the catalogue every other language is
+cloned from and translated against — so a project that sets it to anything else
+has no English catalogue to translate from and can never gain a second language
+without re-authoring every key.
+
+### The failure this comes from
+
+An agent was asked to build a doctor's portal for a German practice. The brief
+said "the entire UI is German, no English strings visible anywhere". The agent
+read one sentence about the product's users as an instruction about the
+codebase, and produced:
+
+- `project.inlang/settings.json` with `baseLocale: "de"` and `locales: ["de"]`,
+  no `en.json` at all — which silently broke `--add-locale` forever
+- RPC functions `getUebersicht` and `getPatientendetail`
+- React components `Zeitstrahl` and `AufmerksamkeitStreifen`
+- database tables `vorgang` and `ereignis`, with German columns
+
+Every one of those is wrong, and the brief was satisfied by none of them: a
+German UI needs German _messages_. What that project actually wanted was three
+settings, each on its own axis:
+
+```jsonc
+// project.inlang/settings.json — the message source stays English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a first-time visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "locale": "de" }
+```
+
+Identifiers stay English throughout. When a brief tells you the product speaks a
+language, it is telling you about axis three and nothing else.
+
 ## Environment Variables
 
 Never use `process.env` inside Pikku functions. Use the `variables` service (see `pikku-config`):

package/skills/pikku-fabric/SKILL.md

@@ -109,11 +109,25 @@ plain `INSERT`s** — no `INSERT OR IGNORE`, no `ON CONFLICT DO NOTHING`, no
 you find yourself reaching for an idempotent form, that's a sign the data wants
 to be a migration instead.
 
-This is **test data only**: enough rows that a fresh dev database isn't an empty
-app. It never reaches staging or production — reset refuses `NODE_ENV=production`
-and refuses a database outside the runtime directory. Anything a real environment
-needs — accounts, role grants — is provisioning, not seeding, and belongs in
-`pikku persona sync` or a migration.
+This is **local dev data only**: enough rows that a fresh dev database isn't an
+empty app. Nothing else ever runs it. A deployed stage applies `db/<engine>/*.sql`
+and stops there — reset refuses `NODE_ENV=production` and refuses a database
+outside the runtime directory, and no deploy step reaches for the seed file.
+
+So the test is not "is this row realistic?", it is **"would the app be broken
+without it in production?"** If yes, it is configuration and belongs in a
+migration, however much it looks like sample data. A venue and its rooms, a
+product catalogue, a tenant, a country list, the organization the whole
+deployment hangs off — all configuration. Accounts and role grants are
+provisioning: `provisionPersonas` at deployment, or a migration. What is left
+over is the seed's job — the bookings, orders and messages a demo needs and a real
+environment starts without.
+
+Get this wrong and it hides: the app is perfect locally, where reset has just
+run, and every deployed environment comes up with empty tables. The signature is
+a stage whose pages return 200 — the shell renders fine — while its first data
+read throws `no result` or a foreign-key violation on a row the seed was
+silently supplying.
 
 A Better Auth app has a second constraint: the plugins you enable (`ban()`,
 `actor()`, …) each declare columns, and `pikku db migrate` refuses to run while
@@ -397,6 +411,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.
 
 ## Converting an existing app to Fabric format
 
@@ -412,7 +427,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`.
+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.
 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,6 +41,13 @@ 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
+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
+project, and what the app says to its users is the message catalogue. See
+`pikku-concepts` → _What Language You Write In_.
+
 ## Stage 2 — State intent in plain English (BEFORE writing code)
 
 Before touching any files, give the user one paragraph stating exactly what