@pikku/skills 0.12.19 → 0.12.21

package/package.json

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

@@ -237,12 +237,12 @@ Banning is the one capability with a schema requirement, and it has its own
 small plugin:
 
 ```typescript
-import { ban } from '@pikku/better-auth'
+import { pikkuBan } from '@pikku/better-auth'
 
-betterAuth({ plugins: [ban()] })
+betterAuth({ plugins: [pikkuBan()] })
 ```
 
-`ban()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
+`pikkuBan()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
 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.
@@ -252,22 +252,28 @@ never needs to know about scopes or roles.
 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        |
+| Plugin                   | Plugin `id`        | Adds                                                                    | Use it when                                                   |
+| ------------------------ | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `pikkuBan()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
+| `pikkuActor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
+| `pikkuCredentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
+| `pikkuDelegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
+| `pikkuFabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+
+Every one carries a `pikku` prefix, because a `plugins: [...]` array mixes these
+with better-auth's own and a bare `actor()` next to `organization()` says
+nothing about where it came from. The unprefixed names — `ban`, `actor`,
+`credentialOAuth`, `delegatedAuth`, `fabric` — are still exported as deprecated
+aliases, so existing apps keep working.
 
 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`.
+by, so the two differ for every one of them.
 
-#### `credentialOAuth()` — link API credentials, not identities
+#### `pikkuCredentialOAuth()` — link API credentials, not identities
 
 ```typescript
-credentialOAuth({
+pikkuCredentialOAuth({
   config: [
     {
       providerId: 'github',
@@ -308,10 +314,10 @@ by construction. Tokens land in better-auth's `account` table, so
 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
+#### `pikkuDelegatedAuth()` — the upstream API is the identity provider
 
 ```typescript
