@pikku/skills 0.12.52 → 0.12.55

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

@@ -1,16 +1,26 @@
 # Build an app on Pikku, fast
 
+## Contents
+
+- Agent Operating Procedure
+- 1. One question, then build
+- 2. Virtual users — 60 seconds, not optional
+- 3. Build
+- 4. Look at it — actually
+- 5. One smoke scenario
+- 6. Hand it over honestly
+
 You have a scaffolded project with skills installed. Get it to working, seeded,
 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.
@@ -42,12 +52,12 @@ Identifiers are English in every project, whatever the product's market;
 `template`, which the Console renders) stays `en` unless the user already told
 you otherwise. If the request says the app's UI is not English, that is the
 message catalogue only: add the locale and set `defaultLocale`, and leave
-`baseLocale` at `en`. `references/app.md` §1a has the three axes in full; getting
+`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.
 
@@ -55,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: {} },
 })
@@ -68,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: {} },
@@ -87,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.
@@ -112,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
@@ -150,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
@@ -186,22 +210,35 @@ taller than the viewport. It is the most likely width your demo gets opened at.
 If you have five spare minutes, `npx impeccable install` (Node 22.18+) scores
 each screen against interaction heuristics and names what is wrong. Feed it
 screenshots, not source. It will polish the default look; it will not give the
-app a look — that is `references/app.md` §8a.
+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 }
   },
 })
@@ -211,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.
@@ -230,16 +267,16 @@ it is seeded with, and that this is a quick build — no knowledge base, no
 changesets, no design pass, access control clicked-through rather than proven.
 
 **Upgrading to a real build is additive, not a rewrite.** If they want it, switch
-to `references/app.md` and do this, in order:
+to the app workflow (the app reference, see SKILL.md) and do this, in order:
 
 1. Write `knowledge/` for what already exists — `entities/` for what you built,
    `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 `references/app.md` at its §4 (apps) or §5 (changes) for
+4. Then pick up the app workflow at its §4 (apps) or §5 (changes) for
    anything new.
 
 Nothing built here has to be thrown away to do that — which is the whole reason

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

@@ -1,7 +1,18 @@
 # Scenarios — writing journeys that stay proven
 
-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
+## Contents
+
+- The shape of a scenario
+- Extraction: what survives, and what silently does not
+- What to assert
+- There is no state reset
+- Steps rot as the app grows
+- Browser scenarios
+- Running them
+- Coverage — which functions have actually been run
+
+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
@@ -28,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 }
   },
@@ -59,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`** (app.md §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.
 
 ---
 
@@ -88,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
@@ -98,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
@@ -139,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.
@@ -176,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
@@ -240,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,4 +1,9 @@
-# Shipping, and staying Fabric-ready
+# Shipping, and staying deploy-ready
+
+## Contents
+
+- Ship it — open source, no platform
+- 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.
@@ -81,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({ ...,
@@ -114,7 +119,7 @@ one hostname, first-party cookies — give its `frontends` entry `"serve": {}`
 and a standalone deploy then mount its built `dist`. Pikku never builds it, so
 build the frontend first. Only one entry may set `serve`.
 
-To ship an app as a desktop or Android app, read `references/native-app.md`.
+To ship an app as a desktop or Android app, read the native-app reference (see SKILL.md).
 
 Before shipping, run the full gate:
 
@@ -153,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
@@ -187,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.