@pikku/skills 0.12.52 → 0.12.55

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

@@ -1,5 +1,17 @@
 # Design
 
+## Contents
+
+- Commit to a direction before the first screen
+- Offer to draw the screens before you build them
+- One screen, designed properly, before the rest exist
+- Judge it — and don't grade your own homework
+- The kit is a floor, not a ceiling
+- Design is a gate on the changeset, not a phase at the end
+- Facts, not taste
+- Two screens that get skipped
+- Symptoms of a screen nobody designed
+
 Your job here is to design something worth the product — not to apply a house
 style. **There is no house style, and this file is not one.** Two apps built from
 this skill should not look like each other; if they do, something has gone wrong
@@ -16,14 +28,14 @@ nearest to hand, on every screen, in every app. Not because it lacks taste, but
 because there is nothing to be wrong against. A direction fixes that: state one,
 in words, before any screen exists.
 
-Say what this product *is* — its register, its reference points, what it feels
+Say what this product _is_ — its register, its reference points, what it feels
 like to use, what it is deliberately not. "A warm, food-forward thing you use
 standing at an open fridge door, closer to a recipe card than to a dashboard, and
 never clinical" is a direction. "Clean and modern" is not — it rules nothing out,
 so it cannot be departed from.
 
 Write it to `knowledge/decisions/design/`, then build the theme from it
-(`references/theming.md`). **From that point you are accountable to your own
+(the theming reference, see SKILL.md). **From that point you are accountable to your own
 direction, not to this file.** That is the whole mechanism: the freedom is real,
 and so is the commitment.
 
@@ -34,13 +46,13 @@ chosen — it has been defaulted to in words instead of in components.
 
 Being ambitious is easier against a list of specific things to not be. Generated
 interfaces cluster hard, and these are the attractors — not because any is ugly,
-but because arriving at one *by default* means no choice was made:
+but because arriving at one _by default_ means no choice was made:
 
-- **Stock Mantine.** The strongest pull, and the hardest to see: a component
+- **Stock component-library defaults.** The strongest pull, and the hardest to see: a component
   library's untouched defaults do not look broken, they look finished. Blue
-  accent, `#dee2e6` borders, `md` radius on everything, `Card` + `Stack` + `Text`
+  accent, grey borders, one radius on everything, `Card` + stacked text
   down every page. An app can be entirely this and never trip a critique, because
-  nothing on any screen is *wrong*.
+  nothing on any screen is _wrong_.
 - Warm cream ground with a serif display face and a terracotta accent.
 - Near-black with one acid-green or vermilion pop.
 - A purple-to-blue gradient header on white.
@@ -71,29 +83,29 @@ screens costs a fraction of eight built screens, and it is the only point where
 "that is not what I meant" is free.
 
 **Author the theme first, then draw the mock from it.** This order is the whole
-point. A beautiful page in hand-rolled CSS sets a bar Mantine then misses, and
+point. A beautiful page in hand-rolled CSS sets a bar the real components then miss, and
 what the user approved is not what ships — they signed off on a picture and
 received an approximation of it. So write `themes/<name>.json` first
-(`references/theming.md`), and let the mock take its every value from that file:
+(the theming reference, see SKILL.md), and let the mock take its every value from that file:
 the palette, `structure.radius`, the spacing scale, the fonts, the component
 `defaultProps`. Approving the mock then approves the theme, and the built screens
 inherit it rather than chase it.
 
-**The mock has two halves, and only one of them is Mantine's.** This is the same
+**The mock has two halves, and only one of them is the component library's.** This is the same
 split the built screen lives under, applied a step earlier so the two agree by
 construction. The PAGE — the shell, the regions, the columns, the rhythm, the
 material behind the content, what overlaps what — is plain HTML and your own
 CSS, arranged however the layout decision demands; that half is free, and it is
 where the design actually happens. The COMPONENTS — anything a person would
 point at and call a control, and that the app will adopt as itself: buttons,
-inputs, selects, tables, badges, menus, modals — are drawn as *Mantine's*, at the
-metrics Mantine actually uses: its control heights, its input shapes, its table
+inputs, selects, tables, badges, menus, modals — are drawn as _shadcn's_, at the
+metrics shadcn actually uses: its control heights, its input shapes, its table
 and menu behaviour. The test is the one the build will apply too: is this thing
 the SHAPE OF THE PAGE, or a COMPONENT someone would point at?
 
 Getting that second half wrong is what makes a mock a lie. A control the mock
 invents is a promise the app cannot keep, and a beautiful hand-rolled input sets
