@pikku/skills 0.12.43 → 0.12.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.43",
+  "version": "0.12.46",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

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

@@ -500,10 +500,9 @@ 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.
+is not told which). Callers rarely derive by hand — `pikku persona secret <id>`
+mints them for a run, and the two `PersonaSignIn` implementations derive on the
+fly. The browser switcher holds none: it signs in through `/sign-in/persona`.
 
 **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
@@ -559,9 +558,11 @@ actor`. So the secret cannot take over a **real user's** account — the blast
   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
-actors and `pikku-react` for `useDevActors()`.
+This is the endpoint `pikku scenario` signs its actors in through. The frontend
+switcher does not use it: it lists from `/sign-in/personas` and posts a persona
+id to `/sign-in/persona`, both served by
+`pikkuActor({ personaSignIn: { personas, featureFlags } })` with no credential — see
+`pikku-scenario` for the setup and `pikku-react` for `useDevActors()`.
 
 ### Provisioning personas
 

package/skills/pikku-blueprint-to-fabric/SKILL.md

@@ -18,7 +18,7 @@ Use this skill as an execution checklist, not reference material.
 5. **Verify with `pikku fabric validate --json`, then codegen and `tsc`** after every slice (Stage 8 has the exact commands). Never batch a whole app and verify at the end.
 6. **Write the parity report as you go**, not at the end — it is the deliverable that proves the rebuild is complete.
 
-This skill is the **translation layer** only. For how Fabric itself works (SQLite/libSQL, `fabric.config.json`, deploy provider, project layout) read **pikku-fabric**. For everything else, delegate to the sibling skill named at each step.
+This skill is the **translation layer** only. For how Fabric itself works (SQLite/libSQL, project linking, deploy provider, project layout) read **pikku-fabric**. For everything else, delegate to the sibling skill named at each step.
 
 ## The one idea
 
@@ -47,7 +47,7 @@ Then read, in this order — **whole files, once**: `product.json` (what it is,
 
 ### The terminology trap — do this before you name anything
 
-`product.json.terminology` and `migration.json.decisionsNeeded` frequently carry a **false friend**: a word the legacy code used that means something else to everyone else (a real case: `tenant` meaning *the seller's own market/legal entity*, not a customer org — where the customer org was `Company`).
+`product.json.terminology` and `migration.json.decisionsNeeded` frequently carry a **false friend**: a word the legacy code used that means something else to everyone else (a real case: `tenant` meaning _the seller's own market/legal entity_, not a customer org — where the customer org was `Company`).
 
 Carrying a false friend into the rebuild wastes the single cheapest opportunity you will ever have to fix it. Resolve the rename **before the first migration is written**, then apply the new name in table names, function names, and types. Add it to the parity report's glossary so the mapping stays legible to whoever compares old and new.
 
@@ -65,7 +65,7 @@ Present each as a real question with the options the code implies and what each
 
 **Never resolve one by reading the legacy code.** If the code answered it, the archaeologist would not have raised it. Silence in the legacy code is the finding.
 
-Record each answer in the parity report under **Decisions taken** with the date and who decided. This is the audit trail for behaviour that is *deliberately* not a port.
+Record each answer in the parity report under **Decisions taken** with the date and who decided. This is the audit trail for behaviour that is _deliberately_ not a port.
 
 ## Stage 1.5 — Emit the implementation inventory (do this before any code)
 
@@ -100,7 +100,7 @@ check its calls. The distinctions it encodes are the ones that matter:
   workflow. That trigger is the legacy shape of an event: a handler doing five
   unrelated things because there was no bus. Splitting it is the upgrade.
 - **user/admin journeys → scenarios, NOT `pikkuWorkflowFunc`s.** A blueprint
-  "workflow" is a *journey* — a sequence a person drives through the UI. A
+  "workflow" is a _journey_ — a sequence a person drives through the UI. A
   `pikkuWorkflowFunc` is durable multi-step orchestration. Conflating them produces
   a workflow engine driving form submissions, which is the most common way this
   mapping goes wrong.
@@ -110,22 +110,22 @@ cheapest progress report you have.
 
 ## Stage 2 — Scaffold
 
-Clone the Fabric starter template, then do the post-clone cleanup **pikku-build** covers (README, package name, lockfile, leftover template artifacts) — a rebuild that ships the template's own name and readme is the first thing a reviewer notices. Set `projectId`, `production.branch` and the frontend entry in `fabric.config.json` per **pikku-fabric**.
+Clone the Fabric starter template, then do the post-clone cleanup **pikku-build** covers (README, package name, lockfile, leftover template artifacts) — a rebuild that ships the template's own name and readme is the first thing a reviewer notices. Declare the frontend in `frontends` in `pikku.config.json` and link with `pikku fabric link` per **pikku-fabric** — there is no Fabric config file.
 
 Map `architecture.json` onto Fabric honestly, and expect it to shrink:
 
-| Blueprint `architecture.json` | Fabric |
-|---|---|
-| API/web process (Puma, Express, …) | the Fabric worker — no component to build |
-| Worker process + queue | `wireQueueWorker` (**pikku-wiring**) |
-| Cron/scheduler component | `wireScheduler` (**pikku-wiring**) |
-| Reverse proxy, deploy tooling, process manager | **drop** — the platform does this |
-| Admin console (ActiveAdmin, Django admin, …) | `scaffold.console: true` first; only build screens for what it genuinely can't express |
-| Session/auth store | Better Auth (**pikku-auth**) |
-| Relational datastore | SQLite via libSQL/Kysely (**pikku-fabric**, **pikku-kysely**) |
-| Redis for cache/locks/queues | usually **nothing** — see the trap below |
+| Blueprint `architecture.json`                  | Fabric                                                                                 |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
+| API/web process (Puma, Express, …)             | the Fabric worker — no component to build                                              |
+| Worker process + queue                         | `wireQueueWorker` (**pikku-wiring**)                                                   |
+| Cron/scheduler component                       | `wireScheduler` (**pikku-wiring**)                                                     |
+| Reverse proxy, deploy tooling, process manager | **drop** — the platform does this                                                      |
+| Admin console (ActiveAdmin, Django admin, …)   | `scaffold.console: true` first; only build screens for what it genuinely can't express |
+| Session/auth store                             | Better Auth (**pikku-auth**)                                                           |
+| Relational datastore                           | SQLite via libSQL/Kysely (**pikku-fabric**, **pikku-kysely**)                          |
+| Redis for cache/locks/queues                   | usually **nothing** — see the trap below                                               |
 
-**The Redis trap.** Legacy apps use Redis for four unrelated jobs: queue backend (→ Fabric's queue), cache (→ usually delete; measure first), pub/sub (→ **pikku-realtime**), and **distributed locks**. That last one is the trap: a lock is nearly always a workaround for a missing database constraint (`invariants.json` will show the same rule with `enforcedBy: "code-guard"` and an `atRiskBecause`). Port the *invariant* to a constraint; do not port the lock. Re-implementing legacy locking on a new stack is how you carry a race condition across a rewrite.
+**The Redis trap.** Legacy apps use Redis for four unrelated jobs: queue backend (→ Fabric's queue), cache (→ usually delete; measure first), pub/sub (→ **pikku-realtime**), and **distributed locks**. That last one is the trap: a lock is nearly always a workaround for a missing database constraint (`invariants.json` will show the same rule with `enforcedBy: "code-guard"` and an `atRiskBecause`). Port the _invariant_ to a constraint; do not port the lock. Re-implementing legacy locking on a new stack is how you carry a race condition across a rewrite.
 
 `architecture.json.deploymentConstraints` is the exception to "drop the infrastructure": entries there are constraints that must **survive** (raw-body ordering for webhook signatures, retry semantics an external caller depends on). Read them; they are cheap to lose and expensive to rediscover.
 
@@ -144,19 +144,19 @@ hand-coerce forever. `TEXT` + `CHECK` for a closed set is the highest-leverage c
 available: the constraint compiles into a **TypeScript union type**, so an invalid
 state is a compile error rather than a runtime one.
 
-The blueprint gives you `attributes`, `relationships`, `states`, `transitions`, `ownership`, `constraints`. It is a *domain* model, not the legacy DDL — you are not required to reproduce the old column layout, and usually shouldn't.
+The blueprint gives you `attributes`, `relationships`, `states`, `transitions`, `ownership`, `constraints`. It is a _domain_ model, not the legacy DDL — you are not required to reproduce the old column layout, and usually shouldn't.
 
 ### Legacy SQL → SQLite traps
 
-| Legacy | SQLite / Fabric | Why |
-|---|---|---|
-| `DECIMAL`/`NUMERIC` money, or a money library's `*_cents` | `INTEGER` minor units | SQLite has no exact decimal. Minor units are what the legacy money library stored anyway — keep the currency in its own column. **Never `REAL` for money.** |
-| `TIMESTAMP`/`DATETIME` | `DATETIME` | Types as a real `Date`. Do NOT store Unix ms in an `INTEGER` — you lose the typing and coerce by hand forever. |
-| `BOOLEAN` | `BOOLEAN` | Types as a real `boolean`. Do NOT store 0/1 in an `INTEGER`. |
-| `ENUM` | `TEXT` + `CHECK` | The one place to spend a `CHECK` — it is a closed set, and a typo'd state is exactly the bug class the blueprint keeps finding. |
-| `uuid`/`serial` PK | `INTEGER PRIMARY KEY AUTOINCREMENT`, or `TEXT` for a public id | **Look at `queries.json.scoping` first.** If the legacy app used a random public id (`puid`, slug) precisely so ids aren't enumerable, that is a *security property* — keep it. Silently switching to sequential integers un-fixes a fix. |
-| JSON column | `TEXT` + a typed parse | Fine, but if `entities.json` gives it real attributes, it wants columns. |
-| DB-level `CHECK` sprawl | app-level validation | Per **pikku-fabric** — *except* the invariants below. |
+| Legacy                                                    | SQLite / Fabric                                                | Why                                                                                                                                                                                                                                       |
+| --------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DECIMAL`/`NUMERIC` money, or a money library's `*_cents` | `INTEGER` minor units                                          | SQLite has no exact decimal. Minor units are what the legacy money library stored anyway — keep the currency in its own column. **Never `REAL` for money.**                                                                               |
+| `TIMESTAMP`/`DATETIME`                                    | `DATETIME`                                                     | Types as a real `Date`. Do NOT store Unix ms in an `INTEGER` — you lose the typing and coerce by hand forever.                                                                                                                            |
+| `BOOLEAN`                                                 | `BOOLEAN`                                                      | Types as a real `boolean`. Do NOT store 0/1 in an `INTEGER`.                                                                                                                                                                              |
+| `ENUM`                                                    | `TEXT` + `CHECK`                                               | The one place to spend a `CHECK` — it is a closed set, and a typo'd state is exactly the bug class the blueprint keeps finding.                                                                                                           |
+| `uuid`/`serial` PK                                        | `INTEGER PRIMARY KEY AUTOINCREMENT`, or `TEXT` for a public id | **Look at `queries.json.scoping` first.** If the legacy app used a random public id (`puid`, slug) precisely so ids aren't enumerable, that is a _security property_ — keep it. Silently switching to sequential integers un-fixes a fix. |
+| JSON column                                               | `TEXT` + a typed parse                                         | Fine, but if `entities.json` gives it real attributes, it wants columns.                                                                                                                                                                  |
+| DB-level `CHECK` sprawl                                   | app-level validation                                           | Per **pikku-fabric** — _except_ the invariants below.                                                                                                                                                                                     |
 
 ### States and transitions
 
