@pikku/skills 0.12.54 → 0.12.55

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

@@ -9,7 +9,7 @@
 - PHASE 1 — What the app is
 - 2. Write the knowledge graph — before any code
 - PHASE 2 — Who it is for, and what it is made of
-- 3. Declare the people — personas and roles
+- 3. Declare the people — virtual users and roles
 - 4. Declare the apps — one API, several frontends
 - PHASE 3 — The plan
 - 5. File the work as changes
@@ -19,23 +19,23 @@
 - 6a. Close the changeset against its plan, not against your memory
 - 7. Prove it — scenarios
 - 8. Make it look like someone designed it
-- 9. Ship it, and stay Fabric-ready
+- 9. Ship it, and stay deploy-ready
 - Reference
 
 You have a scaffolded project with skills installed. This skill owns everything
-from here: no Fabric account, no card, no hosted build — while keeping the
-project shaped so `pikku fabric init` later adopts it with zero rework.
+from here: no hosted account, no card, no hosted build — while keeping the
+project shaped so a hosting platform can adopt it later with zero rework.
 
 **Four phases, and you do not skip ahead:**
 
 1. Write the knowledge graph — what the app IS, before any code
-2. Declare the people and the apps — personas, roles, frontends
+2. Declare the people and the apps — virtual users, roles, frontends
 3. File the work as changes — grouped into changesets, in dependency order
 4. Build them one changeset at a time — each proven by a scenario before it merges
 
 The sections below follow those phases in order, and are meant to be worked
 through rather than searched: §0 bootstrap, §1-§1a the last questions and the
-three languages, §2 the knowledge graph, §3-§4 personas and apps, §5-§5a the
+three languages, §2 the knowledge graph, §3-§4 virtual users and apps, §5-§5a the
 changes and each changeset's technical plan, §6-§6a building and closing one,
 §7-§7a proving it, §8 design, §9 ship. Four of them have their own reference —
 scenarios, design, multi-app and ship, each listed in SKILL.md — to read at the
@@ -68,7 +68,7 @@ One command, run once, now — not later when you start building. It wires the
 `#pikku` import alias the generated code depends on. On a fresh scaffold `.pikku/`
 is empty, so **every command that touches codegen fails until this has run** —
 including ones you would reasonably reach for while still planning, like
-`pikku persona list`. Those failures look alarming (`Cannot find module
+`pikku virtual-user list`. Those failures look alarming (`Cannot find module
 '#pikku/workflow/pikku-workflow-types.gen.js'`, `Schema generation failed for 16
 schemas`) and they are nothing but this missing step.
 
@@ -81,7 +81,7 @@ Ask **three to five** questions that actually change the schema or the screens,
 in one message. Then stop; do not interview the user.
 
 - **Who uses it — who are the distinct kinds of people?** Ask this however small
-  the app is. The answer becomes §3's personas and roles, and you build only the
+  the app is. The answer becomes §3's virtual users and roles, and you build only the
   roles they name.
 - **What are the two or three core objects?**
 - **What is the main thing someone does on their first visit?** This answer
@@ -121,11 +121,11 @@ A brief saying "the entire UI is German" is about **one** of these. Getting this
 wrong has already shipped a project that can never add a second language, so
 settle all three explicitly before you write code.
 
-| Axis            | What it covers                                                                                                                 | Where it goes                                                                        |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                              | Nowhere — **always English**, no setting, not negotiable                             |
-| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions | `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 |
+| 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 virtual user 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 `metaLocale`. Identifiers are the surface the generated `#pikku/*`
@@ -160,7 +160,7 @@ A German medical portal, correctly:
 ```jsonc
 // project.inlang/settings.json
 { "baseLocale": "en", "locales": ["en", "de"] }
-// apps/app/src/i18n/active.json   (or: fabric i18n --default-locale de)
+// apps/app/src/i18n/active.json
 { "defaultLocale": "de" }
 // pikku.config.json
 { "metaLocale": "de" }
@@ -228,14 +228,14 @@ bunx --bun pikku knowledge validate
 
 ## PHASE 2 — Who it is for, and what it is made of
 
-## 3. Declare the people — personas and roles
+## 3. Declare the people — virtual users and roles
 
 The answer to "who uses it" becomes code, in one file:
-`packages/functions/src/personas.ts`. It ships with a single `visitor`; add the
+`packages/functions/src/virtual-users.ts`. It ships with a single `visitor`; add the
 people the user named, and the roles they imply.
 
 ```typescript
-import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+import { defineVirtualUsers } from '#pikku/scopes/pikku-virtual-users.gen.js'
 import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
@@ -251,7 +251,7 @@ defineSystemRole({
   },
 })
 
