@pikku/skills 0.12.54 → 0.12.56

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

@@ -14,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
@@ -69,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
@@ -100,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
@@ -114,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

@@ -11,9 +11,9 @@
 - 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, personas and roles,
+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.
 
 Do not blend the two into one plan —
@@ -86,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.
 
@@ -133,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`
 
@@ -241,4 +241,3 @@ built.
 - 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

package/skills/pikku-build/references/post-clone.md

@@ -35,5 +35,5 @@ part of cleanup — this step is project hygiene, not a build.
 Templates are structure-only starting points. Without this pass, clones carry a
 misleading README, a placeholder package name, and (historically) a gitignored
 lockfile — all of which leak template assumptions into a real project. Running
-it immediately after clone keeps every Pikku project, OSS or Fabric, starting
+it immediately after clone keeps every Pikku project starting
 from a clean, honest baseline.

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

@@ -4,7 +4,7 @@
 
 - Agent Operating Procedure
 - 1. One question, then build
-- 2. Personas — 60 seconds, not optional
+- 2. Virtual users — 60 seconds, not optional
 - 3. Build
 - 4. Look at it — actually
 - 5. One smoke scenario
@@ -15,12 +15,12 @@ signed-in screens in as few steps as possible.
 
 **What this mode deliberately skips**, and what that costs:
 
-| Skipped | Cost |
-|---|---|
-| `knowledge/` | Another agent — or you next week — cannot resume this. Nothing records *why*. |
-| Changesets and plans | No build order, no per-piece proof. Fine at this size, painful past it. |
-| Design direction | It will look like the template. |
-| Refusal scenarios | Access control is asserted, not proven. |
+| Skipped              | Cost                                                                          |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `knowledge/`         | Another agent — or you next week — cannot resume this. Nothing records _why_. |
+| Changesets and plans | No build order, no per-piece proof. Fine at this size, painful past it.       |
+| Design direction     | It will look like the template.                                               |
+| Refusal scenarios    | Access control is asserted, not proven.                                       |
 
 **Say this out loud to the user, once, when you finish.** A quick build that gets
 mistaken for a real one is the only way this mode does damage. §6 is the way out.
@@ -55,9 +55,9 @@ message catalogue only: add the locale and set `defaultLocale`, and leave
 `baseLocale` at `en`. the app workflow's §1a has the three axes in full; getting
 them confused is how a project ends up unable to add a second language.
 
-## 2. Personas — 60 seconds, not optional
+## 2. Virtual users — 60 seconds, not optional
 
-`packages/functions/src/personas.ts` ships with a `visitor`. Add one persona per
+`packages/functions/src/virtual-users.ts` ships with a `visitor`. Add one virtual user per
 kind of person, plus **a second one of the primary kind** — that is what makes
 "you see yours, not theirs" observable when you click around.
 
@@ -65,10 +65,14 @@ kind of person, plus **a second one of the primary kind** — that is what makes
 rule, and it lives in each function's `permissions`, not in a role:
 
 ```typescript
-import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+import { defineVirtualUsers } from '#pikku/scopes/pikku-virtual-users.gen.js'
 