-a bar the real one misses on screen one. If the mock wants something Mantine
+a bar the real one misses on screen one. If the mock wants something shadcn
 does not do, that is a real finding, and finding it here is the point: change the
 theme so it does, or change the mock, and say which.
 
@@ -102,7 +114,7 @@ needs — not a prototype, not a click-through. Static markup, real content from
 their domain (never lorem), the empty and error states beside the happy path,
 laid out so the whole app is legible by scrolling. Its CSS is custom properties
 on `:root` carrying the theme JSON's values, so a change to either is a change
-to one number in both. Mantine itself will not load here — it is a React library
+to one number in both. The components themselves will not load here — they are React
 and a page like this has no bundler, and on hosts that sandbox the page (a Claude
 Artifact) external stylesheets are blocked outright — so do not try; the mock
 reproduces the theme's values by hand, which is why they have to be written down
@@ -126,29 +138,29 @@ stating:
   mock was wrong. Update it, and say you did. Do not let the app and the mock
   drift and then quietly prefer the app.
 - The knowledge graph still owns the domain — objects, roles, rules. The mock
-  owns what the screens look like. When they disagree about a *fact*, knowledge
-  wins; when they disagree about a *layout*, the mock wins.
+  owns what the screens look like. When they disagree about a _fact_, knowledge
+  wins; when they disagree about a _layout_, the mock wins.
 
 **Building it is then a transcription, not a translation.** Because the theme
-already exists and the mock was drawn from it, the screen is Mantine components
+already exists and the mock was drawn from it, the screen is shadcn components
 arranged the way the mock arranges them — the look arrives with the theme. Two
 rules keep it that way:
 
-- **Layout is yours to write; components are Mantine's.** The page shape — the
+- **Layout is yours to write; components are shadcn's.** The page shape — the
   regions, the columns, the rhythm, what sits beside what — is ordinary markup
   and your own CSS. Anything a person would point at and call a control comes
-  from Mantine: buttons, inputs, selects, tables, badges, menus. Those carry
+  from shadcn: buttons, inputs, selects, tables, badges, menus. Those carry
   focus rings, keyboard behaviour and i18n, and hand-rolling one throws all of
   it away.
 - **A gap goes back to the theme, never into a component override.** If a screen
   does not match the mock, the fix is a value in `themes/<name>.json`. A stack of
-  one-off `className`s and `!important` fighting Mantine's defaults looks like
+  one-off `className`s and `!important` fighting the component defaults looks like
   progress on screen one and is unmaintainable by screen five, and the screens
   drift apart because nothing central holds them together.
 
 **Checking the built screen against the mock** is a structural comparison, not a
 pixel one: the same regions in the same order, the same hierarchy, the same
-states present, the same tokens used. Do not chase pixel equality — Mantine's
+states present, the same tokens used. Do not chase pixel equality — shadcn's
 components have their own metrics and the mock was drawn without them. A built
 screen that reads as the same screen has passed.
 
@@ -192,9 +204,9 @@ the thing that made it is always yes. Use evidence.
   Then drive it over CDP from a script: `Page.navigate`,
   `Emulation.setDeviceMetricsOverride` for the two widths,
   `Page.captureScreenshot`, write the PNG, and open it. Sign in the way a person
-  does — click the dev actor switcher on the login page — rather than reaching
-  for the secret the client uses; the UI path is shorter and it also proves the
-  login screen works. Keep the script; you will run it at every changeset.
+  does — through the login page — rather than reaching for the secret the
+  client uses; the UI path also proves the login screen works. Keep the script; you will run it at every changeset.
+
 - **Run `impeccable`** (`npx impeccable install`, Node 22.18+) and feed it the
   screenshots. It is external, it does not flatter, and it scores execution
   against interaction heuristics. But it audits how well you executed the design
@@ -228,7 +240,7 @@ inventory, and it produces the wall of identical boxes further down this file.
 list.** A product has objects of its own, and the ones that carry its meaning are
 the ones no generic kit ships:
 
-- the thing the product is *about*, rendered as itself — a funding meter, a
+- the thing the product is _about_, rendered as itself — a funding meter, a
   streak, a seat map, a run's status over time. If a decision note says the
   progress toward a goal is the primary object, then a component that draws that
   progress has to exist, or the note is describing an app you did not build.