@@ -171,26 +171,26 @@ Two traps the blueprint hands you for free:
 
 One vertical slice per domain. **Order by inbound reference count, not by importance**: the domains everything else points at go first. Identity and the customer/account domain are almost always the base — every other domain's `ownership` and `scoping` mentions them.
 
-Derive the order mechanically: for each domain, count how many *other* domains' entities have a relationship into it. Build the most-referenced first. Then, among the rest, take the ones that carry the most invariants and events (`domains.json` roll-ups tell you) — that's where the product is, and you want it under test early.
+Derive the order mechanically: for each domain, count how many _other_ domains' entities have a relationship into it. Build the most-referenced first. Then, among the rest, take the ones that carry the most invariants and events (`domains.json` roll-ups tell you) — that's where the product is, and you want it under test early.
 
 Leave for last: thin CRUD domains with no events and no invariants (content, downloads, media libraries). They're mechanical, and `migration.json` may well say the honest thing — that some shouldn't be rebuilt at all.
 
 ### What one slice contains
 
-| Blueprint | Fabric artifact | Skill |
-|---|---|---|
-| `commands[]` | one `pikkuFunc` per command, one per file, `expose: true` | **pikku-concepts** |
-| `queries[]` | one `pikkuSessionlessFunc`, `readonly: true`, `expose: true` | **pikku-concepts** |
-| `commands[].preconditions` | guards in the function body, throwing typed errors | **pikku-fabric** hard rules |
-| `policies[]` | `pikkuPermission` on the function's `permissions:` field | **pikku-permissions** |
-| `queries[].scoping` | the permission + the query's `where` | **pikku-permissions**, **pikku-kysely** |
-| `events[]` | realtime topic / queue message | **pikku-realtime**, **pikku-wiring** |
-| `workflows[] kind: system` | `wireScheduler` | **pikku-wiring** |
-| `workflows[]` multi-step | `pikkuWorkflowFunc` + `*.steps.ts` | **pikku-workflow** |
-| `workflows[].scenarios[]` | scenario tests | **pikku-scenario** |
-| `api[]` | mostly **nothing** — see below | **pikku-wiring** |
-| `invariants[]` | DB constraints, in the migration | **pikku-fabric** |
-| `integrations[]` | services | **pikku-services** |
+| Blueprint                  | Fabric artifact                                              | Skill                                   |
+| -------------------------- | ------------------------------------------------------------ | --------------------------------------- |
+| `commands[]`               | one `pikkuFunc` per command, one per file, `expose: true`    | **pikku-concepts**                      |
+| `queries[]`                | one `pikkuSessionlessFunc`, `readonly: true`, `expose: true` | **pikku-concepts**                      |
+| `commands[].preconditions` | guards in the function body, throwing typed errors           | **pikku-fabric** hard rules             |
+| `policies[]`               | `pikkuPermission` on the function's `permissions:` field     | **pikku-permissions**                   |
+| `queries[].scoping`        | the permission + the query's `where`                         | **pikku-permissions**, **pikku-kysely** |
+| `events[]`                 | realtime topic / queue message                               | **pikku-realtime**, **pikku-wiring**    |
+| `workflows[] kind: system` | `wireScheduler`                                              | **pikku-wiring**                        |
+| `workflows[]` multi-step   | `pikkuWorkflowFunc` + `*.steps.ts`                           | **pikku-workflow**                      |
+| `workflows[].scenarios[]`  | scenario tests                                               | **pikku-scenario**                      |
+| `api[]`                    | mostly **nothing** — see below                               | **pikku-wiring**                        |
+| `invariants[]`             | DB constraints, in the migration                             | **pikku-fabric**                        |
+| `integrations[]`           | services                                                     | **pikku-services**                      |
 
 ### Names are the contract
 
