@pikku/skills 0.12.52 → 0.12.55

package/skills/pikku-scenario/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: pikku-scenario
 description: >-
-  Use when writing or running Pikku scenarios, running a persona as a virtual user, or when
+  Use when writing or running Pikku scenarios, running a virtual user against a stage, or when
   asked to test Pikku functions or improve coverage. A scenario (pikkuScenario) drives the app
-  the way users do — steps run as actors over the real transport against a running server — so a
+  the way users do — steps run as virtual users over the real transport against a running server — so a
   flow doubles as an e2e test and a staged/production health check. Covers scenario.do /
   expectEventually / expectError / expectService / expectScore, declared steps via
   pikkuScenarioStep (browser steps driven by @pikku/playwright) written as intent rather than
-  clicks, personas / actors / environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
-  `pikku scenario list|run` and `pikku persona run|list|sync|secret` commands, and live coverage
+  clicks, virtual users / virtual users / environments in pikku.config.json, VIRTUAL_USER_SIGNING_KEY, the
+  `pikku scenario` and `pikku virtual-user` commands, and live coverage
   via `pikku dev --coverage`. TRIGGER when: user asks about scenarios, testing a Pikku function,
-  coverage, e2e flows, browser/UI e2e, health checks, personas, virtual users, or adversarial
+  coverage, e2e flows, browser/UI e2e, health checks, virtual users, or adversarial
   runs against a stage. DO NOT TRIGGER when: user asks about running an existing suite (use
   Bash) or CI config.
 installGroups: [core]
@@ -20,38 +20,34 @@ installGroups: [core]
 
 ## Agent Operating Procedure
 
-Use this skill as an execution checklist, not reference material.
-
 1. Discover before editing: `pikku scenario list` for what exists, `pikku info functions --verbose` for what a scenario can call.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, or build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated.
-4. Validate with the narrowest relevant command first, then `pikku all --tsc` when functions, wirings or schemas may have changed.
-5. If validation fails, fix the source cause and rerun. Do not paper over generated errors by editing generated files.
+2. Edit source files only; never generated output or `.pikku`.
+3. Validate with the narrowest relevant command first, then `pikku all --tsc` when functions, wirings or schemas may have changed. If it fails, fix the source cause and rerun.
 
 **`pikku tests` does not exist.** It was removed in #865 — scenarios own coverage now. Any reference you find to it is stale.
 
 ## Pick the reference
 
-This skill covers writing and running scenarios end to end. Four topics are one level down, and
+This skill covers writing and running scenarios end to end. Five topics are one level down, and
 each says when to open it:
 
-| Read                        | For                                                                                                          |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `references/steps.md`       | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given                                    |
-| `references/browser.md`     | Browser bindings, and locating by message key in a translated app                                            |
-| `references/personas.md`    | Personas vs actors, `definePersonas`, upstream credentials for actors, and the human "Sign in as …" switcher |
-| `references/coverage.md`    | Live coverage, filling it, and unit tests for pure logic                                                     |
-| `references/persona-run.md` | Running a persona as a model-driven virtual user against a stage                                             |
+| Read                             | For                                                                                                                                 |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `references/steps.md`            | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given                                                           |
+| `references/browser.md`          | Browser bindings, and locating by message key in a translated app                                                                   |
+| `references/virtual-users.md`    | Virtual users vs virtual users, `defineVirtualUsers`, upstream credentials for virtual users, and human sign-in as a virtual user |
+| `references/coverage.md`         | Live coverage, filling it, and unit tests for pure logic                                                                            |
+| `references/virtual-user-run.md` | Running a model-driven virtual user against a stage                                                                                 |
 
 ## What a scenario is
 
-A scenario is a `pikkuScenario` export that drives the app **as real actors over the real transport**, against a running server. That is what lets one artifact serve as both an e2e test and a staged/production health check.
+A scenario is a `pikkuScenario` export that drives the app **as real virtual users over the real transport**, against a running server. That is what lets one artifact serve as both an e2e test and a staged/production health check.
 
 Consequences that matter, and bite if ignored:
 
 - **There is no state reset.** A scenario runs against a live server. Scope what you create (unique ids, your own rows) and never assume a clean database.
-- **Every effect runs as somebody, or as a declared step.** `scenario.do(...)` without `{ actor }` throws `Scenario tried to run '<rpc>' as an internal step…` — there is no bare internal-RPC step. The other way to do work is `scenario.given/when/then`, which runs a `pikkuScenarioStep`; its actor is optional (setup steps have none) unless it declares `browser: true`.
-- **Actors must be configured and signed in**, or the scenario cannot run.
+- **Every effect runs as somebody, or as a declared step.** `scenario.do(...)` without `{ virtualUser }` throws `Scenario tried to run '<rpc>' as an internal step…` — there is no bare internal-RPC step. The other way to do work is `scenario.given/when/then`, which runs a `pikkuScenarioStep`; its virtual user is optional (setup steps have none) unless it declares `browser: true`.
+- **Virtual users must be configured and signed in**, or the scenario cannot run.
 
 Scenarios live in `srcDirectories` like any other function — by convention `*.scenario.ts`.
 