@@ -243,7 +255,7 @@ Adding them is not hand-rolling, and they are the difference between an app that
 uses a design system and an app that looks like one.
 
 The tell that you skipped this: your `components/` directory maps one-to-one onto
-your data model and contains nothing that names a *quality* of the product.
+your data model and contains nothing that names a _quality_ of the product.
 
 ## Design is a gate on the changeset, not a phase at the end
 
@@ -269,7 +281,7 @@ repaint is a rewrite.
 ### The seed is part of the gate
 
 A screenshot is only evidence if the screen has something on it. Before the gate
-runs, the dev seed must populate what each screen *is for* — not one row, and not
+runs, the dev seed must populate what each screen _is for_ — not one row, and not
 an empty state.
 
 This is a real and quiet failure: a list app whose seed has no list, a countdown
@@ -280,7 +292,7 @@ designing and is not what the changeset is about.
 Seed enough to be judged against: several rows, not three identical ones, and a
 deliberate spread of the cases the screen has to hold — a long title that wraps,
 a missing optional field, a picture and no picture, one item in each state the
-screen can show. Anything derived from *today* — a countdown, "3 days ago", an
+screen can show. Anything derived from _today_ — a countdown, "3 days ago", an
 expiry — is seeded as an interval from `now`, never as a fixed date: fixed dates
 are correct on the afternoon they are written and meaningless a month later.
 
@@ -308,8 +320,8 @@ These are not design opinions and are not open to a different answer.
 - **Empty, loading and error are states that exist.** The empty state is what a
   new user meets first and the one most often skipped entirely.
 - **Contrast and tap targets are measured, not judged.** `pikku-a11y` covers it.
-  One trap worth knowing: a Mantine `light` variant paints its label at the
-  generated ramp's stop, which lands just under AA on its own tint — name the
+  One trap worth knowing: a tinted badge paints its label in the
+  accent, which lands just under AA on its own tint — name the
   darker ink once and reuse it.
 
 ## Two screens that get skipped
@@ -351,7 +363,7 @@ first one.
   and a display font applied to a default layout is a well-dressed default.
 - Every border, divider and disabled control is a cool blue-grey while the
   accent is not — the surest sign the neutrals were inherited rather than
-  chosen. See `references/theming.md`.
+  chosen. The theming reference (see SKILL.md) covers it.
 - It looks like the last app you built.
-- It looks like Mantine. Not *built with* Mantine, which it is and should be —
+- It looks like stock shadcn. Not _built with_ shadcn, which it is and should be —
   but indistinguishable from a component gallery with the brand hue swapped in.

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

@@ -1,5 +1,19 @@
 # Pikku Create-a-Feature
 