@@ -202,7 +202,7 @@ Every function needs a real `description` — take it from the concept's `descri
 
 ### The API is not the contract
 
-`api.json` has one entry per legacy surface, and it is **evidence, not a spec**. Each entry's `mapsTo` names the command or query — build *that*, and let RPC be the transport (**pikku-fabric**: RPC first, `expose: true`).
+`api.json` has one entry per legacy surface, and it is **evidence, not a spec**. Each entry's `mapsTo` names the command or query — build _that_, and let RPC be the transport (**pikku-fabric**: RPC first, `expose: true`).
 
 Add `wireHTTP` only where the URL shape is a real external contract:
 
@@ -235,7 +235,7 @@ In the rebuild these become real: publish the event (**pikku-realtime**) or enqu
 
 Two disciplines:
 
-- **Do not invent events.** The archaeologist applied a threshold (≥1 real consumer beyond the row write). If a CRUD fact isn't in `events.json`, it didn't earn an event; a state row that is only *read* later is state, not an event.
+- **Do not invent events.** The archaeologist applied a threshold (≥1 real consumer beyond the row write). If a CRUD fact isn't in `events.json`, it didn't earn an event; a state row that is only _read_ later is state, not an event.
 - **`explicit: false` is a confidence marker.** These are reconstructions of intent. When one drives money or an external side effect, the parity report says it was reconstructed — the reviewer should confirm the consumer list is complete.
 
 ### Policies — collapse the drift