-definePersonas({
-  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+defineVirtualUsers({
+  visitor: {
+    name: 'Visitor',
+    jobTitle: 'Synthetic health-check user',
+    account: {},
+  },
   amina: { name: 'Amina', jobTitle: 'Gardener', account: {} },
   bilal: { name: 'Bilal', jobTitle: 'Gardener', account: {} },
 })
@@ -78,16 +82,28 @@ definePersonas({
 named:
 
 ```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({
-  owner: { displayName: 'Owner', description: 'Sees only their own rows', scopes: [] },
-  tenant: { displayName: 'Tenant', description: 'Sees only their own tenancy', scopes: [] },
+  owner: {
+    displayName: 'Owner',
+    description: 'Sees only their own rows',
+    scopes: [],
+  },
+  tenant: {
+    displayName: 'Tenant',
+    description: 'Sees only their own tenancy',
+    scopes: [],
+  },
 })
 
-definePersonas({
-  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+defineVirtualUsers({
+  visitor: {
+    name: 'Visitor',
+    jobTitle: 'Synthetic health-check user',
+    account: {},
+  },
   amina: { name: 'Amina', jobTitle: 'Owner', roles: ['owner'], account: {} },
   bilal: { name: 'Bilal', jobTitle: 'Owner', roles: ['owner'], account: {} },
   chidi: { name: 'Chidi', jobTitle: 'Tenant', roles: ['tenant'], account: {} },
@@ -97,10 +113,10 @@ definePersonas({
 Two owners in both examples, deliberately: one owner cannot demonstrate that
 owners are separated from each other.
 
-- **Keep `visitor`.** The shipped scenarios name `actors.visitor`; removing it
+- **Keep `visitor`.** The shipped scenarios name `virtualUsers.visitor`; removing it
   fails `pikku all` and nothing you write after that registers.
-- **One `definePersonas` call for the whole project.**
-- **Never write an email address** — each is derived from the persona id and
+- **One `defineVirtualUsers` call for the whole project.**
+- **Never write an email address** — each is derived from the virtual user id and
   `scenarios.emailDomain` in `pikku.config.json`.
 - `roles` is typechecked against `defineSystemRole`; an undeclared role is a
   build error.
@@ -122,7 +138,7 @@ Then, in this order — it is the order codegen depends on:
    the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. It is local only:
    no deploy applies it, so anything the app cannot run without belongs in a
    migration instead. **Be generous, and
-   seed rows for both personas.** An empty app demos badly, and you cannot see a
+   seed rows for both virtual users.** An empty app demos badly, and you cannot see a
    layout break against zero rows.
 3. **Functions** — one `pikkuFunc` per `*.function.ts`, `expose: true`. Pikku
    generates the typed RPC client and React Query hooks; you do NOT write HTTP
@@ -160,17 +176,15 @@ than they save:
   keystroke now and a rewrite later.
 - Never hardcode a host or port — the API base resolves to same-origin `/api`.
 
-Before the first run, make sure `.env` holds both local secrets — `bun run dev`
-appends missing ones, but an older scaffold or a copied `.env` may not have them:
+Before the first run, make sure `.env` holds the local secret — `bun run dev`
+appends it if missing, but an older scaffold or a copied `.env` may not have it:
 
 ```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
 ```
 
 Never commit `.env`. Then run it — through `bun run dev`, never `vite` on its
-own, because the dev script is what hands the frontend the persona list for the
-"Sign in as …" switcher; without it the switcher silently renders nothing:
+own, because the dev script is what points the frontend at your API:
 
 ```sh
 bun run prebuild && bun run dev
@@ -200,18 +214,31 @@ app a look — that is the app workflow's §8a.
 
 ## 5. One smoke scenario
 
-Not the full ladder — one journey, end to end, as a real persona, so the app has
+Not the full ladder — one journey, end to end, as a real virtual user, so the app has
 at least one thing that stays true.
 
 ```typescript
 import { pikkuScenario } from '#pikku/scenarios'
 
-export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>({
+export const ownerCreatesAndSeesItScenario = pikkuScenario<
+  void,
+  { id: string }
+>({
   title: 'An owner creates a thing and sees it',
   tags: ['scenario', 'smoke'],
-  func: async (_services, _data, { scenario, actors }) => {
-    const row = await scenario.do('creates', 'createThing', { name: 'first' }, { actor: actors.amina })
-    await scenario.then('sees it listed', 'thingShowsInList', { id: row.id }, { actor: actors.amina })
+  func: async (_services, _data, { scenario, virtualUsers }) => {
+    const row = await scenario.do(
+      'creates',
+      'createThing',
+      { name: 'first' },
+      { virtualUser: virtualUsers.amina }
+    )
+    await scenario.then(
+      'sees it listed',
+      'thingShowsInList',
+      { id: row.id },
+      { virtualUser: virtualUsers.amina }
+    )
     return { id: row.id }
   },
 })
@@ -221,9 +248,9 @@ export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>
   `pikkuScenarioStep`.** An RPC name in a `then` will not resolve.
 - **Every scenario must assert.** A ladder with no `then` is a PKU680 critical —
   it fails `pikku all`, stopping codegen rather than a test.
-- **`SCENARIO_ACTOR_SECRET` must be in `.env`** (above). Without it
-  `/api/auth/sign-in/actor` is disabled and every scenario fails at sign-in, for
-  a reason that reads like an auth bug.
+- **Run scenarios against a `pikku dev` server.** `pikku dev` creates the virtual
+  user signing key; without a running or previously started dev server every
+  scenario fails at sign-in, for a reason that reads like an auth bug.
 - **There is no state reset** — scope what you create to unique ids.
 
 Keep the three shipped scenarios in `packages/functions/test/scenarios/` green.
@@ -246,8 +273,8 @@ to the app workflow (the app reference, see SKILL.md) and do this, in order:
    `decisions/` for what you chose silently, `questions/` for what you guessed
    at. Then `pikku knowledge index && pikku knowledge validate`.
 2. Backfill an entity note for each thing the app holds, so `pikku knowledge
-   gaps` has something to measure against.
-3. Write the refusal scenarios — the ones proving one persona cannot reach
+gaps` has something to measure against.
+3. Write the refusal scenarios — the ones proving one virtual user cannot reach
    another's rows. This is the gap that matters most.
 4. Then pick up the app workflow at its §4 (apps) or §5 (changes) for
    anything new.

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

@@ -11,8 +11,8 @@
 - Running them
 - Coverage — which functions have actually been run
 
-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 here, because a passing one proves the
+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.
 
 The traps below all cost a real changeset a red run, and most of them are invisible on the run that
@@ -39,26 +39,27 @@ import { pikkuScenario } from '#pikku/scenarios'
 
 export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
   title: 'A tenant reports a fault and the owner sees it',
-  description: 'The report lands on the owning landlord’s queue, and nobody else’s',
+  description:
+    'The report lands on the owning landlord’s queue, and nobody else’s',
   tags: ['scenario', 'maintenance'],
-  func: async (_services, _data, { scenario, actors }) => {
+  func: async (_services, _data, { scenario, virtualUsers }) => {
     const report = await scenario.do(
       'reports a broken boiler',
       'createMaintenanceReport',
       { summary: 'No hot water' },
-      { actor: actors.chidi },
+      { virtualUser: virtualUsers.chidi }
     )
     await scenario.then(
       'appears on the owner’s queue',
       'reportShowsOnQueue',
       { id: report.id },
-      { actor: actors.amina },
+      { virtualUser: virtualUsers.amina }
     )
     await scenario.then(
       'is invisible to the other owner',
       'reportIsNotVisible',
       { id: report.id },
-      { actor: actors.bilal },
+      { virtualUser: virtualUsers.bilal }
     )
     return { id: report.id }
   },
@@ -70,10 +71,10 @@ export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
 (server-side by default, plus a `browser` one that drives the page). Reaching for an RPC name in a
 `then` will not resolve.
 
-**`SCENARIO_ACTOR_SECRET` must be in `.env`** (the app workflow's §6, before the first run). Without it
-`/api/auth/sign-in/actor` is disabled — every scenario then fails at sign-in, before its first step,
-for a reason that reads like an auth bug. `pikku scenario run` reads it from the environment, so
-source `.env` first (`set -a && . ./.env && set +a`) when you run outside `bun run dev`.
+**Scenarios sign in with the key `pikku dev` created.** Start `pikku dev` once in the project (it writes
+`.pikku-runtime/virtual-user/signing.key`); without that key every scenario fails at sign-in, before its
+first step, for a reason that reads like an auth bug. Against a deployed stage export
+`VIRTUAL_USER_SIGNING_KEY`, which that stage's deployer holds.
 
 ---
 
@@ -99,7 +100,7 @@ each half of that rule, because the first half does not imply the second.
 
 **Write each scenario's setup out in full rather than sharing a local helper.** A helper holding
 setup steps does not fail extraction — the steps are recorded and the suite goes green — but the
-extractor cannot bind an `actor` that arrives as a function parameter, so the transcript credits
+extractor cannot bind an `virtualUser` that arrives as a function parameter, so the transcript credits
 every setup step to whoever the last literal binding named. Seven permission scenarios here read
 "henrik sets up her company Salon Nordlicht" in a suite whose whole point was that the company is
 finja's. A scenario body is a recorded document, and the duplication is the price of it saying who
@@ -109,7 +110,7 @@ did what.
 
 ## What to assert
 
-**Write the refusals, and assert WHY.** One persona reaching for another's row has to be rejected,
+**Write the refusals, and assert WHY.** One virtual user reaching for another's row has to be rejected,
 and that rejection is a scenario — it is how you prove access control instead of asserting it. But
 only if the step reads the reason: "not ok" is also what a malformed request returns, so a refusal
 step that stops at the status code passes on a call the function never even ran. One here posted
@@ -150,7 +151,7 @@ second run starts where its first one stopped.
 **Run the suite twice and require the second run green.** A suite that only passes on a fresh
 database is a suite that passes once. Two corollaries, both of which cost a changeset a red run:
 
-- **Name nothing a setup step might already own.** `setsUpHerCompany` returns the company that actor
+- **Name nothing a setup step might already own.** `setsUpHerCompany` returns the company that virtual user
   already has rather than renaming it, so a later step passed the literal name it had asked for and
   was told no such company exists. Read the name, slug or id back off the step's output and pass
   THAT.
@@ -187,7 +188,7 @@ scenarios that had been green for months.
 
 **A selector on IDENTITY alone rots the same way once rows gain a lifecycle.** One reused the first
 licence assigned to an email regardless of its state, which was correct until a new changeset's
-refusal scenarios left that actor holding cancelled ones — it then handed back a dead licence, read
+refusal scenarios left that virtual user holding cancelled ones — it then handed back a dead licence, read
 as success, and failed a scenario two changesets older at a step that needed a live one.
 
 **A step's input is a recorded contract, and it does not take a version.** Widening one — an extra
@@ -251,7 +252,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.
 

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

@@ -1,9 +1,9 @@
-# Shipping, and staying Fabric-ready
+# Shipping, and staying deploy-ready
 
 ## Contents
 
 - Ship it — open source, no platform
-- Staying Fabric-ready
+- Staying deploy-ready
 
 Read this when the changes queue is empty and the scenarios are green — it is
 the last phase, and nothing in it is needed before then.
@@ -86,7 +86,7 @@ Changing the strategy renames units, and a unit name is what a queue consumer, a
 scheduled task and a `dependsOn` point at. The manifest rewrites all three, but
 anything holding a unit name outside the manifest does not follow. Units dropped
 from the manifest are not deleted by OSS `deploy()` either (pikkujs/pikku#543) —
-fabric sweeps its dispatch namespace after each deploy, plain pikku leaves the
+a hosting platform may sweep them after each deploy, plain pikku leaves the
 old workers in place.
 
 `tags` matches the tags a function inherits from its wirings — `wireHTTP({ ...,
@@ -158,23 +158,22 @@ lint over function return types, catching a `Pii`/`Secret` field that leaks
 through an exposed function. Expensive, so run it before a release rather than on
 every save — but run it.
 
-## Staying Fabric-ready
+## Staying deploy-ready
 
 Everything above is open source. This is the contract that keeps
-`pikku fabric init` a one-command import later, instead of a migration.
+the project a one-command import for a hosting platform later, instead of a migration.
 
 - **`frontends` in `pikku.config.json` describes reality.** Every app has an
   entry with the right `cwd`, `kind` and `dev` (`command`, `port`); exactly one
-  is `primary`; `serves` and `personas` name real personas from the personas
-  section.
-- **`fabric.projectId` in `pikku.config.json` is optional.** Leave it out unless you
-  have the real id; the CLI writes it after finding the project from the git
-  remote. Do not invent a value.
-- **One `definePersonas` call**, every persona reachable through exactly one
-  frontend. Fabric materialises these as its virtual users; a persona nobody
+  is `primary`; `serves` and `virtualUsers` name real virtual users declared in
+  `defineVirtualUsers`.
+- **`cloud.projectId` in `pikku.config.json` is optional.** Leave it out unless you
+  have the real id; the CLI writes it once the project is linked. Do not invent a value.
+- **One `defineVirtualUsers` call**, every virtual user reachable through exactly one
+  frontend. A hosting platform may materialise these as its users; a virtual user nobody
   serves imports as a person with no way in.
 - **`knowledge/` passes `validate`, and `pikku knowledge gaps` lists nothing.** This is
-  the part Fabric itself reads and continues from.
+  the part a hosting platform reads and continues from.
 - **Every plan under `knowledge/plans/` passes `pikku knowledge plan progress`.**
   A merged changeset is a claim; the plan reconciled against the generated meta
   is the check. Anything the first pass still owes is either built now or deferred with
@@ -192,7 +191,6 @@ Everything above is open source. This is the contract that keeps
   the SDK.
 - **`pikku validate` is clean**, and `pikku all` has no critical diagnostics.
 
-What you deliberately do NOT do: run any `pikku fabric` subcommand, add a card,
-or link a project. None of it is needed to build, test, critique, or deploy — it
-is needed the day the user wants Fabric to host and build it, and on that day, if
+What you deliberately do NOT do: link a project to a hosting platform. None of it is needed to build, test, critique, or deploy — it
+is needed the day the user wants one to host and build it, and on that day, if
 this section holds, that day is one command long.

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

@@ -11,8 +11,8 @@ Read this at the design step, once you have a direction to turn into a theme —
 whether the user described one in words, handed you a reference, or ran their own
 design step whose output you are implementing.
 
-Nothing in the open-source toolchain authors a theme for you. Fabric has the
-`fabric-theme` tool; without it, hand-authoring is the route, and it is a small
+Nothing in the open-source toolchain authors a theme for you. A hosting
+platform may offer a theme tool; without it, hand-authoring is the route, and it is a small
 job done in JSON.
 
 ## Where the look lives

package/skills/pikku-changes/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-changes
-description: 'Work a project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku changes wait|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against a stage", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
-installGroups: [fabric]
+description: 'Work a project''s changes queue — the todo list someone filed by circling things in the running app. Covers `pikku changes wait|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the changes against a stage", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage.'
 ---
 
 # Working a changes queue
@@ -44,7 +43,7 @@ something changed. `wait` does the waiting and exits only when there is work.
    | ---- | ------------------------------------------------------ | ----------------------------------------------- |
    | 0    | work printed (claimed, and/or `Answered`)              | work it, then step 3                            |
    | 2    | `--timeout`/`--once` found nothing                     | stop, or restart `wait`                         |
-   | 3    | session refused                                        | tell the user to run `pikku fabric login`; stop |
+   | 3    | auth refused                                           | relay the CLI's message; stop                   |
    | 1    | anything else                                          | report the message; stop                        |
 
 3. For each item: `show` → fix → commit → `done`; or `ask` and move on; or `reply`
@@ -62,6 +61,25 @@ group's lease, done — and when a held or leased item is **claimable at** (a lo
 cannot be taken. For held items, run `wait --claim` rather than retrying. The lease is 30 minutes
 (`--lease-minutes`); an abandoned claim returns to the queue by itself.
 
+## The board
+
+Every change sits in one column: backlog, ready, in progress, needs answer, done.
+`list` prints them left to right with counts (`--include-done` adds done). A claim is
+not a column: it lives on the changeset's lease, so a change still in progress whose
+lease lapsed shows as `abandoned`, and `next` and `wait` pick it up again.
+
+`claim`, `wait` and `next` never take a backlog change; `claim` on one is refused
+with a 409. Move it first, and only when the person asked for it to be worked:
+
+```bash
+pikku changes ready 5        # backlog → ready
+pikku changes backlog 5      # shelve it again
+pikku changes start 3 4      # ready → in progress, the work has begun
+```
+
+The backlog lives in the local queue only; a project whose changes are in Pikku
+Studio Cloud refuses `backlog`, `ready` and `file --backlog`.
+
 ## Changesets
 
 Group related items into changesets and claim each one as a group, saying which tables it touches —
@@ -187,5 +205,3 @@ Branch and commit default to the checkout you are in — run it there, never typ
 the item's commit by its `Change-Id` trailer, so close items in any order.
 An item you decided not to do is not `done`: `reply` with why and leave it for a
 human to dismiss.
-
-Registering writes with Fabric needs the `changes:project:write` scope.