+## Contents
+
+- Agent Operating Procedure
+- Stage 1 — Discover
+- Stage 2 — State intent in plain English (BEFORE writing code)
+- Stage 3 — Branch off
+- Stage 4 — Implement
+- Stage 5 — Verify
+- Stage 6 — Commit
+- Stage 7 — Hand off
+- Report what fought you
+- Hard constraints
+- Output discipline
+
 The stages, in order:
 
 - [Agent Operating Procedure](#agent-operating-procedure)
@@ -257,8 +271,8 @@ Do not push without explicit confirmation. Do not merge.
 ## Report what fought you
 
 When pikku itself is what cost you time — a wrong generated type, a check that
-passed when it should not, a skill that misled you — file it with `pikku fabric
-report`. The `pikku-report` skill owns the ladder, the two kinds, the JSON-on-
+passed when it should not, a skill that misled you — file it as the
+`pikku-report` skill describes. That skill owns the ladder, the two kinds, the JSON-on-
 stdin form and asking the user at hand-over; read it before filing.
 
 Filing is permitted here (see **Hard constraints**), and sending what was filed
@@ -276,7 +290,7 @@ The skill's `allowed-tools` does **not** permit:
 - `pikku deploy apply` (never deploy)
 - secret writes
 - network calls beyond what the implementation requires, except
-  `pikku fabric report`, which is explicitly permitted
+  filing a finding as `pikku-report` describes, 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-build/references/mocks.md

@@ -0,0 +1,29 @@
+# Data the backend does not have yet
+
+Read this when a screen needs data no function returns yet, or returns in a different shape. Real functions come first; mock only what is missing.
+
+## Three ways to get data
+
+- `usePikkuQuery('rpc:name')` and `usePikkuMutation('rpc:name')` take only RPCs that exist, with the function's own types. `api.gen.ts` lists them. Use these whenever a function fits.
+- Mocks are files, not code: `.mocks/<rpc.name>/<scenario>.json` is exactly what the RPC answers, and `<scenario>.meta.json` beside it holds `label`, `description`, `state` (healthy, empty, error or slow), `default`, `delayMs` and `status`. Exactly one scenario per RPC has `default: true`. Add an empty and an error scenario for every list and every mutation.
+- `usePikkuQueryStub('rpc:name')` and `usePikkuMutationStub('rpc:name')` always answer from the mock, and their output type is inferred from the mock files. Use a stub only when the function's types are not enough: no function exists, or the shape the screen needs differs from the function's output. If the mock already fits the function, use `usePikkuQuery`.
+
+The app loads its mocks with `registerPikkuMocks()` from the generated `mocks.gen.ts` beside `api.gen.ts`, called when `import.meta.env.DEV || import.meta.env.VITE_MOCK`. It covers the app's `.mocks/` and every wired addon's, so never glob `.mocks` or `node_modules` by hand.
+
+## Addon mocks
+
+An addon ships default mocks in its own package as `.mocks/<function>/<scenario>.json`, named without a namespace, and lists `.mocks` in `files`. An app that wires the addon as `studio` gets them as `studio:<function>`. The app's `.mocks/studio.<function>/` adds scenarios; one with the same name replaces the addon's, and a `default: true` in the app wins over the addon's default. Put mocks for an addon's functions in the addon, and only the app's own variations in the app.
+
+With `VITE_MOCK` set the plain hooks answer from the default mock too, so every state of every screen can be looked at without a backend.
+
+## Publishing
+
+A stub with no `{ featureFlag }` works in development and cannot be published. `usePikkuQueryStub('rpc:name', { featureFlag: 'flag' })` can, as long as the flag is declared in the project. Production never ships mock data; a stub there is a plain call that gets a 404.
+
+## Making a screen real
+
+`pikku mocks check` lists every stub and blocks the unflagged ones. For each stub: implement the function so its output matches the mock, replace the stub with `usePikkuQuery`, delete the flag if nothing else uses it. `pikku mocks diff` shows what changed, what is unused and what is dead; delete a mock directory it reports as removed.
+
+## Screens built on mocks
+
+The screens are the real app's: real components, `m.*()` for every string, the theme tokens. Only the data is sample. Make it look lived in: at least six realistic records where a page lists things, real copy, tinted and textured placeholder images instead of flat grey boxes. A button that leads nowhere real stays inert.

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

@@ -1,5 +1,12 @@
 # Adding a second frontend
 
+## Contents
+
+- Deciding it is two apps, not one
+- The second app
+- Sessions across two origins
+- Building the second app's screens
+
 Read this when the split you recorded in Phase 2 is "separate apps" and you have
 reached the changeset that needs the second one. **Not before.** Cloning
 `apps/app` materialises a directory of copied screens; doing it during planning
@@ -14,7 +21,7 @@ The split you are acting on should already be recorded, but this is the reasonin
 behind it — and the place people get it wrong is the third case at the bottom.
 
 **A group that comes in through its own front door gets its own app.** A role
-*inside* an app is not that: it changes which nav items and which buttons a person
+_inside_ an app is not that: it changes which nav items and which buttons a person
 sees, and lives in `useNavItems()` and the `permissions` on the function, not in a
 route subtree.
 
@@ -24,7 +31,7 @@ across the counter with an account of their own gets their own — the customer,
 tenant, the patient. One app is a real answer and often the right one.
 
 **The asymmetry that forces a split is sign-up.** Where staff accounts are created
-*for* people and customers create their own, the two need different sign-up, different
+_for_ people and customers create their own, the two need different sign-up, different
 onboarding and different session shape, and bending one app around both costs more
 than the second app does. Do not collapse two audiences into one app to save a build.
 
@@ -34,7 +41,7 @@ Never invent a person the notes do not name in order to reach two.
 
 Some people use the product with no account at all — ordering from a menu, booking a
 table, opening an invitation. They are not a third case, and **they do not get their
-own frontend**: an app is built around the personas who sign into it. What they get is
+own frontend**: an app is built around the virtual users who sign into it. What they get is
 the public route space every app already has.
 
 - **`/app/*` is the signed-in application.** One `beforeLoad` on `/app` bounces a
@@ -60,19 +67,19 @@ and someone else's record: if the invoices nav item is hidden but `listAllInvoic
 has no `permissions`, the app is wide open and the nav is decoration.
 
 Worth a scenario each, because they are two different claims: that a mechanic cannot
-*see* the invoices nav item, and that their call to an invoices RPC is *refused*. The
+_see_ the invoices nav item, and that their call to an invoices RPC is _refused_. The
 second is the one that catches a `permissions` field nobody wired.
 
 ## The second app
 
 ```bash
-pikku app new admin --serves staff --personas manager,mechanic
+pikku app new admin --serves staff --virtual-users 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
+`app: '<slug>'` onto each named virtual user in `defineVirtualUsers({…})`, adds the
 `frontends` entry to `pikku.config.json`, and re-runs `bun install`. `pikku app
 list` shows every app afterwards.
 
@@ -101,12 +108,12 @@ second app nobody needed, so the command will not create one when:
 - **An existing app already serves that audience.** People sharing an audience
   share ONE app and differ by nav and permitted actions. A new app is for a
   group the first app is not for.
-- **A named persona already signs into another app.** A person signs into one
+- **A named virtual user already signs into another app.** A person signs into one
   app; move them out first if they really belong here.
 - **The slug is what the plan calls an app that already exists.** The plan's
   FIRST app is the one the project starts with — only the apps after it get
   created.
-- **A persona is not in `definePersonas({…})`.** The app is built around who
+- **A virtual user is not in `defineVirtualUsers({…})`.** The app is built around who
   signs into it, so it is not created for people who do not exist yet.
 
 It also repairs its own half-states: a run that died between writing the
@@ -121,14 +128,14 @@ 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`.
+`frontends` entry: `pikku app native init <slug>`. The native-app reference
+(see SKILL.md) covers it.
 
 ### Scenarios across the two apps
 
-`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
+`pikku app new` stamps `app: '<slug>'` onto each virtual user it is given, and that
+field — not the `virtualUsers` array on the `frontends` entry — is what
+`@pikku/playwright` resolves a virtual user's base url from at sign-in. A virtual user
 with no `app` lands on the fallback frontend, which is the other app's screens
 with the right session on them.
 
@@ -145,15 +152,15 @@ single `appUrl` fallback, and the CLI takes `--app-url <app>=<url>,<app>=<url>`:
 
 Three things follow, and each one has cost a run:
 
-- **An actor is bound to ONE app for the whole run.** The resolution happens once,
-  at sign-in. A staff persona cannot be walked through the customer app to check
-  something is absent from it — drive that assertion with a persona who lives
+- **A virtual user is bound to ONE app for the whole run.** The resolution happens once,
+  at sign-in. A staff virtual user cannot be walked through the customer app to check
+  something is absent from it — drive that assertion with a virtual user who lives
   there, and say in the scenario's docblock why the witness is who it is. This
   binds a SIGNED-OUT scenario too, and that is where it bites: 'a visitor with no
-  session cannot open the admin desk' driven by a customer-app persona points the
+  session cannot open the admin desk' driven by a customer-app virtual user points the
   browser at a router with no such route at all, so what the assertion measures is
   a 404, not the guard — and on an app with a catch-all redirect to login it
-  passes while proving nothing. Pick the actor by which app owns the ROUTE, not by
+  passes while proving nothing. Pick the virtual user by which app owns the ROUTE, not by
   who should be refused, and drop their session instead.
 - **Every frontend needs its API proxy pointed at the API you are actually
   running.** `vite.config.ts` reads a variable (`VITE_API_PROXY`) with a default

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

@@ -1,5 +1,14 @@
 # Shipping an app as a desktop or Android app
 
+## Contents
+
+- The commands
+- Pick the mode first
+- What pikku owns and what you own
+- Plugins
+- The identifier
+- Building
+
 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

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

@@ -1,5 +1,12 @@
 # An app on top of an OpenAPI spec
 
+## Contents
+
+- Pick the auth mode
+- The auth-config file
+- The screens
+- Scenarios
+
 The spec becomes an addon first — the `pikku-addon` skill's
 `references/openapi.md` covers generating, verifying and checking it against
 the real API. This reference is the decision that shapes the app around it:
@@ -7,13 +14,13 @@ the real API. This reference is the decision that shapes the app around it:
 
 ## Pick the auth mode
 
-| The upstream…                                                            | Mode              | Command                       | Who signs in, and how                                   |
-| ------------------------------------------------------------------------ | ----------------- | ----------------------------- | ------------------------------------------------------- |
-| Is where the users already have accounts, and has a login endpoint      | Delegated         | `--auth-config <file>`        | Users sign in with their upstream login; no new account |
-| Takes a per-user API key, bearer token or basic auth                     | Per-user key      | (the default)                 | App account, then a Connect screen for the key          |
-| Uses OAuth2                                                              | Per-user OAuth    | (the default)                 | App account, then Connect via the OAuth consent         |
-| Is used on everyone's behalf with one key the business owns              | Shared secret     | `--auth shared`               | App account only; the key is a secret                   |
-| Takes no auth                                                            | None              | `--auth none`                 | App account only                                        |
+| The upstream…                                                      | Mode           | Command                | Who signs in, and how                                   |
+| ------------------------------------------------------------------ | -------------- | ---------------------- | ------------------------------------------------------- |
+| Is where the users already have accounts, and has a login endpoint | Delegated      | `--auth-config <file>` | Users sign in with their upstream login; no new account |
+| Takes a per-user API key, bearer token or basic auth               | Per-user key   | (the default)          | App account, then a Connect screen for the key          |
+| Uses OAuth2                                                        | Per-user OAuth | (the default)          | App account, then Connect via the OAuth consent         |
+| Is used on everyone's behalf with one key the business owns        | Shared secret  | `--auth shared`        | App account only; the key is a secret                   |
+| Takes no auth                                                      | None           | `--auth none`          | App account only                                        |
 
 Per-user is the default because the upstream then enforces each person's own
 permissions. A shared secret acts with one identity for everyone, so the
@@ -62,30 +69,30 @@ JSON, passed with `--auth-config`. Every field is optional except where noted.
 
 Top level — how every call authenticates:
 
-| Field          | Meaning                                                                                              |
-| -------------- | ---------------------------------------------------------------------------------------------------- |
-| `headerName`   | The header the API reads the token or key from. Setting it alone means a per-user API key            |
+| Field          | Meaning                                                                                                |
+| -------------- | ------------------------------------------------------------------------------------------------------ |
+| `headerName`   | The header the API reads the token or key from. Setting it alone means a per-user API key              |
 | `headerFormat` | `raw` sends the bare value, `bearer` prefixes `Bearer `. Default: bearer for `Authorization`, else raw |
-| `extraHeaders` | Static headers on every request, login included — for upstreams that route on a header               |
-| `delegated`    | Present when users sign in with their upstream login                                                 |
+| `extraHeaders` | Static headers on every request, login included — for upstreams that route on a header                 |
+| `delegated`    | Present when users sign in with their upstream login                                                   |
 
 `delegated`:
 
-| Field            | Meaning                                                                                                   |
-| ---------------- | --------------------------------------------------------------------------------------------------------- |
-| `loginPath`      | Required. The spec-relative login operation                                                               |
-| `loginMethod`    | Default `post`                                                                                            |
-| `credentials`    | What the sign-in form collects: `login` (a username or email), `email`, `password`, `apiKey`. Default `["email","password"]` |
-| `fields`         | The upstream's name for each credential, e.g. `{ "login": "username" }`                                  |
-| `encoding`       | `json`, `form` or `query` — how the login fields travel. Default `json`                                   |
-| `apiKeyHeader`   | The header an `apiKey` credential is sent in. Default `x-api-key`                                         |
-| `tokenPath`      | Required. Dot-path to the token in the login response                                                     |
-| `expiresAtPath`  | Dot-path to an epoch-seconds expiry. Defaults to the JWT's `exp` when claims come from the JWT            |
-| `identity`       | An operation that returns the signed-in user, called with the new token — for logins that return only a token |
-| `claims.source`  | `jwt`, `response` or `identity`. Default `identity` when `identity` is set, else `response`               |
-| `claims.*`       | Dot-paths to `externalId`, `email`, `name` (one path or several joined with a space), `role`, `tenantId`  |
-| `emailTemplate`  | Builds an email for an upstream user who has none: `{login}`, `{externalId}`, `{host}`. Such an address never claims an existing user |
-| `roles`          | Maps the raw `claims.role` value onto an app role; an unmapped value gets no role                          |
+| Field           | Meaning                                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `loginPath`     | Required. The spec-relative login operation                                                                                           |
+| `loginMethod`   | Default `post`                                                                                                                        |
+| `credentials`   | What the sign-in form collects: `login` (a username or email), `email`, `password`, `apiKey`. Default `["email","password"]`          |
+| `fields`        | The upstream's name for each credential, e.g. `{ "login": "username" }`                                                               |
+| `encoding`      | `json`, `form` or `query` — how the login fields travel. Default `json`                                                               |
+| `apiKeyHeader`  | The header an `apiKey` credential is sent in. Default `x-api-key`                                                                     |
+| `tokenPath`     | Required. Dot-path to the token in the login response                                                                                 |
+| `expiresAtPath` | Dot-path to an epoch-seconds expiry. Defaults to the JWT's `exp` when claims come from the JWT                                        |
+| `identity`      | An operation that returns the signed-in user, called with the new token — for logins that return only a token                         |
+| `claims.source` | `jwt`, `response` or `identity`. Default `identity` when `identity` is set, else `response`                                           |
+| `claims.*`      | Dot-paths to `externalId`, `email`, `name` (one path or several joined with a space), `role`, `tenantId`                              |
+| `emailTemplate` | Builds an email for an upstream user who has none: `{login}`, `{externalId}`, `{host}`. Such an address never claims an existing user |
+| `roles`         | Maps the raw `claims.role` value onto an app role; an unmapped value gets no role                                                     |
 
 Check it before building on it: start `pikku dev`, sign in once with
 `POST /api/auth/sign-in/delegated` as a real upstream user, and call an exposed
@@ -93,7 +100,7 @@ operation with the session. A wrong password must be refused. Keep real
 credentials in the environment, never in the config or a test.
 
 What the install wires for delegated mode — `pikkuDelegatedAuth` in
-`src/auth.ts`, the token stored per user, actors carrying it into scenarios — is
+`src/auth.ts`, the token stored per user, virtual users carrying it into scenarios — is
 in the `pikku-auth` skill's `references/better-auth.md`.
 
 ## The screens
@@ -107,13 +114,13 @@ in the `pikku-auth` skill's `references/better-auth.md`.
   call fails with `missing_credential`.
 - A `credential_rejected` error (`CredentialRejectedError`, 403) means the
   upstream refused the stored token: show the sign-in again (`reauth:
-  'sign-in'`) or the Connect screen (`reauth: 'connect'`), not a generic error.
+'sign-in'`) or the Connect screen (`reauth: 'connect'`), not a generic error.
 
 ## Scenarios
 