@@ -244,17 +244,17 @@ Two disciplines:
 
 The whole point is **one `pikkuPermission` per rule**, referenced from every function that needs it (**pikku-permissions**). When the `enforcedAt` versions genuinely disagree, that's a decision, not a merge — ask which is correct. Picking the one you read first silently ships a behaviour change.
 
-Per **pikku-fabric**: no auth checks in function bodies. If a policy resists expression as a permission, that's a signal it's a *business rule* (a precondition) rather than authorization — those live in the function body and throw typed errors.
+Per **pikku-fabric**: no auth checks in function bodies. If a policy resists expression as a permission, that's a signal it's a _business rule_ (a precondition) rather than authorization — those live in the function body and throw typed errors.
 
 ## Stage 5 — Scenarios from the blueprint's tests
 
 `workflows[].scenarios[]` entries carry `fromTest` — they were excavated from the legacy suite, which means **they are the legacy app's executable spec**, already in given/when/outcome shape. They map directly onto **pikku-scenario** actors and flows, and `product.json.actors` gives you the actor list.
 
-This is the highest-leverage stage in the rebuild and the easiest to skip. A scenario ported from a legacy test is the only artifact that can tell you the new app *behaves* like the old one — parity of function names proves nothing.
+This is the highest-leverage stage in the rebuild and the easiest to skip. A scenario ported from a legacy test is the only artifact that can tell you the new app _behaves_ like the old one — parity of function names proves nothing.
 
 Two rules:
 
-- A scenario whose legacy test was **commented out or broken** (`gaps.json` flags these) still gets written — it just isn't parity, it's new coverage. Note which in the parity report; often the disabled test is disabled *because* the behaviour was broken.
+- A scenario whose legacy test was **commented out or broken** (`gaps.json` flags these) still gets written — it just isn't parity, it's new coverage. Note which in the parity report; often the disabled test is disabled _because_ the behaviour was broken.
 - A workflow with **no scenarios** is a gap in the blueprint, not permission to skip testing. Flag it rather than inventing behaviour to test.
 
 ## Stage 6 — Integrations
@@ -265,7 +265,7 @@ Two rules:
 - `"trivial"` → candidates for a platform-native equivalent, but only if the user wants it. Swapping a vendor mid-rebuild makes every failure ambiguous.
 - `envVars` → `defineVariable` / `defineSecret` (**pikku-services**). Per **pikku-fabric**: no `process.env`, ever.
 
-**Secrets in the blueprint are live secrets.** `gaps.json` security entries routinely name credentials hardcoded in the legacy source *and its committed history*. They must be **rotated**, not copied into the new app's secret store — and rotation is the legacy app's problem, today, independent of the rebuild. Say so; don't let the rebuild timeline become the remediation timeline.
+**Secrets in the blueprint are live secrets.** `gaps.json` security entries routinely name credentials hardcoded in the legacy source _and its committed history_. They must be **rotated**, not copied into the new app's secret store — and rotation is the legacy app's problem, today, independent of the rebuild. Say so; don't let the rebuild timeline become the remediation timeline.
 
 **Inbound webhooks deserve a real look.** They're the surfaces most likely to be carrying a `gaps.json` security entry (unverified signatures, disabled checks). Rebuild the verification properly (**pikku-wiring**), and if the reason it was disabled was a vendor that doesn't reliably sign, that's a `decisionsNeeded` — not something to replicate.
 
@@ -273,24 +273,24 @@ Two rules:
 
 Only when `frontend*.json` is present. Target: TanStack Start + Mantine.
 
-`frontend.json` records the legacy stack as facts. **It is context, not a port target** — a bespoke Sass system, a server-rendered template stack, or a different component library all land on the same target. Read `designSystemConsistency` and `designFindings` to know what *not* to carry: findings are the drift (hardcoded colors, forked-per-locale pages, duplicated components), and the rebuild is the moment they cost nothing to drop.
+`frontend.json` records the legacy stack as facts. **It is context, not a port target** — a bespoke Sass system, a server-rendered template stack, or a different component library all land on the same target. Read `designSystemConsistency` and `designFindings` to know what _not_ to carry: findings are the drift (hardcoded colors, forked-per-locale pages, duplicated components), and the rebuild is the moment they cost nothing to drop.
 
 ### Routes
 
 `frontend-routes[]` → TanStack routes. `path` and `purpose` carry over; `auth` becomes the route guard.
 