@@ -68,10 +64,10 @@ export const orderSupportScenario = pikkuScenario<
 >({
   title: 'Order support (scenario)',
   tags: ['scenario'],
-  func: async ({ logger }, data, { scenario, actors }) => {
-    if (!actors?.shopper || !actors?.support) {
+  func: async ({ logger }, data, { scenario, virtualUsers }) => {
+    if (!virtualUsers?.shopper || !virtualUsers?.support) {
       throw new Error(
-        'orderSupportScenario needs run actors (shopper + support) — run via `pikku scenario run <environment>`'
+        'orderSupportScenario needs run virtualUsers (shopper + support) — run via `pikku scenario run <environment>`'
       )
     }
 
@@ -79,7 +75,7 @@ export const orderSupportScenario = pikkuScenario<
       'shopper doubles their order',
       'doubleValue',
       { value: data?.value ?? 21 },
-      { actor: actors.shopper }
+      { virtualUser: virtualUsers.shopper }
     )
 
     const settled = await scenario.expectEventually(
@@ -87,7 +83,7 @@ export const orderSupportScenario = pikkuScenario<
       'formatMessage',
       { greeting: 'Hello', name: 'Support' },
       (out: { message: string }) => out.message.length > 0,
-      { actor: actors.support, within: '5s', interval: 50 }
+      { virtualUser: virtualUsers.support, within: '5s', interval: 50 }
     )
 
     return { doubled: doubled.result, message: settled.message }
@@ -95,19 +91,19 @@ export const orderSupportScenario = pikkuScenario<
 })
 ```
 
-A scenario takes the same config fields as a workflow (`title`, `description`, `tags`, `input`/`output`, `auth`, `permissions`, `middleware`, `version`, …). The third argument is the scenario context: `{ scenario, actors }`.
+A scenario takes the same config fields as a workflow (`title`, `description`, `tags`, `input`/`output`, `auth`, `permissions`, `middleware`, `version`, …). The third argument is the scenario context: `{ scenario, virtualUsers }`.
 
 ### The scenario API
 
-| Call                                                                                 | Purpose                                                                                                                |
-| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| `scenario.do(step, rpc, data, { actor })`                                            | Run an RPC as that actor. The step name is what appears in the run output.                                             |
-| `scenario.expectEventually(step, rpc, data, predicate, { actor, within, interval })` | Poll until `predicate(out)` passes or `within` elapses. For anything asynchronous — queues, workers, eventual state.   |
-| `scenario.expectError(step, rpc, data, { actor, matches })`                          | Assert the call **fails**. For fault injection and negative paths.                                                     |
-| `scenario.expectService(step, 'service.method', { actor, calledWith })`              | Assert a stubbed service was called. Requires the server to run with `--test`.                                         |
-| `scenario.expectScore(step, runId, scorer, { atLeast, atMost, reference })`          | Grade a finished agent run with a declared scorer and assert the score. See below.                                     |
-| `scenario.given(stepName, step, data, { actor })`                                    | Run a declared `pikkuScenarioStep` as setup. `when` is the same call; `then` also makes the step's bindings witnesses. |
-| `scenario.runScheduledTask(name)`                                                    | Fire a wired scheduler on the target now, rather than waiting for its cron.                                            |
+| Call                                                                                       | Purpose                                                                                                                |
+| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `scenario.do(step, rpc, data, { virtualUser })`                                            | Run an RPC as that virtual user. The step name is what appears in the run output.                                      |
+| `scenario.expectEventually(step, rpc, data, predicate, { virtualUser, within, interval })` | Poll until `predicate(out)` passes or `within` elapses. For anything asynchronous — queues, workers, eventual state.   |
+| `scenario.expectError(step, rpc, data, { virtualUser, matches })`                          | Assert the call **fails**. For fault injection and negative paths.                                                     |
+| `scenario.expectService(step, 'service.method', { virtualUser, calledWith })`              | Assert a stubbed service was called. Requires the server to run with `--test`.                                         |
+| `scenario.expectScore(step, runId, scorer, { atLeast, atMost, reference })`                | Grade a finished agent run with a declared scorer and assert the score. See below.                                     |
+| `scenario.given(stepName, step, data, { virtualUser })`                                    | Run a declared `pikkuScenarioStep` as setup. `when` is the same call; `then` also makes the step's bindings witnesses. |
+| `scenario.runScheduledTask(name)`                                                          | Fire a wired scheduler on the target now, rather than waiting for its cron.                                            |
 
 `expectEventually` is **scenario-only**. Calling it from a `pikkuWorkflowFunc` is a critical inspector error (`PKU675`) pointing you at `pikkuScenario`.
 
@@ -127,7 +123,7 @@ const { runId } = await scenario.when(
   {
     prompt: data.prompt,
   },
-  { actor: actors.user }
+  { virtualUser: virtualUsers.user }
 )
 
 await scenario.expectScore('answered briefly', runId, 'brevity', {
@@ -156,8 +152,8 @@ the default suite excludes it.
 A scenario config takes `before` and `after`. Both have the **same signature as `func`** — `(services, data, wire)` — with the return value discarded:
 
 ```typescript
-const resetsCredentials = async (_services, _data, { actors }) => {
-  await actors!.admin!.invoke('resetCredentials', {})
+const resetsCredentials = async (_services, _data, { virtualUsers }) => {
+  await virtualUsers!.admin!.invoke('resetCredentials', {})
 }
 
 export const credentialScenario = pikkuScenario({
@@ -165,7 +161,7 @@ export const credentialScenario = pikkuScenario({
   tags: ['scenario', 'credential'],
   before: resetsCredentials,
   after: removesInstalledAddon,
-  func: async (services, data, { scenario, actors }) => {
+  func: async (services, data, { scenario, virtualUsers }) => {
     /* … */
   },
 })
@@ -180,18 +176,12 @@ export const credentialScenario = pikkuScenario({
 | Neither runs when the run is suspended or waiting — teardown only fires at a terminal outcome.           |
 | Hooks are **not** ladder rows. The runner records nothing for them; a failure is labelled by phase.      |
 
-A hook reaches the app the same way the body does: through `wire.actors`. If you want cleanup to be _visible_ on the ladder, make it an ordinary `scenario.then(...)` instead.
+A hook reaches the app the same way the body does: through `wire.virtualUsers`. If you want cleanup to be _visible_ on the ladder, make it an ordinary `scenario.then(...)` instead.
 
 Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs — a workflow is durable and resumable, so a callback that reran on every replay would have no honest meaning.
 
 ### Grouping scenarios (`pikkuFeature`)
 
-A feature is also cited by a page of the user guide: `pikku scenario guide`
-fills each cited block with the feature's recordings and screenshots, and
-nothing else (see **pikku-guide**). A scenario's `title` captions its recording
-and a screenshot's `name` captions the still, so write both as copy a user would
-read. Mark plumbing features `document: false`.
-
 `pikkuFeature` groups scenarios the way gherkin's `Feature:` groups `Scenario:`. Scenarios are referenced by **imported identifier**, so a renamed or deleted scenario is a compile error rather than a silent skip:
 
 ```typescript
@@ -229,11 +219,17 @@ export const credentialFeature = pikkuFeature({
 
 The **feature is the run unit**: `--flows` on a scenario whose every feature entry carries `data` errors and names the features containing it, because the feature is what supplies that data. Use `--features` for those. A scenario referenced bare anywhere, or in no feature at all, still runs standalone.
 
+A feature is also cited by a page of the user guide: `pikku scenario guide`
+fills each cited block with the feature's recordings and screenshots, and
+nothing else (see **pikku-guide**). A scenario's `title` captions its recording
+and a screenshot's `name` captions the still, so write both as copy a user would
+read. Mark plumbing features `document: false`.
+
 ## Steps
 
 `scenario.do` can only name an RPC. A **step** — `pikkuScenarioStep` — is a named, typed unit of
 scenario behaviour whose body is an ordinary pikku function, so it can call several RPCs as its
-actor, assert, or drive a browser. It is referenced by its typed string name (checked against the
+virtual user, assert, or drive a browser. It is referenced by its typed string name (checked against the
 generated step map), its body lives under a surface binding (`default` / `browser` / `cli`, never a
 `func`), and one row of the report is one step.
 
@@ -242,7 +238,7 @@ suite survives its first redesign:
 
 - **What a step is given** — a step runs in the CLI process, not where the app runs. There is no
   `kysely`, no `secrets`, and `rpc` is present but throws on purpose. Everything reaches the app
-  through the actor.
+  through the virtual user.
 - **Steps describe intent, not actions** — `buys the £5 strawberry milkshake`, never
   `clicks [data-testid=add]`. The clicking lives in plain utilities the step composes.
 - **`then` bindings are witnesses, not alternatives** — a `then` runs _every_ binding it declares
@@ -260,11 +256,11 @@ score a perfect run while checking nothing.
 
 ## Configuration
 
-Personas are declared in TypeScript. One `definePersonas({ … })` call for the
-whole project — codegen builds the `PersonaId` union from it, materialises one
-scenario actor per person, and seeds a user row each:
+Virtual users are declared in TypeScript. 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:
 
-```ts snippet:definePersonas
+```ts snippet:defineVirtualUsers
 
 ```
 
@@ -273,42 +269,40 @@ scenario actor per person, and seeds a user row each:
 ```json
 {
   "scenarios": {
-    "emailDomain": "actors.example.com",
+    "emailDomain": "virtualuser.example.com",
     "browserDriver": "@pikku/playwright",
     "model": "claude-sonnet-4-5"
   },
   "environments": {
     "local": {
       "apiUrl": "http://localhost:4077",
-      "signInPath": "/api/auth/sign-in/actor"
+      "signInPath": "/api/auth/sign-in/virtual-user"
     }
   }
 }
 ```
 
-- `scenarios.emailDomain` is the mail domain actor addresses are built on.
+- `scenarios.emailDomain` is the mail domain virtual user addresses are built on.
 - `scenarios.browserDriver` is the package driving `browser` bindings.
-- `scenarios.model` is the model a persona thinks with (`actor.converse`, `pikku virtual-user run`).
-- `environments.<name>` are the targets a run can point at. The key is the required positional of `pikku scenario run`; `apiUrl` is required and `signInPath`/`rpcPath`/`sessionPath` have defaults.
+- `scenarios.model` is the model a virtual user thinks with (`virtualUser.converse`, `pikku virtual-user run`).
+- `environments.<name>` are the targets a run can point at. The key is the required positional of `pikku scenario run`; `apiUrl` is required; `signInPath` defaults to `/auth/sign-in/virtual-user`, `rpcPath` to `/rpc`, and `sessionPath` has a default too.
 
-**`references/personas.md`** covers the parts that bite: one entry is one
-person and one actor, emails are derived and never written, `runnable: false`
-for someone only acted upon, `definePersonas` being read from source rather
-than evaluated, and the same actor list powering a human "Sign in as …"
-switcher.
+**`references/virtual-users.md`** covers the parts that bite: one entry is one
+person and one virtual user, emails are derived and never written, `runnable: false`
+for someone only acted upon, `defineVirtualUsers` being read from source rather
+than evaluated, and the same virtual user list powering a human sign-in.
 
-- `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
-- **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
+- **The signing key never goes in `pikku.config.json`.** `pikku dev` creates one under `.pikku-runtime/virtual-user/`; a deployed stage's deployer holds `VIRTUAL_USER_SIGNING_KEY`. Each run signs a short-lived statement with it. `pikku scenario run` throws without a key.
 
 ## Running
 
 ```bash
 pikku scenario list                       # features with their scenarios indented, then ungrouped scenarios
-SCENARIO_ACTOR_SECRET=… pikku scenario run local
-SCENARIO_ACTOR_SECRET=… pikku scenario run local --flows orderSupportScenario
-SCENARIO_ACTOR_SECRET=… pikku scenario run local --features credentialFeature
-SCENARIO_ACTOR_SECRET=… pikku scenario run local --tags smoke,scenario
-SCENARIO_ACTOR_SECRET=… pikku scenario run local --spawn --exclude-tags ai-live
+pikku scenario run local
+pikku scenario run local --flows orderSupportScenario
+pikku scenario run local --features credentialFeature
+pikku scenario run local --tags smoke,scenario
+pikku scenario run local --spawn --exclude-tags ai-live
 ```
 
 `run` takes the environment as a **required positional** — the key from `environments`. Every filter narrows the same plan, so narrowing a feature to two of its five scenarios still runs the feature's hooks exactly once around those two.
@@ -330,7 +324,7 @@ SCENARIO_ACTOR_SECRET=… pikku scenario run local --spawn --exclude-tags ai-liv
 
 Output is `PASS <name> (<ms>) → <output>` / `FAIL <name> (<ms>): <error>`, then `N/M scenarios passed against '<env>'`. A scenario inside a feature is named `<Feature> › <scenario> <data>`.
 
-**Exit code is 1** if any scenario fails _or_ if no scenario matched the filter — a typo'd `--flows` is a hard error, not a silent zero-run pass. It throws outright on an unknown environment, an unknown flow name, or a missing `SCENARIO_ACTOR_SECRET`.
+**Exit code is 1** if any scenario fails _or_ if no scenario matched the filter — a typo'd `--flows` is a hard error, not a silent zero-run pass. It throws outright on an unknown environment, an unknown flow name, or a missing signing key.
 
 ## Coverage
 
@@ -340,7 +334,7 @@ derived from unit tests:
 ```bash
 pikku enable scenarios                                 # sets scaffold.scenarios = true
 pikku dev --coverage                                   # V8 precise coverage, in-process
-SCENARIO_ACTOR_SECRET=… pikku scenario run local --coverage
+pikku scenario run local --coverage
 ```
 
 That writes `<outDir>/coverage/scenario-coverage.json`. **`references/coverage.md`** has the
@@ -351,21 +345,18 @@ and where a plain unit test is still the right tool.
 
 | Smell                                               | Why it's wrong                                                                                                                                   |
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `pikku tests …`                                     | Removed in #865. Use `pikku scenario`.                                                                                                           |
-| `.feature` files / Gherkin for function tests       | Scenarios are TypeScript, not Gherkin. The in-process cucumber function world was deleted.                                                       |
-| `scenario.do(...)` with no `{ actor }`              | Throws. Every step runs as somebody.                                                                                                             |
+| `.feature` files / Gherkin for function tests       | Scenarios are TypeScript, not Gherkin. There is no in-process function world.                                                                    |
+| `scenario.do(...)` with no `{ virtualUser }`        | Throws. Every step runs as somebody.                                                                                                             |
 | A scenario per function                             | Scenarios are user flows. One flow covers many functions; that is the point.                                                                     |
 | Assuming a clean database                           | There is no state reset — it may be a staging server. Scope what you create.                                                                     |
 | `sleep()` before asserting                          | Use `expectEventually`.                                                                                                                          |
-| A step named `clicksAddToBasket` / `opensThePage`   | That is an action, not an intent. Name the step for what the actor wanted; put the clicking in a utility.                                        |
+| A step named `clicksAddToBasket` / `opensThePage`   | That is an action, not an intent. Name the step for what the virtual user wanted; put the clicking in a utility.                                 |
 | A step named `kauftEinenApfel` / a `vorgang` table  | Identifiers are English in every project. The German belongs in `description` / `template`, and only when `pikku.config.json` sets `metaLocale`. |
 | A browser step that assumes it is already on a page | It can then only run mid-flow. Arrive first — check the URL, navigate if needed.                                                                 |
 | `getByLabel('Full Name')` in a translated app       | Passes only in the base locale, and a copy edit breaks it as an unexplained timeout. Locate by message key.                                      |
-| A `browser` binding guarding `if (!browser)`        | The binding guarantees it. The guard hides the real error, which is a missing actor (`PKU677`).                                                  |
+| A `browser` binding guarding `if (!browser)`        | The binding guarantees it. The guard hides the real error, which is a missing virtual user (`PKU677`).                                           |
 | A step with a `func:` instead of a surface binding  | There is no `func` on a step. Bodies live under `default` / `browser` / `cli`; a step with none throws at load.                                  |
 | `expectEventually` in a `pikkuWorkflowFunc`         | `PKU675` — scenario-only.                                                                                                                        |
-| Coverage silently 0                                 | Server not run with `--coverage`, verbose functions meta not deployed, `scaffold.scenarios` unset, or no actors configured.                      |
-
-`@pikku/cucumber` is a **browser/e2e** harness (`Actor`, `BrowserWorld`, `PersonaData`, `DbUtils`) — out of scope here.
+| Coverage silently 0                                 | Server not run with `--coverage`, verbose functions meta not deployed, `scaffold.scenarios` unset, or no virtual users configured.               |
 
 See `pikku-concepts` for the core mental model.

package/skills/pikku-scenario/references/browser.md

@@ -2,7 +2,7 @@
 
 Declaring a `browser` binding is the whole switch: inside that binding `wire.browser` is guaranteed present and non-optional, and a step without one never sees a browser at all. There is nothing to null-check.
 
-A `browser` binding gets a session bound to **its actor**, signed in through the same `signInPath` + `SCENARIO_ACTOR_SECRET` path the HTTP actors use, so the browser and the RPC calls are one identity. Calling such a step without an actor is a critical error (`PKU677`).
+A `browser` binding gets a session bound to **its virtual user**, signed in through the same signed-statement path the HTTP virtual users use, so the browser and the RPC calls are one identity. Calling such a step without a virtual user is a critical error (`PKU677`).
 
 Browser steps are where **intent, not actions** earns its keep: the step is one intent, the clicking lives in shared utilities, and the step arrives before it acts. Write the mechanics below into utilities and keep the step body to three or four calls that read as a sentence.
 
@@ -17,8 +17,8 @@ export const opensTheCart = pikkuScenarioStep<
     await browser.goto(path)
     return { url: browser.page.url() }
   },
-  default: async (_services, _data, { actor }) => ({
-    url: (await actor.invoke('getCart', {})).url,
+  default: async (_services, _data, { virtualUser }) => ({
+    url: (await virtualUser.invoke('getCart', {})).url,
   }),
 })
 ```
@@ -54,6 +54,6 @@ await page
 
 - Type off `messages/<baseLocale>.json`, **not** the generated Paraglide output — `i18n/paraglide/` is build output, so typing against it makes the tests unbuildable until the app has been built. The JSON is the tracked source.
 - Fall back to the base locale for a key a locale has not translated. That is what Paraglide does at run time, so a helper that throws instead would disagree with the screen the test is looking at.
-- This is not only about locators. A copy literal passed to a **project helper** (`pick('Where would you like to work?', …)`) reaches the DOM the same way, and so does a pane name quoted back in a failure message. `pikku fabric validate` scans every string in a `*.steps.ts` / `*.scenario.ts` against the base catalogue and errors on any verbatim match, wherever it sits — except comments, and the `name` / `description` / `template` declared directly on a `pikkuFeature`, `pikkuScenario` or `pikkuScenarioStep`, which are Console meta written in the project's `locale` rather than app copy.
+- This is not only about locators. A copy literal passed to a **project helper** (`pick('Where would you like to work?', …)`) reaches the DOM the same way, and so does a pane name quoted back in a failure message. `pikku validate` scans every string in a `*.steps.ts` / `*.scenario.ts` against the base catalogue and errors on any verbatim match, wherever it sits — except comments, and the `name` / `description` / `template` declared directly on a `pikkuFeature`, `pikkuScenario` or `pikkuScenarioStep`, which are Console meta written in the project's `locale` rather than app copy.
 - A regex locator (`{ name: /^Next$/i }`) hides the literal but not the problem. `{ name: t('key'), exact: true }` is both stricter and locale-correct.
-- Strings the catalogue does not own — a test id, a fixture filename, a seeded value — stay literal. The catalogue is the test for whether something is copy.
+- Strings the catalogue does not own — a test id, a fixture filename, a seeded value — stay literal. The catalogue is the test for whether something is copy.

package/skills/pikku-scenario/references/coverage.md

@@ -18,7 +18,7 @@ one as a flag would be worse than failing.
 ```bash
 pikku dev --coverage                                   # V8 precise coverage, in-process
 pikku dev --coverage --test                            # also enable stubs (needed for expectService)
-SCENARIO_ACTOR_SECRET=… pikku scenario run local --coverage
+pikku scenario run local --coverage
 ```
 
 The run resets coverage before each scenario and snapshots after, writing **`<outDir>/coverage/scenario-coverage.json`**:
@@ -33,7 +33,7 @@ The run resets coverage before each scenario and snapshots after, writing **`<ou
 }
 ```
 
-Coverage is best-effort: it disables itself with a warning if the server is not collecting or the first actor cannot invoke, and it needs at least one configured actor. If you get no coverage, check those first.
+Coverage is best-effort: it disables itself with a warning if the server is not collecting or the first virtual user cannot invoke, and it needs at least one configured virtual user. If you get no coverage, check those first.
 
 **There is no AI-prompt output.** The old `--ai-out` flag died with `pikku tests`; nothing replaced it. To find what needs work, read `scenario-coverage.json` yourself and cross-reference `pikku meta functions list` for input/output schemas.
 
@@ -41,7 +41,7 @@ Coverage is best-effort: it disables itself with a warning if the server is not
 
 1. `pikku scenario run <env> --coverage`, then read `<outDir>/coverage/scenario-coverage.json` to see what is unexercised.
 2. `pikku meta functions list` for those functions' schemas.
-3. Write a `pikkuScenario` that reaches them **through a real user flow** with an actor — not a scenario per function. Scenarios are flows; coverage is a consequence.
+3. Write a `pikkuScenario` that reaches them **through a real user flow** with a virtual user — not a scenario per function. Scenarios are flows; coverage is a consequence.
 4. Re-run to confirm.
 
 ## Unit tests for pure logic
@@ -67,4 +67,4 @@ describe('createTodo', () => {
 node --import tsx --test src/**/*.test.ts
 ```
 
-Services are plain objects — a Pikku function is pure business logic, so a mock is just the shape the function destructures. Build real services via the `pikkuServices` / `pikkuWireServices` factories when a test needs them.
+Services are plain objects — a Pikku function is pure business logic, so a mock is just the shape the function destructures. Build real services via the `pikkuServices` / `pikkuWireServices` factories when a test needs them.

package/skills/pikku-scenario/references/steps.md

@@ -16,7 +16,7 @@ Browser bindings have their own file: **`references/browser.md`**.
 
 ## What a step is
 
-`scenario.do` can only name an RPC. A **step** is a named, typed unit of scenario behaviour whose body is an ordinary pikku function — so it can call several RPCs as its actor, assert, or drive a browser.
+`scenario.do` can only name an RPC. A **step** is a named, typed unit of scenario behaviour whose body is an ordinary pikku function — so it can call several RPCs as its virtual user, assert, or drive a browser.
 
 ```typescript
 import { pikkuScenarioStep } from '#pikku/scenarios'
@@ -28,9 +28,9 @@ export const buysAnApple = pikkuScenarioStep<
   name: 'buysAnApple',
   description: 'buys an apple',
   template: 'buys {qty} apples',
-  actor: true,
-  default: async (_services, { qty }, { actor }) => {
-    return await actor.invoke('placeOrder', { qty })
+  virtualUser: true,
+  default: async (_services, { qty }, { virtualUser }) => {
+    return await virtualUser.invoke('placeOrder', { qty })
   },
 })
 ```
@@ -44,7 +44,7 @@ await scenario.given(
   'buys an apple',
   'buysAnApple',
   { qty: 1 },
-  { actor: actors.shopper }
+  { virtualUser: virtualUsers.shopper }
 )
 // reporter renders: Given shopper buys 1 apples   ✓  412ms
 ```
@@ -53,14 +53,14 @@ Rules that bite:
 
 - **The step is referenced by its typed string name, not by importing the const** — exactly like `workflow.do`. The name is the step's `pikkuFuncId` and is checked against the generated step map. A non-literal target is a critical error (`PKU678`).
 - **Steps are not RPCs.** They are deliberately never network-callable — a browser-driving step must not be.
-- **`actor.invoke` is typed over the exposed RPC map**, so the name and the payload are checked and the result comes back narrowed — no cast. `actor.invokeRaw(name, data, { headers })` is the same call reporting `{ status, ok, body }` instead of throwing; use it whenever the refusal _is_ the assertion.
-- **A step that runs as somebody declares `actor: true`**, and the runner injects `wire.actor` — non-optional inside every binding, with no guard to write and nothing to unwrap. A `browser` binding implies it, because a window is opened as somebody. Leave it off for a step with no persona to be: an assertion over what an earlier step returned, or one that posts credentials precisely because it must not reuse an actor's session. Dispatching a step that declared it without `{ actor: actors.x }` fails before the body runs (`ScenarioActorRequired`); a step that did not declare it has no `actor` on its wire at all.
+- **`virtualUser.invoke` is typed over the exposed RPC map**, so the name and the payload are checked and the result comes back narrowed — no cast. `virtualUser.invokeRaw(name, data, { headers })` is the same call reporting `{ status, ok, body }` instead of throwing; use it whenever the refusal _is_ the assertion.
+- **A step that runs as somebody declares `virtualUser: true`**, and the runner injects `wire.virtualUser` — non-optional inside every binding, with no guard to write and nothing to unwrap. A `browser` binding implies it, because a window is opened as somebody. Leave it off for a step with no virtual user to be: an assertion over what an earlier step returned, or one that posts credentials precisely because it must not reuse a virtual user's session. Dispatching a step that declared it without `{ virtualUser: virtualUsers.x }` fails before the body runs (`ScenarioVirtualUserRequired`); a step that did not declare it has no `virtualUser` on its wire at all.
 - **`env` is optional on the wire**, because most steps need nothing from it. Narrow it with `requireScenarioEnv(scenarioStep)` from `#pikku/scenario` rather than a local guard — it names the step and says what to pass. `env` is `{ apiUrl, appUrl? }` from the environment the run targets, and is how a raw-HTTP step learns the target's URL: a step runs in the CLI process, where there is no `variables` service and `process.env` is not the answer.
 - **Steps default to `retries: 0`**, unlike ordinary workflow steps. Retrying a failed assertion is wrong; pass `retries` explicitly if a step is genuinely flaky-by-nature.
 - **Step results are persisted**, so return JSON-serialisable data — never a `Locator` or a client object.
 - **`description` documents the step; `template` is what the report renders.** `template`'s `{placeholders}` are filled from the input the step was called with, so one step reads differently for each call — `sees {state} addon {packageName}` reports as "sees available addon @pikku/addon-stripe". Reflect every input field in the template, and type the values so they read as words (`state?: 'installed' | 'available'`, not `installed?: boolean`). A placeholder with no value renders as nothing and the whitespace collapses.
-- **Never write the actor into the prose.** The reporter renders the actor as the sentence's subject, so a step authored as `` `'sam' creates the client` `` run as `{ actor: actors.sam }` reads "Given sam 'sam' creates the client" — and the hardcoded name desyncs the moment the call site changes actor. Write a bare third-person predicate (`creates the {name} client`) and let the actor supply the subject. Prose that opens with its own actor's key — quoted, capitalised or possessive — is `PKU681`; naming someone **else** mid-sentence ("sends nadia an invite") is ordinary prose and is left alone, as is an actor keyed after a role noun used as a noun ("creates the admin client" as `actors.admin`).
-- Prose precedence is `options.description` → the step's `template` → the step's own `description` → the positional step name. Repeated names get `#1`, `#2` ordinals, so a `for` loop over a data set is how you write a Scenario Outline. A loop-generated step name is not statically known, so it is matched back to its declaration by step function instead — which works as long as that function's call sites agree on their phase, actor and prose. Two call sites that disagree make the loop step report under its bare runtime name.
+- **Never write the virtual user into the prose.** The reporter renders the virtual user as the sentence's subject, so a step authored as `` `'sam' creates the client` `` run as `{ virtualUser: virtualUsers.sam }` reads "Given sam 'sam' creates the client" — and the hardcoded name desyncs the moment the call site changes virtual user. Write a bare third-person predicate (`creates the {name} client`) and let the virtual user supply the subject. Prose that opens with its own virtual user's key — quoted, capitalised or possessive — is `PKU681`; naming someone **else** mid-sentence ("sends nadia an invite") is ordinary prose and is left alone, as is a virtual user keyed after a role noun used as a noun ("creates the admin client" as `virtualUsers.admin`).
+- Prose precedence is `options.description` → the step's `template` → the step's own `description` → the positional step name. Repeated names get `#1`, `#2` ordinals, so a `for` loop over a data set is how you write a Scenario Outline. A loop-generated step name is not statically known, so it is matched back to its declaration by step function instead — which works as long as that function's call sites agree on their phase, virtual user and prose. Two call sites that disagree make the loop step report under its bare runtime name.
 
 ## What a step is given
 
@@ -82,7 +82,7 @@ not.
 `guardRpc` whose every member refuses:
 
 > Scenario tried to run 'getOrder' as an internal step. Every workflow.do in a
-> scenario must carry { actor: actors.x } so it executes against 'local'.
+> scenario must carry { virtualUser: virtualUsers.x } so it executes against 'local'.
 
 The same guard covers `rpc.agent.run/stream/resume/approve/interrupt` and
 `startWorkflow`.
@@ -90,10 +90,10 @@ The same guard covers `rpc.agent.run/stream/resume/approve/interrupt` and
 This is the design, not a gap: **everything a step touches of the application
 goes over the wire as somebody.** A test that could reach into the database
 would be testing a different program from the one a person uses. So there are
-exactly three ways in, and they are all through the actor:
+exactly three ways in, and they are all through the virtual user:
 
-- `actor.invoke(name, data)` — typed over the exposed RPC map, carrying the
-  actor's session. Declare `actor: true` and destructure it off the wire.
+- `virtualUser.invoke(name, data)` — typed over the exposed RPC map, carrying the
+  virtual user's session. Declare `virtualUser: true` and destructure it off the wire.
 - `.invokeRaw(name, data, { headers })` — same call, reporting
   `{ status, ok, body }`, for when the refusal is the assertion.
 - a plain `fetch` against `requireScenarioEnv(scenarioStep).apiUrl`, for
@@ -108,9 +108,10 @@ Two consequences follow, and both shape how steps get written:
 - **`agentRunner` is conditional.** It is built only when the project declares
   agents, and `createDevAgentRunner` needs a base URL _and_ a key together
   (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or the LiteLLM pair). With a key alone
-  it returns nothing and `agentRunner` is `undefined`, so `actor.converse`
-  fails before the persona says anything. A suite that would rather own its own
+  it returns nothing and `agentRunner` is `undefined`, so `virtualUser.converse`
+  fails before the virtual user says anything. A suite that would rather own its own
   model can pass an `llm` to `runConversation` instead of relying on this one.
+
 ---
 
 ## Steps describe intent, not actions
@@ -193,7 +194,7 @@ export const buysTheItem = pikkuScenarioStep<
   name: 'buysTheItem',
   description: 'finds one item in the shop and puts it in the basket',
   template: 'buys the {name}',
-  // One intent, one implementation per surface an actor can drive it through.
+  // One intent, one implementation per surface a virtual user can drive it through.
   browser: async (_services, { name }, { browser }) => {
     await ensureOnShop(browser)
     await searchFor(browser, name)
@@ -215,7 +216,7 @@ await scenario.when(
   'buys a milkshake',
   'buysTheItem',
   { name: '£5 strawberry milkshake' },
-  { actor: actors.shopper }
+  { virtualUser: virtualUsers.shopper }
 )
 // reporter renders: When shopper buys the £5 strawberry milkshake  ✓  1.2s
 ```
@@ -254,7 +255,7 @@ const order = await scenario.do(
   'Shopper checks out',
   'createOrder',
   { basketId, shippingAddress },
-  { actor: actors.shopper }
+  { virtualUser: virtualUsers.shopper }
 )
 ```
 
@@ -282,9 +283,9 @@ export const seesTheOrderConfirmed = pikkuScenarioStep<
   { status: string }
 >({
   name: 'seesTheOrderConfirmed',
-  // Both bindings run as the persona, so the step declares one and the runner
-  // injects `wire.actor` — non-optional in every binding.
-  actor: true,
+  // Both bindings run as the virtual user, so the step declares one and the runner
+  // injects `wire.virtualUser` — non-optional in every binding.
+  virtualUser: true,
   template: 'sees order {orderId} confirmed',
   // Both run on `--run browser`. Each returns what it observed, and the runner
   // compares them — so this fails when the page disagrees with the database.
@@ -293,9 +294,9 @@ export const seesTheOrderConfirmed = pikkuScenarioStep<
       .locate({ testId: 'order-status', where: { 'data-order': orderId } })
       .getAttribute('data-status'),
   }),
-  // Through the actor, not through a `rpc` service — see "What a step is given".
-  default: async (_services, { orderId }, { actor }) => ({
-    status: (await actor.invoke('getOrder', { orderId })).status,
+  // Through the virtualUser, not through a `rpc` service — see "What a step is given".
+  default: async (_services, { orderId }, { virtualUser }) => ({
+    status: (await virtualUser.invoke('getOrder', { orderId })).status,
   }),
 })
 ```
@@ -304,7 +305,7 @@ Three rules follow, and they are the ones that get broken:
 
 - **A browser witness must observe on the page.** One that quietly calls an RPC to check the result is worse than no binding at all — it reports a tick for a surface it never looked at.
 - **Return what you observed, don't just assert.** A witness returning a value lets the runner diff the two. A witness that only throws still works, but it can never disagree with anything, so it proves less. Read structured state with `where` on the test-id selector rather than parsing translated copy.
-- **A step with no binding for the run's surface is counted, not excused.** `--run browser` prints `n/m steps ran on browser` over _every_ step, so an action that quietly fell back to the server lowers the number just as an assertion does. A `then` that fell back is additionally named — `--strict` fails on those, because a sentence saying the actor saw something nobody looked at is a different problem from a shortcut. Not being in the UI _is_ the finding: do not add a browser binding that fakes it.
+- **A step with no binding for the run's surface is counted, not excused.** `--run browser` prints `n/m steps ran on browser` over _every_ step, so an action that quietly fell back to the server lowers the number just as an assertion does. A `then` that fell back is additionally named — `--strict` fails on those, because a sentence saying the virtual user saw something nobody looked at is a different problem from a shortcut. Not being in the UI _is_ the finding: do not add a browser binding that fakes it.
 
 **Always give a `then` a `default` witness.** It is the floor every run can fall back to, and an assertion with no witness the run can execute is fatal (`ScenarioNoWitness`) — not a coverage gap. The distinction is the point: a `then` checked server-side under `--run browser` did happen, it just wasn't seen where the prose claims; one checked nowhere never happened at all, and without the error it would return `undefined` and render as a tick. A browser-only `then` is therefore a step that fails the fast suite, which is rarely what you want.
 
@@ -343,9 +344,9 @@ export const buysAnApple = pikkuScenarioStep<
   name: 'buysAnApple', // identifier — English, always
   description: 'kauft einen Apfel', // prose — follows locale
   template: 'kauft {qty} Äpfel', // prose — follows locale
-  actor: true,
-  default: async (_services, { qty }, { actor }) =>
-    await actor.invoke('placeOrder', { qty }),
+  virtualUser: true,
+  default: async (_services, { qty }, { virtualUser }) =>
+    await virtualUser.invoke('placeOrder', { qty }),
 })
 ```
 
@@ -356,11 +357,11 @@ A product with a non-English UI is not on its own a reason to set `metaLocale`
 is the app's language, not the team's. Ask, or leave it `en`.
 
 **Where a non-`en` `metaLocale` still shows English, today.** The reporter composes a
-sentence as `<Keyword> <actor> <template>` (`composeStepProse`), and the keyword is
+sentence as `<Keyword> <virtual user> <template>` (`composeStepProse`), and the keyword is
 an English literal. The Console translates the Given/When/Then keywords into its own
 UI language; the CLI reporter does not, so `metaLocale: "de"` gives you German step
 prose inside an English frame — `Given shopper kauft 1 Äpfel`. Write templates that read
 acceptably in that frame rather than trying to defeat it. A second gap: where a
 function or scenario declares no `title`, the Console falls back to splitting the
 **identifier** into an English-looking label (`toEnglishName`), so under a
-non-`en` `metaLocale` meta is worth authoring rather than leaving to the fallback.
+non-`en` `metaLocale` meta is worth authoring rather than leaving to the fallback.