-A persona that signs in through the upstream needs an upstream credential to
-act with. The install adds `credentials` to `pikkuActor` in `src/auth.ts`, and
-at sign-in each actor stores `ACTOR_CREDENTIAL_<PERSONA>_<NAME>` from the
-environment (e.g. `ACTOR_CREDENTIAL_SALES_REP_DOLIBARR`). Without it every
+A virtual user that signs in through the upstream needs an upstream credential to
+act with. The install adds `credentials` to `pikkuVirtualUser` in `src/auth.ts`, and
+at sign-in each virtual user stores `VIRTUAL_USER_CREDENTIAL_<VIRTUAL_USER>_<NAME>` from the
+environment (e.g. `VIRTUAL_USER_CREDENTIAL_SALES_REP_DOLIBARR`). Without it every
 scenario step that reaches the upstream fails with `missing_credential`. The
-`pikku-scenario` skill's `references/personas.md` has the details.
+`pikku-scenario` skill's `references/virtual-users.md` has the details.

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

@@ -1,12 +1,22 @@
 # Build a platform showcase on Pikku
 
-**This skill is a delta. `references/app.md` is the base — read it and follow it in
-full.** Everything there applies: knowledge base first, personas and roles,
+## Contents
+
+- What "platform" means here
+- Choosing surfaces — during app workflow §5 (planning)
+- The surfaces
+- Coverage — where the bar is higher than the base workflow
+- The full gate
+- Deploy
+- Reference
+
+**This file is a delta: it adds to the app workflow, which stays the base and is
+followed in full.** Everything there applies: knowledge base first, virtual users and roles,
 changes grouped into changesets, planned then built one at a time, scenarios, design pass, deploy