-**`dataFrom` is the payoff.** It lists query/command names — the *same* names as `queries.json`/`commands.json`, which are the same names as your `pikkuFunc`s, which are the same names in the generated client. So a route's data layer is mechanical: each `dataFrom` entry is a generated hook (**pikku-react**). If `dataFrom` contains a name that isn't a real function, the blueprint wasn't reconciled — go fix it there.
+**`dataFrom` is the payoff.** It lists query/command names — the _same_ names as `queries.json`/`commands.json`, which are the same names as your `pikkuFunc`s, which are the same names in the generated client. So a route's data layer is mechanical: each `dataFrom` entry is a generated hook (**pikku-react**). If `dataFrom` contains a name that isn't a real function, the blueprint wasn't reconciled — go fix it there.
 
 ### Components — the honest cost
 
 `frontend-components[].rebuild` is the only field that matters for planning:
 
-| `rebuild` | What to do |
-|---|---|
-| `mantine-standard` | Use the Mantine component. Do not port. |
-| `mantine-composition` | Compose from Mantine primitives. Do not port. |
-| `custom-style` | Normalize to Mantine + theme tokens. The divergence is the thing to drop. |
-| **`custom-logic`** | **Port the behaviour.** Read `customLogic` and `dependencies`. |
+| `rebuild`             | What to do                                                                |
+| --------------------- | ------------------------------------------------------------------------- |
+| `mantine-standard`    | Use the Mantine component. Do not port.                                   |
+| `mantine-composition` | Compose from Mantine primitives. Do not port.                             |
+| `custom-style`        | Normalize to Mantine + theme tokens. The divergence is the thing to drop. |
+| **`custom-logic`**    | **Port the behaviour.** Read `customLogic` and `dependencies`.            |
 
 The first three are the bulk and they're cheap — they're a re-expression, not a migration. **`custom-logic` is the actual project**: the bespoke chart, the virtualized table, the map surface, the rich editor, the drag interaction. Each has real behaviour that must survive, and `customLogic` says what it is.
 
@@ -324,7 +324,7 @@ diff, because it is the only document that holds the blueprint and the new code
 Per domain:
 
 - **Built** — each command/query/event/policy → its function/file. The concept-name-as-ID makes this a table, not prose.
-- **Deliberately not built** — from `migration.json.dropped` and `gaps.json`, with the reason. *The most important section.* Without it, every dropped bug and orphan reads as a regression to whoever reviews.
+- **Deliberately not built** — from `migration.json.dropped` and `gaps.json`, with the reason. _The most important section._ Without it, every dropped bug and orphan reads as a regression to whoever reviews.
 - **Decisions taken** — each gate answer, who decided, when. Behaviour that deliberately differs from the legacy app.
 - **Now enforced** — invariants that were `enforcedBy: "nothing"` and now have a constraint. The rebuild's actual dividend, in one list.
 - **Reconstructed** — anything from `confidence: low`/`medium` or `explicit: false` events. Flag for confirmation against production behaviour.
@@ -333,20 +333,20 @@ Per domain:
 
 ## Red flags
 
-| Thought | Reality |
-|---|---|
-| "Let me check how the old code did this" | The blueprint says what it does. If it doesn't, it's a decision — ask. Reading legacy source is how its accidents get re-imported. |
-| "I'll port the state machine library" | Port the *states and transitions*. The library is implementation; `commands.json` already names every transition. |
-| "The blueprint lists this state, so I'll create it" | Check it's reachable. Unreachable states are a finding, not a spec. |
-| "I'll wire HTTP for each `api.json` entry" | You're transcribing the legacy router. RPC first; `wireHTTP` only for genuinely fixed external URLs. |
-| "The old app didn't enforce it, so neither will I" | `enforcedBy: "nothing"` is the highest-value work in the rebuild — the reason it's worth doing at all. |
-| "I'll add events for the CRUD actions too" | The archaeologist applied a consumer threshold. Not in `events.json` = didn't earn one. |
-| "Two enforcement sites disagree; I'll use the first one" | That's a silent behaviour change. Drift is a decision — ask which is correct. |
-| "It's just screens, the frontend is quick" | The `custom-logic` components are the project. Scope them individually before starting. |
-| "I'll copy the secrets into the new secret store" | Blueprint-exposed secrets are burned. Rotate. And the legacy app needs that today, regardless of the rebuild. |
-| "I'll do the parity report at the end" | You will not remember why you dropped things, and dropped-on-purpose will read as regression. |
-| "Verify once it's all built" | No bisect point. Verify per slice; that's what slices are for. |
-| "The blueprint has a `low`-confidence entry, I'll build my best guess" | That's inventing product. It's a gate question. |
+| Thought                                                                | Reality                                                                                                                            |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| "Let me check how the old code did this"                               | The blueprint says what it does. If it doesn't, it's a decision — ask. Reading legacy source is how its accidents get re-imported. |
+| "I'll port the state machine library"                                  | Port the _states and transitions_. The library is implementation; `commands.json` already names every transition.                  |
+| "The blueprint lists this state, so I'll create it"                    | Check it's reachable. Unreachable states are a finding, not a spec.                                                                |
+| "I'll wire HTTP for each `api.json` entry"                             | You're transcribing the legacy router. RPC first; `wireHTTP` only for genuinely fixed external URLs.                               |
+| "The old app didn't enforce it, so neither will I"                     | `enforcedBy: "nothing"` is the highest-value work in the rebuild — the reason it's worth doing at all.                             |
+| "I'll add events for the CRUD actions too"                             | The archaeologist applied a consumer threshold. Not in `events.json` = didn't earn one.                                            |
+| "Two enforcement sites disagree; I'll use the first one"               | That's a silent behaviour change. Drift is a decision — ask which is correct.                                                      |
+| "It's just screens, the frontend is quick"                             | The `custom-logic` components are the project. Scope them individually before starting.                                            |
+| "I'll copy the secrets into the new secret store"                      | Blueprint-exposed secrets are burned. Rotate. And the legacy app needs that today, regardless of the rebuild.                      |
+| "I'll do the parity report at the end"                                 | You will not remember why you dropped things, and dropped-on-purpose will read as regression.                                      |
+| "Verify once it's all built"                                           | No bisect point. Verify per slice; that's what slices are for.                                                                     |
+| "The blueprint has a `low`-confidence entry, I'll build my best guess" | That's inventing product. It's a gate question.                                                                                    |
 
 ## Quick reference
 