-definePersonas({
+defineVirtualUsers({
   visitor: {
     name: 'Visitor',
     jobTitle: 'Synthetic health-check user',
@@ -282,18 +282,18 @@ definePersonas({
 })
 ```
 
-- **Keep `visitor`.** The shipped scenarios name `actors.visitor`, and PKU677
-  requires a browser step's actor to be a literal `actors.<name>`. Removing it
-  stops `actors.visitor` type-checking, which fails `pikku all`, and nothing you
+- **Keep `visitor`.** The shipped scenarios name `virtualUsers.visitor`, and PKU677
+  requires a browser step's virtual user to be a literal `virtualUsers.<name>`. Removing it
+  stops `virtualUsers.visitor` type-checking, which fails `pikku all`, and nothing you
   write after that registers.
-- **One `definePersonas` call for the whole project.** Codegen builds the
-  `PersonaId` union from it, materialises one scenario actor per person, and
+- **One `defineVirtualUsers` call for the whole project.** Codegen builds the
+  `VirtualUserId` union from it, materialises one scenario virtual user per person, and
   seeds a user row each. A second call site is a second answer to "who uses this
   app".
 - **`roles` is typechecked against `defineSystemRole`.** An undeclared role is a
   build error rather than a runtime surprise.
-- **Never write an email address.** Each is derived from the persona id and
-  `scenarios.emailDomain` in `pikku.config.json` — `visitor@actors.local`.
+- **Never write an email address.** Each is derived from the virtual user id and
+  `scenarios.emailDomain` in `pikku.config.json` — `visitor@virtualuser.local`.
   Hand-writing one is how a run signs in as somebody who was never created.
 - **Declare a second person of the same kind** whenever the rule is ownership
   (`bilal` above). "You see yours, not theirs" is not testable with one owner,
@@ -305,14 +305,14 @@ definePersonas({
   in the function's `permissions` field (§6), never in the body. Read the
   `pikku-auth` skill.
 
-`pikku persona list` shows who is declared and `pikku roles audit` reports roles
+`pikku virtual-user list` shows who is declared and `pikku roles audit` reports roles
 the database still holds that code no longer declares — both need §0's bootstrap
 to have run, and both are worth a look once it has.
 
 **One warning about the scaffold's own notes:** `knowledge/index.md` may claim
-the people live in `pikku.config.json`, put there by a persona command.
-That is stale. In this template they live in `personas.ts` as above, and
-`pikku.config.json` carries no personas key at all — only `scenarios.emailDomain`.
+the people live in `pikku.config.json`, put there by a virtual user command.
+That is stale. In this template they live in `virtual-users.ts` as above, and
+`pikku.config.json` carries no virtual users key at all — only `scenarios.emailDomain`.
 Trust the file you can read over the note describing it.
 
 ## 4. Declare the apps — one API, several frontends
@@ -374,7 +374,7 @@ What a change is:
 - **One commit's worth.** "The owner sees this month's arrears" is a change,
   or a few. "Add the database schema" is not; it is a step inside one.
 - **It ends in something a person can do**, in a browser, signed in as a named
-  persona. If you cannot say what they see when it is done, that is a
+  virtual user. If you cannot say what they see when it is done, that is a
   `questions/` note, not a change.
 
 If §1's screen mock was made — approved, or drawn because nobody answered —
@@ -454,7 +454,7 @@ while the plan is short.
    configuration and belongs in a migration, not here.
    Do this generously and do it now: an empty app demos badly and critiques
    badly, and you cannot judge a screen's hierarchy, overflow, or truncation
-   against zero rows. Seed rows each persona sees differently — with an ownership
+   against zero rows. Seed rows each virtual user sees differently — with an ownership
    rule that means seeding rows for the _second_ owner too.
 3. **Functions.** One `pikkuFunc` per `*.function.ts`. Mark it `expose: true` and
    Pikku generates the typed RPC client and the React Query hooks the UI calls;
@@ -537,28 +537,26 @@ Rules that are not optional:
   tables. A domain table with one of those names — a class _session_, a drop-in
   _session_ — collides in the migration. Name it for the domain instead
   (`evening`, `class_meeting`) and keep the word in the UI copy.
-- The template's `/` redirects to `/app`, so the login screen — and its "Sign in
-  as …" switcher — is what a signed-out visitor sees first. Replace `/` with a
-  public homepage and that stops being true: mount `<DevActorSwitcher />` in the
-  public layout as well, or a reviewer lands on a site with no way in.
+- The template's `/` redirects to `/app`, so the login screen is what a
+  signed-out visitor sees first. Replace `/` with a public homepage and a
+  reviewer lands on a site with no way in: link it to the login screen.
 
-Before the first run, make sure `.env` at the project root holds the two
-secrets the local stack needs. `bun run dev` appends whichever is missing, but
-check anyway — a project scaffolded from an older template, or a `.env` copied
-in from elsewhere, can lack one, and neither failure names the variable:
+Before the first run, make sure `.env` at the project root holds the secret
+the local stack needs. `bun run dev` appends it if missing, but check anyway —
+a project scaffolded from an older template, or a `.env` copied in from
+elsewhere, can lack it, and the failure does not name the variable:
 
 - `BETTER_AUTH_SECRET` — without it the first sign-up is a 500.
-- `SCENARIO_ACTOR_SECRET` — without it `/api/auth/sign-in/actor` is disabled:
-  every scenario fails at sign-in before its first step, and the "Sign in as …"
-  switcher renders nothing.
+
+Virtual user sign-in needs nothing in `.env`: `pikku dev` creates its own key
+pair and hands the app the public half.
 
 ```sh
 grep -q '^BETTER_AUTH_SECRET=' .env 2>/dev/null || echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
-grep -q '^SCENARIO_ACTOR_SECRET=' .env 2>/dev/null || echo "SCENARIO_ACTOR_SECRET=$(openssl rand -base64 32)" >> .env
 ```
 
 `.env` is gitignored and local only — never commit it. A deployed stage gets its
-secrets from the platform (`pikku fabric secrets`), not from this file.
+secrets from the hosting platform, not from this file.
 
 Then run it:
 
@@ -571,13 +569,10 @@ 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 "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.
+yourself.** The frontend needs 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 every request goes to the wrong API.
 
 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
@@ -661,8 +656,8 @@ only when there is nothing to hang a check on.
 
 ## 7. Prove it — scenarios
 
-A scenario is a user journey run as one of your personas, over the real
-transport, with that persona's session. It is the only kind of test worth writing
+A scenario is a user journey run as one of your virtual users, over the real
+transport, with that virtual user's session. It is the only kind of test worth writing
 here, because a passing one proves the app works the way a signed-in person
 experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
 green — and every scenario a changeset's plan names becomes one more.
@@ -674,7 +669,7 @@ proves nothing:
 
 - the shape of a scenario, and `do` vs `given`/`when`/`then`
 - what survives DSL extraction — a `then` in `return` position asserts nothing,
-  and a shared setup helper credits its steps to the wrong actor
+  and a shared setup helper credits its steps to the wrong virtual user
 - what to assert — refusals must read the REASON, totals must be deltas, and the
   assertion nobody writes is the row count
 - living without a state reset: the suite must be green on its SECOND run
@@ -688,7 +683,7 @@ bunx --bun pikku scenario run local --spawn                  # server-side, the
 bunx --bun pikku scenario run local --spawn --run browser    # the same journeys, driven as a human
 ```
 
-In a multi-app project that one run covers both frontends: each persona carries
+In a multi-app project that one run covers both frontends: each virtual user carries
 its own `app` and `@pikku/playwright` resolves the base url from the
 environment's `appUrls` map, so there is no second environment to run.
 
@@ -738,7 +733,7 @@ Three separate jobs, and conflating them is why open-source builds come out
 looking like the template:
 
 - **Direction** — deciding what it should look like. **No open-source tool does
-  this.** Fabric has `fabric-theme`; you have §1's answer and 8a below.
+  this.** A hosting platform may offer one; you have §1's answer and 8a below.
 - **Execution** — whether the screens actually realise that direction, or
   default to whatever component was nearest. No theme does this, and it is where
   "works but looks like nobody decided anything" comes from.
@@ -831,13 +826,13 @@ seven copies deep. Run `pikku db reset` and restart the dev server before you
 screenshot anything — a screen judged against that data gets designed for a
 problem it does not have.
 
-## 9. Ship it, and stay Fabric-ready
+## 9. Ship it, and stay deploy-ready
 
 When the queue is empty, `pikku knowledge gaps` lists nothing and the scenarios are green, read
 the ship reference (see SKILL.md). It carries the open-source deploy paths (`--provider
 standalone`, `cloudflare`, `aws`), how to serve several frontends behind one
-API, the pre-release gate to run, and the contract that keeps `pikku fabric init`
-a one-command import later rather than a migration.
+API, the pre-release gate to run, and the contract that keeps the project
+importable by a hosting platform later rather than a migration.
 
 The app is not handed over without its user guide. The scenarios you wrote are
 already its skeleton: read **pikku-guide**, write one page per audience citing
@@ -864,8 +859,8 @@ says when to open each one:
 - design — committing to a design direction, and how to tell whether the
   screens realise it. Read BEFORE the first screen (§6), not at §8
 - theming — authoring the theme (§8a)
-- ship — deploying, and the Fabric-readiness contract (§9)
+- ship — deploying, and the deploy-readiness contract (§9)
 - Sibling skills: `pikku-knowledge` (§2), `pikku-auth` (§3),
-  `pikku-scenario` (§7, §7a), `pikku-deploy` and `pikku-fabric` (§9)
+  `pikku-scenario` (§7, §7a), and `pikku-deploy` (§9)
 - Project conventions written by the template: `AGENTS.md`
 - Doing less than this: the quick reference. Doing more: the platform reference (both in SKILL.md).

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

@@ -28,7 +28,7 @@ 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,
@@ -46,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 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, 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.
@@ -98,7 +98,7 @@ 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 *shadcn's*, at the
+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?
@@ -138,8 +138,8 @@ 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 shadcn components
@@ -204,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
@@ -240,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.
@@ -255,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
 
@@ -281,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
@@ -292,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.
 
@@ -365,5 +365,5 @@ first one.
   accent is not — the surest sign the neutrals were inherited rather than
   chosen. The theming reference (see SKILL.md) covers it.
 - It looks like the last app you built.
-- It looks like stock shadcn. Not *built with* shadcn, 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

@@ -271,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
@@ -290,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

@@ -8,6 +8,12 @@ Read this when a screen needs data no function returns yet, or returns in a diff
 - 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

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

@@ -21,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.
 
@@ -31,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.
 
@@ -41,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
@@ -67,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.
 
@@ -108,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
@@ -133,9 +133,9 @@ Packaging it as a desktop or Android app is a separate step, on the same
 
 ### 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.
 
@@ -152,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