-gates, Fabric-readiness. This file adds the surfaces that turn an app into a
+gates, deploy-readiness. This file adds the surfaces that turn an app into a
 demonstration of the platform, and says where each one slots into that workflow.
 
-Read `references/app.md` now, then come back. Do not blend the two into one plan —
+Do not blend the two into one plan —
 the phases below hang off its phases by number.
 
 ## What "platform" means here
@@ -23,7 +33,7 @@ or agent page, never the queue, scheduler or wire pages behind it.
 Budget the extra surfaces at one changeset each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
 
-## Choosing surfaces — during `references/app.md` §5 (planning)
+## Choosing surfaces — during app workflow §5 (planning)
 
 When you file the work, each surface below becomes its own changeset, ordered
 after the spine it depends on.
@@ -76,7 +86,7 @@ on a human or a timer and must survive a restart.
   gap in the middle? If every operation completes in one request, you do not need
   workflows and forcing one is noise.
 - **Prove it:** a scenario that starts the workflow, advances it as a second
-  persona, and asserts the end state. `pikku-react` covers driving it
+  virtual user, and asserts the end state. `pikku-react` covers driving it
   from the UI.
 - Three workflows ship with the template. Read them before writing yours.
 
@@ -123,7 +133,7 @@ generated typed client.
 - **Motivation test:** two people looking at the same thing at the same time, or
   a long operation whose progress matters.
 - **Prove it:** a browser scenario is the only honest proof — assert the second