@@ -372,6 +372,6 @@ legacy repo → pikku-software-archaeology → .knowledge/ blueprint
 thing, and emits `parity-*.md` so the rebuild can be reviewed against the blueprint rather than
 against the legacy code.
 
-For Fabric mechanics — project layout, `fabric.config.json`, the validate loop, reading a deployed
-stage — use **pikku-fabric**. For a single feature *after* the rebuild, and for the post-clone
+For Fabric mechanics — project layout, how a checkout is linked, the validate loop, reading a deployed
+stage — use **pikku-fabric**. For a single feature _after_ the rebuild, and for the post-clone
 cleanup in Stage 2, use **pikku-build**.

package/skills/pikku-build/SKILL.md

@@ -44,7 +44,8 @@ plus more effort" — it is App plus a deliberate surface checklist, so read the
 base first and follow it in full rather than blending the two into one plan.
 
 The supporting references belong to whichever mode sends you to them:
-`references/multi-app.md` (a second frontend), `references/design.md` (showing
+`references/multi-app.md` (a second frontend), `references/native-app.md`
+(shipping an app as a desktop or Android app), `references/design.md` (showing
 a picture of the screens first, committing to a design direction, and judging
 whether the screens realise it — read before the first screen is built, not
 after the last), `references/theming.md`
@@ -139,7 +140,7 @@ generated functions through `ref()`.
 - **Print the links whenever the stack comes up, and in every hand-over.** Full,
   clickable URLs, with the ports taken from what `bun run dev` actually printed:
   - **App** — the frontend's URL (`http://localhost:7104` in the template; each
-    frontend in `pikkufabric.config.json` has its own port)
+    frontend in `frontends` in `pikku.config.json` has its own port)
   - **API** — `http://localhost:3000`
   - **Console** — `http://localhost:3000/console`, plus a deep link to each
     page that shows what this turn produced (the paths are below)

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

@@ -335,7 +335,7 @@ Cloning `apps/app` materialises a folder of copied screens, so it belongs to the
 milestone that first needs the second app, not to planning.
 
 When you get there, read `references/multi-app.md`. It carries the clone, the
-`package.json` edits, the `pikkufabric.config.json` frontends map, the dev-runner
+`package.json` edits, the `frontends` map in `pikku.config.json`, the dev-runner
 change that otherwise silently never starts your second app, the per-frontend
 scenario environments, and how sessions behave across two origins.
 
@@ -568,22 +568,18 @@ Then run it:
 bun run prebuild && bun run dev
 ```
 
-That starts the API on :3000 and every frontend in `pikkufabric.config.json`. A
+That starts the API on :3000 and every frontend in `frontends`. A
 frontend running against a dead API looks exactly like an app bug, so if every
 request fails, check that both halves came up.
 
 **Start the stack through `bun run dev`, not by launching `vite` or `pikku dev`
-yourself.** The dev script reads the personas, derives one credential per
-persona from `SCENARIO_ACTOR_SECRET`, and hands both to the frontend as
-`VITE_DEV_ACTORS` / `VITE_DEV_ACTOR_SECRETS`. Vite reads those once, at boot. A
-frontend started any other way — or restarted by hand later — has an empty
-actor list, and the switcher silently disappears from every page. If you do
-start the frontend on its own (say :3000 is taken by another project), you owe
-it three things: the two `VITE_DEV_*` values the dev script would have computed,
-and `VITE_API_PROXY` pointing at your API — the dev proxy defaults to
-`http://localhost:3000`, so beside another project's server your sign-ins go to
-_its_ API and come back `401 Invalid actor secret`, which reads like a bad
-credential rather than the wrong server.
+yourself.** The "Sign in as …" switcher asks the API for its personas at
+runtime, so the frontend needs nothing baked in — but it does need to reach
+_your_ API. If you start the frontend on its own (say :3000 is taken by another
+project), point `VITE_API_PROXY` at your API: the dev proxy defaults to
+`http://localhost:3000`, so beside another project's server the switcher lists
+_its_ personas, or none, which reads like a missing switcher rather than the
+wrong server.
 
 The `--bun` in `bunx --bun pikku …` is load-bearing — keep it. Without it the
 CLI's `#!/usr/bin/env node` shebang hands the process to whatever Node is on