-delegatedAuth({
+pikkuDelegatedAuth({
   authenticate: async ({ email, password, apiKey }) => upstream.login(...),
   storeCredential: (userId, identity) =>
     credentialService.set('acme', identity.credential, userId),
@@ -338,10 +344,10 @@ 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
+#### `pikkuFabric()` — control-plane operator sign-in
 
 ```typescript
-fabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
+pikkuFabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
 ```
 
 `POST /sign-in/fabric` verifies a short-lived RS256 token that the Fabric
@@ -468,14 +474,27 @@ someone" means **a particular kind of user** rather than one fixed admin.
 Register it explicitly — it is not automatic:
 
 ```typescript
-import { actor } from '@pikku/better-auth'
+import { pikkuActor } from '@pikku/better-auth'
 
-plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
+plugins: [pikkuActor({ 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 +535,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
@@ -570,7 +591,7 @@ await provisionPersonas(singletonServices, {
 ```
 
 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,
+`pikkuBan()` 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

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

@@ -129,8 +129,8 @@ a stage whose pages return 200 — the shell renders fine — while its first da
 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
+A Better Auth app has a second constraint: the plugins you enable (`pikkuBan()`,
+`pikkuActor()`, …) each declare columns, and `pikku db migrate` refuses to run while
 the applied schema is missing any of them. `pikku db generate` writes the
 migration that closes the gap.
 
@@ -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

@@ -1,7 +1,7 @@
 ---
 name: pikku-feature
 description: 'Drive create-a-feature work inside a Pikku project that already exists: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
-allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *)
+allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
 argument-hint: '<feature description>'
 ---
 
@@ -16,6 +16,7 @@ Use this skill as an execution checklist, not reference material.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+6. Report anything about pikku itself that cost you time, the moment it happens — see **Report what fought you**.
 
 End-to-end flow: **discover → state intent → branch → implement → verify → commit → hand to reviewer**.
 
@@ -41,7 +42,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
@@ -246,6 +247,106 @@ feature/<slug>` and surface the PR-create URL.
 
 Do not push without explicit confirmation. Do not merge.
 
+## Report what fought you
+
+When pikku itself is what cost you time, report it with `pikku fabric report`.
+Nothing is written to the repo; the finding goes to the linked fabric project
+and the terminal shows you exactly what was sent.
+
+**Report at the moment it happens**, not at the end from memory — a run that
+falls over never reaches its end. One finding per thing that fought you.
+
+### The ladder
+
+1. **Find the quicker workaround.** The user is paying for their feature, not
+   for pikku's health.
+2. **Investigate** only when there is no workaround, or when the user asks why
+   something is slow or wrong.
+3. **Report at the depth you already reached.** Never spend extra effort to
+   file; never throw away effort you already spent. If the investigation took
+   you to the mechanism, the finding says so — named file, named function, what
+   is actually happening, and what pikku should do instead.
+
+**Never fix pikku itself.** Not a patch in `node_modules`, not a linked
+checkout, not a branch in the framework repo. Many agents each patching pikku to
+unblock themselves is many divergent copies and a merge problem nobody signed up
+for. Work around it in the app, report it, and let the fix happen once.
+
+### What counts
+
+Anything that cost you time and would cost the next person the same. Most of
+these never produce an error: output that is quietly wrong, a generated type
+that disagrees with the runtime, a check that passes when it should not, a
+narrowing you had to write by hand because the framework should have written it.
+**Having to write code the framework should have written for you is a finding.**
+
+So is anything that only shows up in one place — invisible locally, fatal
+deployed, or the reverse. Say which, with `--surface`.
+
+Not a finding: a preference, a thing you would have designed differently, or
+baseline noise that was already failing before you started.
+
+### Two kinds
+
+- `--kind product` — pikku behaved wrongly. Fixing it is a change to the
+  framework.
+- `--kind harness` — a skill misled you: it told you to run something that does
+  not exist, described a flag that is spelled differently, or contradicted what
+  the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
+  section>"`. This is the most useful kind to file, because it is fixable
+  immediately — so file it even when the cost was small.
+
+### When there was no workaround
+
+Report it anyway with `--unresolved`, and put what you tried and how each
+attempt failed in `--tried`. That is what stops the next person walking the same
+dead ends. Tell the user what you did instead — abandoned it, shipped something
+degraded, or stopped.
+
+`--unresolved` means **no workaround was found**. It does not mean the
+workaround was unpleasant.
+
+### The command
+
+Send it as JSON on stdin. Most of a finding is prose, and prose carries
+apostrophes, quotes, backticks and newlines — each one a shell metacharacter
+before it is a character in your sentence. A stack trace passed to `--error`
+breaks the command at its first newline; a backtick in `--actual` runs whatever
+follows it. Quote the heredoc delimiter (`<<'EOF'`, never `<<EOF`) so the shell
+leaves the body alone.
+
+```bash
+pikku fabric report --stdin <<'EOF'
+{
+  "title": "<one-line title>",
+  "kind": "product",
+  "model": "<the model you are>",
+  "expected": "<what you expected pikku to do>",
+  "actual": "<what it did instead>",
+  "command": "<the command you ran>",
+  "workaround": "<what you did instead, inside the app>"
+}
+EOF
+```
+
+Add whichever of these you actually have: `error` (the error's message line,
+verbatim), `repro` (the shortest way to reach it again), `proposal` (what pikku
+should do), `area`, `surface` (`local`, `deployed` or `both`), `cost` (measured
+if you measured it — "98s vs 20s steady" ranks; "slow" does not), `run` (an id
+shared by every finding from this build), `deployTarget`.
+
+The same fields exist as flags — `--kind`, `--expected` and so on — for a
+finding short enough to type. Anything with a newline or a quote in it goes
+through `--stdin`.
+
+Versions, platform and package manager are read off the installed tree for you.
+Do not pass them and do not ask the user for them.
+
+Reporting never fails a build. A finding that cannot be sent — logged out, or
+fabric unreachable — is held on the machine and goes out with the next report
+that succeeds, so nothing you file is lost. If it says the finding was queued,
+carry on with the feature; do not try to fix it, and do not file it again.
+
 ## Hard constraints
 
 The skill's `allowed-tools` does **not** permit:
@@ -254,7 +355,8 @@ The skill's `allowed-tools` does **not** permit:
 - `yarn dbmigrate` (never run migrations against the real DB during planning)
 - `pikku deploy apply` (never deploy)
 - secret writes
-- network calls beyond what the implementation requires
+- network calls beyond what the implementation requires, except
+  `pikku fabric report`, which is explicitly permitted
 
 If the feature genuinely needs any of these, **stop and ask** with a clear
 explanation of why and what would change.

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`