-  persona's screen changed without a reload.
+  virtual user's screen changed without a reload.
 
 ### MCP — `pikku-wiring`
 
@@ -137,7 +147,7 @@ correct rather than a smell: a third-party caller needs a real REST shape.
 
 ### Locales — `pikku-i18n`
 
-`references/app.md` already requires every string to be a key. **Here, ship three
+The app workflow already requires every string to be a key. **Here, ship three
 locales, and make one of them RTL** (`pikku-i18n`). Two LTR locales prove the
 plumbing; an RTL one proves the layout, and it will find real bugs — mirrored
 icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
@@ -150,7 +160,7 @@ every added locale is cloned from, so three locales is `locales: ["en", …]` an
 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 `metaLocale` in
-`pikku.config.json`. See `references/app.md` §1a.
+`pikku.config.json`. The app workflow's §1a covers it.
 
 ### Emails — `pikku-emails`
 
@@ -177,7 +187,7 @@ the domain has a piece that genuinely belongs to no single app.
 
 ## Coverage — where the bar is higher than the base workflow
 
-`references/app.md` §7a already has the mechanics and the per-changeset habit:
+The app workflow's §7a already has the mechanics and the per-changeset habit:
 run the server instrumented, run the scenarios against it, read
 `coverage/scenario-coverage.json`, and triage every gap as a missing scenario, a
 function that should not exist, or a documented deferral. Do all of that here.