@@ -709,6 +705,21 @@ new RPC and does not re-run `afterStart`, so a fresh function answers 404 and
 anything provisioned at boot is missing — failures that read like a wiring bug
 and are nothing but a stale process.
 
+**Run the whole suite, not the milestone's own scenarios.** The milestone's
+scenarios are the ones you wrote to pass; the regression lives in someone
+else's. Tightening what "archived" means is a one-function change that reads as
+local and quietly breaks the milestone-01 scenario nobody re-ran.
+
+**Restart the server after adding a function, and never edit one while a run is
+in flight.** Hot reload does not register a new RPC and does not re-run
+`afterStart`, so a fresh function answers 404 and anything provisioned at boot
+is missing — failures that read like a wiring bug and are nothing but a stale
+process. The same reload is what makes a run unrepeatable if you edit during
+it: a browser pass is long enough to feel like free time, and a schema touched
+at minute four hot-reloads into a half-generated contract, so every scenario
+after that point fails on something you have already fixed. Wait for the run or
+kill it — a run you edited under is not a result.
+
 ### 7a. Coverage — which functions have actually been run
 
 Green scenarios tell you the journeys you wrote still work. They say nothing

package/skills/pikku-build/references/multi-app.md

@@ -3,7 +3,7 @@
 Read this when the split you recorded in Phase 2 is "separate apps" and you have
 reached the milestone that needs the second one. **Not before.** Cloning
 `apps/app` materialises a directory of copied screens; doing it during planning
-leaves `pikkufabric.config.json` pointing at an app nobody has designed yet.
+leaves `frontends` in `pikku.config.json` pointing at an app nobody has designed yet.
 
 If the split is "one app with paths", you never need this file — add route
 segments under `/app` and give each audience its own entries in `useNavItems()`.
@@ -66,14 +66,15 @@ second is the one that catches a `permissions` field nobody wired.
 ## The second app
 
 ```bash
-pikku new app admin --serves staff --personas manager,mechanic
+pikku app new admin --serves staff --personas manager,mechanic
 ```
 
 One command does every step this section used to list by hand: it fetches
 `pikkujs/starter-template`'s `apps/app`, re-points its `package.json` at the
 new name, its own dev/preview port and its own `--tsBuildInfoFile`, stamps
 `app: '<slug>'` onto each named persona in `definePersonas({…})`, adds the
-`frontends` entry, and re-runs `bun install`.
+`frontends` entry to `pikku.config.json`, and re-runs `bun install`. `pikku app
+list` shows every app afterwards.
 
 **It scaffolds from the starter template, not from the app you already have.**
 Copying the working app drags its screens, routes and nav into an audience that
@@ -119,10 +120,14 @@ It stops after `bun install`. Serving the new app — a reverse proxy, a
 supervisor, a dev runner, a deploy target — belongs to whatever is hosting it.
 On a plain checkout, `bun --filter @project/<slug> dev` is enough.
 
+Packaging it as a desktop or Android app is a separate step, on the same
+`frontends` entry: `pikku app native init <slug>`. See
+`references/native-app.md`.
+
 ### Scenarios across the two apps
 
-`pikku new app` stamps `app: '<slug>'` onto each persona it is given, and that
-field — not the `personas` array in `pikkufabric.config.json` — is what
+`pikku app new` stamps `app: '<slug>'` onto each persona it is given, and that
+field — not the `personas` array on the `frontends` entry — is what
 `@pikku/playwright` resolves a persona's base url from at sign-in. A persona
 with no `app` lands on the fallback frontend, which is the other app's screens
 with the right session on them.

package/skills/pikku-build/references/native-app.md