@@ -196,7 +206,7 @@ Two things change in a showcase:
 
 ## The full gate
 
-Everything in `references/app.md` §9, plus the checks a showcase should be able to
+Everything in the app workflow's §9, plus the checks a showcase should be able to
 survive:
 
 ```sh
@@ -218,7 +228,7 @@ bunx --bun pikku scenario run local --spawn --run browser
 
 ## Deploy
 
-`references/app.md` §9 covers the open-source paths (`--provider standalone`,
+The app workflow's §9 covers the open-source paths (`--provider standalone`,
 `cloudflare`, `aws`). One thing specific to this mode: **the extra surfaces are
 extra deploy units.** Workflow workers, queue workers, schedules and the events
 channel each appear in `pikku deploy plan` as their own entries. Read the plan
@@ -227,8 +237,7 @@ built.
 
 ## Reference
 
-- Base workflow: `references/app.md` — read it first, follow it in full
+- Base workflow: the app workflow, which this file adds to
 - Per-surface skills: `pikku-workflow`, `pikku-wiring`, `pikku-agent`,
   `pikku-i18n`, `pikku-emails`,
   `pikku-meta`, `pikku-addon`, `pikku-auth`, `pikku-services`
-- Every feature, end to end: https://pikkufabric.com/llm-all-features.txt