@@ -0,0 +1,148 @@
+# Shipping an app as a desktop or Android app
+
+Read this when an app in `frontends` has to be installed rather than visited: a
+desktop app, an Android APK, later an iPhone app. The app is still the same
+frontend. A native app is that frontend packaged in a Tauri shell, configured on
+its `frontends` entry, with the Tauri project committed beside it.
+
+```
+apps/customer/            ← frontends.customer.cwd
+  package.json            ← gains @tauri-apps/cli, @tauri-apps/api, one package per plugin
+  dist/                   ← frontends.customer.dist, which the shell packages
+  src-tauri/              ← the native project, committed
+```
+
+## The commands
+
+Every app command is under `pikku app` — native included, as `pikku app native`.
+There is no `pikku new app`, and no app flag on `pikku deploy`.
+
+```bash
+pikku app new <name>                  # a second frontend, from the starter template
+pikku app list                        # every app, where it lives, what it ships as
+pikku app native init <name>          # write the native project (or re-apply config to it)
+pikku app native add <name> store biometric   # add plugins
+pikku app native upgrade <name>       # rewrite pikku's half from the config as it stands
+pikku app native check [name]         # compare projects to the config, and apps to each other
+```
+
+`init` flags, all optional. Each one is saved into `frontends.<name>.native`
+first, and every later `add`, `upgrade` and `check` reads the config, not the
+flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `--desktop` `--android` `--ios` | Platforms. None given: desktop, Android and iOS, or desktop alone with `--bundle-server` |
+| `--identifier com.acme.customer` | Bundle id and Android package name. Default `com.<npm scope>.<app name>` |
+| `--product-name "Acme"` | The name people see. Default: the app name |
+| `--url https://app.example.com` | Open a deployed origin instead of bundling `dist` |
+| `--bundle-server` | Ship the compiled pikku server inside the app (desktop only) |
+| `--plugins store,dialog` | Native plugins, comma-separated |
+
+The resulting config:
+
+```json
+"frontends": {
+  "customer": {
+    "cwd": "apps/customer",
+    "kind": "spa",
+    "native": {
+      "identifier": "com.acme.customer",
+      "platforms": ["desktop", "android"],
+      "plugins": ["store", "biometric"]
+    }
+  }
+}
+```
+
+## Pick the mode first
+
+| Config | The window shows | Platforms | Costs |
+| --- | --- | --- | --- |
+| *(default)* | `dist`, bundled into the app | desktop, Android, iOS | the API is cross-origin |
+| `"url": "https://…"` | a deployed server's own origin | desktop, Android, iOS | no UI without a network; the App Store rejects a site wrapper |
+| `"bundleServer": true` | the compiled server, spawned as a sidecar | desktop only | a bun-compiled binary per target |
+
+**The default mode's cost is auth.** A bundled page's origin is
+`tauri://localhost` (macOS, iOS, Linux) or `http://tauri.localhost` (Windows,
+Android), so the API is on another origin:
+
+- cookies are third-party, so authenticate with a bearer token and keep it in the
+  `store` plugin, not in a cookie;
+- the server's CORS rules must allow both origins, with the auth headers;
+- the API base can no longer be `window.location.origin` or a relative `/api`.
+  Read it from a build-time variable (`VITE_API_URL`) that the native build sets;
+- OAuth cannot redirect back to the app's origin. Social login goes out through
+  the system browser and returns through a deep link.
+
+`url` mode pays none of this, because the page lives on the server's real origin.
+`bundleServer` pays none of it either, and is the offline, single-machine option.
+Neither `url` nor `bundleServer` can be combined with the other.
+
+**A `kind: "ssr"` frontend cannot be bundled.** There is no server in the app to
+render it, so `init` refuses and asks you to build it as a static SPA or use
+`--url`.
+
+## What pikku owns and what you own
+
+The project is yours to edit. Pikku rewrites only these parts, on every `add`
+and `upgrade`, and never touches anything else:
+
+| Pikku rewrites | You own |
+| --- | --- |
+| `src/pikku.rs` (every plugin initialiser) | `src/lib.rs`, `src/main.rs`, which call `pikku::plugins(builder)` once |
+| `capabilities/pikku.json`, `capabilities/pikku-mobile.json` | any other `capabilities/*.json` |
+| the `# pikku:plugins:*` and `# pikku:mobile-plugins:*` blocks in `Cargo.toml` | the rest of `Cargo.toml` |
+| `identifier`, `productName`, `build.frontendDist`, `bundle.externalBin` in `tauri.conf.json` | every other key, the window list included |
+| `@tauri-apps/*` entries in `package.json`, only when missing | the rest, including pinned versions |
+| `ui/index.html`, with `bundleServer` only | icons, `Info.ios.plist`, `gen/android`, `gen/apple` |
+
+Put your own crates outside the marker blocks. If a marker is deleted, `add`
+refuses rather than guess. If `lib.rs` stops calling `pikku::plugins`, `check`
+reports it, because otherwise no plugin you configure is initialised.
+
+## Plugins
+
+`store`, `dialog`, `clipboard-manager`, `os`, `notification` and `geolocation`
+run everywhere. `biometric`, `haptics`, `barcode-scanner` and `nfc` are
+mobile-only. Pikku gates them with `#[cfg(mobile)]` and a target-specific
+dependency, so the desktop build of the same crate still compiles. Call a plugin
+through its `@tauri-apps/plugin-*` package, behind a
+`window.__TAURI_INTERNALS__` check so the same build still runs in a browser.
+iOS consent strings are written to `Info.ios.plist`; reword them for the app.
+
+## The identifier
+
+One per app, used on every platform, and **unique across apps**. Two apps that
+share an identifier replace each other on install and share a data directory.
+`init` refuses a clash and `check` reports one. Android sets the format: no
+hyphens, no segment that starts with a digit, no Java keyword. macOS also rejects
+an identifier ending in `.app`. The identifier can change freely until the first
+store release and never afterwards.
+
+## Building
+
+Generation is plain file writing, so it succeeds on a machine that cannot build
+the result. From the app's `cwd`, after installing:
+
+```bash
+bun run tauri dev                      # against the frontend's dev server
+bun run tauri build                    # after building dist
+bun run tauri android init && bun run tauri android build --apk
+```
+
+Desktop needs a Rust toolchain. Android also needs the Android SDK and NDK, and
+iOS needs Xcode on a Mac. `tauri android init` and `tauri ios init` write
+`src-tauri/gen/android` and `gen/apple`; commit them, because signing and the
+manifest live there.
+
+**CI builds from an uploaded `dist`.** Nothing in `src-tauri/` depends on the
+machine that generated it, so build the frontend once, upload `dist/` as an
+artifact, and run `tauri build` on a runner per platform. The exception is
+`bundleServer`, whose `binaries/` holds a server compiled for one target and is
+gitignored. `pikku deploy apply --provider standalone --runtime bun` compiles the
+server and installs it into every app whose `native.bundleServer` is set.
+
+Builds are unsigned. macOS asks for right-click → Open on first launch, Windows
+shows SmartScreen, and an Android debug APK sideloads. A signed release needs
+keys that the CI holds as secrets.