@pikku/skills 0.12.54 → 0.12.55

package/skills/pikku-scenario/references/{persona-run.md → virtual-user-run.md}

@@ -1,17 +1,17 @@
-# Running a persona as a virtual user
+# Running a virtual user against a stage
 
 ## Contents
 
 - [The shape of a run](#the-shape-of-a-run)
 - [The dispositions](#the-dispositions)
-- [Credentials, and which one wins](#credentials-and-which-one-wins)
+- [The key](#the-key)
 - [Production is opt-in, twice](#production-is-opt-in-twice)
 - [The role check happens before the first step](#the-role-check-happens-before-the-first-step)
 - [The other subcommands](#the-other-subcommands)
 - [What NOT to do](#what-not-to-do)
 
-`pikku persona run <environment> <persona>` signs a declared persona in over the
-app's real auth and works the API in character, driven by a model. A persona
+`pikku virtual-user run <environment> <virtualUserId>` signs a declared virtual user in over the
+app's real auth and works the API in character, driven by a model. A virtual user
 while running **is** the virtual user — there is no second declaration for it.
 
 **It is not a test runner.** It asserts nothing, and a green run proves nothing:
@@ -20,33 +20,33 @@ not with this seed". Findings set exit code 1, so a run can gate a pipeline;
 giving up on a goal does not, because that is a user being a user.
 
 Everything it needs is already in the project — the catalogue is the function
-meta, the intents are the scenarios' own prose, the identity is the persona
+meta, the intents are the scenarios' own prose, the identity is the virtual user
 signing in, the scopes come from their declared roles. The only new input is
 which person to be.
 
-Declaring personas — persona versus actor, `definePersonas`, materialised
-actors — is in the skill itself, under **Personas and actors**. This is the
+Declaring virtual users — virtual user versus virtual user, `defineVirtualUsers`, materialised
+virtual users — is in the skill itself, under **Virtual users and virtual users**. This is the
 running half.
 
 ## The shape of a run
 
 ```bash
-SCENARIO_ACTOR_SECRET=… pikku persona run local shopper
-SCENARIO_ACTOR_SECRET=… pikku persona run local shopper -d careless --seed 42
-SCENARIO_ACTOR_SECRET=… pikku persona run staging auditor \
+pikku virtual-user run local shopper
+pikku virtual-user run local shopper -d careless --seed 42
+pikku virtual-user run staging auditor \
   --goals "reconcile the order totals" --steps 80 --out runs/auditor.json
 ```
 
 Both arguments are required positionals: the environment key from
-`environments`, then the persona id. A run needs a model — `--model`, or
+`environments`, then the virtual user id. A run needs a model — `--model`, or
 `scenarios.model` in `pikku.config.json` — and an AI provider in the
 environment (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or `LITELLM_PROXY_URL` +
 `LITELLM_API_KEY`).
 
 | Flag                   | Effect                                                                                                                                                |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--disposition` / `-d` | How they behave. Overrides the persona's own                                                                                                          |
-| `--goals`              | Comma-separated, in your words — run _alongside_ the persona's own and the ones derived from scenarios                                                |
+| `--disposition` / `-d` | How they behave. Overrides the virtual user's own                                                                                                     |
+| `--goals`              | Comma-separated, in your words — run _alongside_ the virtual user's own and the ones derived from scenarios                                           |
 | `--steps`              | Model turns before it stops (default 40)                                                                                                              |
 | `--mutations`          | Non-read calls before it stops                                                                                                                        |
 | `--duration`           | Wall clock before it stops, e.g. `30m`                                                                                                                |
@@ -60,9 +60,9 @@ environment (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or `LITELLM_PROXY_URL` +
 ## The dispositions
 
 A disposition is a bundle of instructions and mechanical dials (move weights,
-temperature, repeat and re-read rates). `tuning` on the persona adjusts those
+temperature, repeat and re-read rates). `tuning` on the virtual user adjusts those
 dials without replacing the character — a tuned `careless` user is still
-careless. Passing `--disposition` drops the persona's `tuning`, because you
+careless. Passing `--disposition` drops the virtual user's `tuning`, because you
 asked to run them differently rather than to bend their dials into another
 shape.
 
@@ -76,33 +76,29 @@ shape.
 | `adversarial` | Probing whether the boundaries are enforced. Inverted oracle — a 2xx from something it should not reach is the finding        |
 | `accountable` | Doing the job for real. The **only** disposition production accepts                                                           |
 
-## Credentials, and which one wins
+## The key
 
-Three variables, checked in this order. None of them belongs in
-`pikku.config.json`.
+A run signs one short-lived statement per virtual user and presents it to the
+app. The key comes from, in this order:
 
-1. **`FABRIC_OPERATOR_TOKEN`** — what a deployed stage accepts. Asymmetric, and
-   it needs no account the target would not otherwise have, so it wins over the
-   other two when both are present.
-2. **`PIKKU_PERSONA_SECRETS`** — `id=secret,id=secret`, already-derived
-   per-persona credentials. Hand a run only the personas it should be able to
-   be; asking for one outside the list is refused by name rather than falling
-   through to the root. Mint them with `pikku persona secret [personas...]` —
-   naming none mints all.
-3. **`SCENARIO_ACTOR_SECRET`** — the root secret, which derives every persona's
-   credential and is therefore entitled to all of them. Only `pikku dev` serves
-   the endpoint it opens.
+1. **`VIRTUAL_USER_SIGNING_KEY`** in the environment — a deployed stage's
+   private key, held by whoever deploys it.
+2. **The file `pikku dev` wrote**, `.pikku-runtime/virtual-user/signing.key` —
+   so a local run needs nothing set.
+
+Neither belongs in `pikku.config.json`. The app only ever holds the public half,
+`VIRTUAL_USER_VERIFY_KEY`.
 
 ## Production is opt-in, twice
 
-A persona's `environments` omitted means every configured environment **except**
+A virtual user's `environments` omitted means every configured environment **except**
 those flagged `production: true` — nothing reaches production by being
 forgotten. Naming one requires `disposition: 'accountable'`.
 
 That rule is checked twice on purpose: the inspector checks the declaration at
-build time, and sign-in re-checks the **effective** disposition — the persona's
+build time, and sign-in re-checks the **effective** disposition — the virtual user's
 own, or whatever `--disposition` replaced it with — before the run starts. So
-`--disposition adversarial` cannot point an accountable persona at production.
+`--disposition adversarial` cannot point an accountable virtual user at production.
 The build check trusts the file; the run check does not trust which artifact got
 deployed.
 
@@ -110,7 +106,7 @@ deployed.
 true` is a label a person wrote in `pikku.config.json`; nothing can tell from a
 url whether real customers are behind it. `--api-url` replaces the url and keeps
 the classification, so a non-production environment repointed at a production
-host is still treated as non-production, and an adversarial persona will happily
+host is still treated as non-production, and an adversarial virtual user will happily
 run against it. The flag is for a target that only exists at run time — a
 freshly provisioned sandbox. Point it anywhere else and the guard above is not
 protecting you.
@@ -118,8 +114,8 @@ protecting you.
 ## The role check happens before the first step
 
 A run reads its own roles back from the stage and compares them to what the
-persona declared. It refuses on a mismatch, before anything runs — findings
-from a persona whose roles drifted are about the seed, and reading them as
+virtual user declared. It refuses on a mismatch, before anything runs — findings
+from a virtual user whose roles drifted are about the seed, and reading them as
 product bugs is how a whole run gets thrown away. A stage that reports no roles
 warns and runs unverified. `--skip-role-check` is for a target whose auth
 reports roles somewhere pikku cannot read; findings from such a run may be seed
@@ -127,21 +123,20 @@ drift.
 
 ## The other subcommands
 
-| Command                              | What it answers                                                                            |
-| ------------------------------------ | ------------------------------------------------------------------------------------------ |
-| `pikku persona list`                 | Who is declared — who each one is, what they may do, what they want                        |
-| `pikku persona sync <environment>`   | Which personas that environment will provision, with which roles, and why any were skipped |
-| `pikku persona secret [personas...]` | Mint per-persona credentials from the root secret                                          |
+| Command                                 | What it answers                                                                                 |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `pikku virtual-user list`               | Who is declared — who each one is, what they may do, what they want                             |
+| `pikku virtual-user sync <environment>` | Which virtual users that environment will provision, with which roles, and why any were skipped |
 
 `sync` **reports**; it does not provision. The CLI has no connection to a
 deployed environment's database, so the provisioning happens in the deployment —
-pass the generated personas to `provisionPersonas` from `@pikku/better-auth`.
+pass the generated virtual users to `provisionVirtualUsers` from `@pikku/better-auth`.
 
 ## What NOT to do
 
 - **Do not treat a clean run as a pass.** Nothing was asserted. Use scenarios
   for the things that must hold.
-- **Do not run a persona declared `runnable: false`**, or one whose `account`
+- **Do not run a virtual user declared `runnable: false`**, or one whose `account`
   names a provider. The first is someone who exists to be acted upon — running
   her races the scenario that bans her — and the second needs a human at a
   consent screen. Both are refused before sign-in rather than partway through.
@@ -154,5 +149,5 @@ pass the generated personas to `provisionPersonas` from `@pikku/better-auth`.
   ones the app marked as needing a human because they spend money.
 - **Do not read a finding from a run started with `--skip-role-check` as a
   product bug** until the roles are confirmed some other way.
-- **Do not expect `--goals` to replace the persona's goals.** They are appended;
+- **Do not expect `--goals` to replace the virtual user's goals.** They are appended;
   a run that replaces Susan's goals is not Susan.

package/skills/pikku-scenario/references/virtual-users.md

@@ -0,0 +1,114 @@
+# Virtual users and virtual users
+
+## Contents
+
+- [Declaring virtual users in TypeScript](#declaring-virtual-users-in-typescript)
+- [Virtual users that call a third-party API](#virtual-users-that-call-a-third-party-api)
+- [The same virtual users sign a human in](#the-same-virtual-users-sign-a-human-in)
+
+A **virtual user** is a person your product is for; an **virtual user** is one body that signs in as them. Every entry materialises exactly one virtual user, so `virtualUsers.<id>` exists for each declared virtual user and there is no second way to declare a login.
+
+- Two people of the same kind are two entries, not one virtual user with two logins — "you see yours, not theirs" is only testable with two customers.
+- Never write an email address: each is derived from the virtual user id and `scenarios.emailDomain`, and a hand-written one signs in as somebody who was never created.
+- `roles` is typechecked against `defineSystemRole`; an undeclared role is a build error.
+- A person who is only ever acted _upon_ — the account an admin bans — sets `runnable: false`: declared and seeded, never signed in, because a run as them would race the scenario that acts on them.
+- A virtual user holds only what is true of that kind of person for the app's whole lifetime (`name`, `jobTitle`, `description`, `personality`, `roles`, `goals`, `disposition`). What someone is trying to get done, and the circumstances they are doing it in, belong to the **scenario**, not to them.
+
+## Declaring virtual users in TypeScript
+
+There may be **one `defineVirtualUsers` call in the whole codebase** — one place to
+read the set from, one place to add to it. A second anywhere, including in the
+same file, is a critical. Generated files are exempt and never claim the slot.
+
+> [!WARNING]
+> The declaration is **read from source, never evaluated** — the CLI writes it
+> to JSON that a deployed stage carries without the app. So every value has to
+> be statically knowable, and a value that is not comes out as `undefined`
+> rather than as an error. Only `name` is checked, so a computed `personality`,
+> `jobTitle` or `description` is dropped in silence and the virtual user runs with a
+> blank temperament.
+
+What that admits and what it does not:
+
+```typescript
+personality: 'Wound up and short with it.' // read
+personality: `Wound up and short with it.
+  Says what she wants in a few blunt words.` // read — no ${} in it
+personality: 'Wound up. ' + 'Short with it.' // dropped, silently
+personality: TEMPERAMENTS.impatient // dropped, silently
+```
+
+A no-substitution template literal is a string literal as far as the reader is
+concerned, so it is the way to write a long personality across several lines —
+not a concatenation, and not a `prettier-ignore`d single line. Its newlines and
+leading indentation are kept verbatim and reach the model that way, which is
+harmless but worth knowing before you align it to the surrounding code.
+
+One more thing worth knowing before writing a rich virtual user: **`virtualUser.converse`
+builds its prompt from `name`, `jobTitle`, `personality` and the scenario's
+`task` only.** Fields like `disposition`, `goals` and `roles` are read and
+stored, and the console shows them, but they do not reach the conversing
+virtual user's instructions. Anything that must shape how someone talks belongs in
+`personality` or in the task.
+
+A project that never declares a virtual user keeps working: a scenario that names no virtual user needs none.
+
+- `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/virtual-user`, `rpcPath` to `/rpc`.
+- **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`. `pikku scenario run` throws without a key.
+
+## Virtual users that call a third-party API
+
+An addon generated from an upstream API (Dolibarr, a CRM, a calendar) calls it
+with the signed-in user's own credential. A virtual user has none until one is stored
+for it, so every step that reaches the addon fails with `No <X> session`. Give
+the `virtualUser` plugin a `credentials` option, and each virtual user carries its upstream
+credential into every session:
+
+- `names: ['dolibarr']` — the credentials to carry
+- `store: (name, value, userId) => credentialService.set(name, value, userId)`
+- `remove: (name, userId) => credentialService.delete(name, userId)`
+
+At each virtual user sign-in the plugin reads `VIRTUAL_USER_CREDENTIAL_<VIRTUAL_USER>_<NAME>` —
+`dan` + `dolibarr` is `VIRTUAL_USER_CREDENTIAL_DAN_DOLIBARR` — and stores it with
+`credentialService.set` for that virtual user. A bare value is stored as `{ token }`
+(what a delegated or bearer credential holds); a JSON object is stored as-is,
+e.g. `{"apiKey":"…"}` for an API-key credential. Unset means the virtual user has no
+upstream credential: `remove` drops one stored at an earlier sign-in.
+
+- **Values live in `.env` (or CI secrets), never in `virtual-users.ts` or code.**
+  Use a dedicated upstream test account per virtual user, not a real person's.
+- `read` defaults to `process.env`; a Worker passes `(key) => variables.get(key)`.
+- A malformed JSON value refuses the sign-in with a 500 that names the variable.
+- A delegated token expires upstream like any other; re-signing the virtual user
+  in re-stores whatever the variable holds now.
+
+## The same virtual users sign a human in
+
+Declared virtual users are not only for automated runs. `signInPath` is Better Auth's
+`virtualUser` plugin (see `pikku-auth`, a separate install), which any caller can post to — so the
+frontend can sign in as the **same** list, and an
+app can be reviewed as each kind of user without anyone knowing a seed password.
+
+It holds no credential. A client app that wants one-click sign-in posts only a
+virtual user id to `/auth/sign-in/switch-virtual-user` itself; the server
+resolves the address. One server piece serves both, in the auth config:
+
+```ts snippet:virtualUserSignIn
+
+```
+
+It is always open under `pikku dev`. A deployed stage needs virtual user
+sign-in opted in and an explicit `virtualUserSignIn.allowed`; production never
+has the opt-in, so it lists nobody and refuses every virtual user sign-in.
+
+If the list is empty, it is one of two things, and neither errors:
+
+- **The gate is closed.** On a deployed stage that is the gate doing its job —
+  check the opt-in. Locally, check the virtual users declare an `email` (via
+  `scenarios.emailDomain`) and are not `runnable: false`.
+- **`virtualUserSignIn` is missing, or the frontend calls another API.** A dev
+  proxy (`VITE_API_PROXY`, default `http://localhost:3000`) that points at
+  another project's API lists that project's virtual users, or none.
+
+When the list has virtual users but a sign-in 404s, that virtual user has no `email`
+or is `runnable: false`.

package/skills/pikku-seo/SKILL.md

@@ -44,7 +44,7 @@ gate) — write real copy for THIS app, in the app's voice.
 - **Title**: unique per page, 50–60 characters, the page's primary topic first,
   brand at the end (`Topic — AppName`). The template's `__APP_TITLE__` placeholder
   (in `src/app-meta.ts` and `messages/en.json`) is filled with the app title at scaffold time
-  by `fabric-new-app`; it must never survive in any page's title.
+  by `cloud-new-app`; it must never survive in any page's title.
 - **Description**: unique per page, 150–160 characters, states the concrete
   value of the page in plain language — a reason to click, not a keyword list.
 - **Dynamic public pages** (e.g. a public detail page) build both from loader

package/skills/pikku-services/references/audit-wire-service.md

@@ -1,6 +1,6 @@
 # Audit Wire Service
 
-`createInvocationAudit` creates a per-request `InvocationAuditLog` that buffers audit events in memory and flushes them as a batch when the function-runner calls `closeWireServices` at the end of the request. If `singletonServices.audit` is not configured (local dev without Fabric), it returns a no-op `DisabledInvocationAudit` — no crash, events are silently dropped.
+`createInvocationAudit` creates a per-request `InvocationAuditLog` that buffers audit events in memory and flushes them as a batch when the function-runner calls `closeWireServices` at the end of the request. If `singletonServices.audit` is not configured (local dev without a hosting platform), it returns a no-op `DisabledInvocationAudit` — no crash, events are silently dropped.
 
 Pair with `createAuditedKysely` to auto-capture every Kysely query as an audit event.
 
@@ -38,4 +38,4 @@ const deleteUser = pikkuFunc({
 
 `closeWireServices` (called automatically by the function-runner) invokes `audit.close()` → `singletonServices.audit.write(batch)` → platform-specific flush (e.g. CF Queue, libsql INSERT). No manual flushing needed.
 
-> **Fabric note:** Fabric provisions the audit queue and consumer worker automatically. The audit table schema is in `db/sqlite/0003-audit.sql` (starter-template). Run `pikku fabric validate` to confirm the migration is in place.
+> **Note:** a hosting platform may provision the audit queue and consumer worker for you. The audit table schema is in `db/sqlite/0003-audit.sql` (starter-template). Run `pikku validate` to confirm the migration is in place.

package/skills/pikku-services/references/audit.md

@@ -10,7 +10,6 @@
 - [AuditEvent shape](#auditevent-shape)
 - [Do / Don't](#do-dont)
 
-
 ## Mental model — two layers
 
 - **`audit` (singleton `AuditService`)** — the durable **sink**. Write-only: `audit(event)` + optional `write(batch)`. Defaults to `NoopAuditService` (discards). Swap in a real sink to persist (see Sinks).
@@ -188,7 +187,7 @@ type AuditEvent = {
 
 `auditLog.write()` takes `Omit<AuditEvent, 'occurredAt'>` — you only supply `type`, `source`, and `metadata` (and `userIdentity` if overriding the session default).
 
-`userIdentity` is filled from the wire's session plus its `pikkuUserId`, and is left off entirely when all three are absent — which is what makes a cron or system invocation land with a null actor rather than an empty object.
+`userIdentity` is filled from the wire's session plus its `pikkuUserId`, and is left off entirely when all three are absent — which is what makes a cron or system invocation land with a null virtual user rather than an empty object.
 
 ## Do / Don't
 

package/skills/pikku-services/references/services.md

@@ -210,7 +210,7 @@ what makes the split real.
 
 ### Audit Wire Service
 
-`createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and Fabric notes, read `references/audit-wire-service.md`.
+`createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and hosting notes, read `references/audit-wire-service.md`.
 
 ### Built-in Services
 

package/skills/pikku-software-archaeology/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-software-archaeology
-description: 'Use when reverse-engineering an existing repository into a `.knowledge/` Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner of the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator. Not the `knowledge/` notes of pikku-knowledge. DO NOT TRIGGER for: documenting code structure, API docs for a clean codebase, an engineer-facing code review, or rebuilding from an existing blueprint (use pikku-blueprint-to-fabric).'
+description: 'Use when reverse-engineering an existing repository into a `.knowledge/` Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner of the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator. Not the `knowledge/` notes of pikku-knowledge. DO NOT TRIGGER for: documenting code structure, API docs for a clean codebase, an engineer-facing code review, or rebuilding from an existing blueprint.'
 installGroups: [core]
 ---
 
@@ -25,7 +25,7 @@ Everything goes in `<repo>/.knowledge/` (or a caller-specified directory):
 
 ```
 .knowledge/
-├── product.json        # purpose, actors, capabilities, terminology
+├── product.json        # purpose, virtualUsers, capabilities, terminology
 ├── domains.json        # business domains (NEVER folder names)
 ├── entities.json       # domain entities: attributes, relationships, states, transitions
 ├── commands.json       # state-changing actions (SendInvoice, not POST /invoices/:id/send)
@@ -77,13 +77,13 @@ Build an inventory before interpreting anything:
 
 Where intent hides, per ecosystem (read these first):
 
-| Ecosystem                 | Highest-yield locations                                                                                                                                                                                                                                                                                                      |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Rails                     | `config/routes.rb`, model validations + callbacks + `aasm`/state machines, `app/policies` (Pundit) / `ability.rb` (CanCan), Sidekiq/ActiveJob workers, `db/schema.rb`, specs (esp. request + model specs)                                                                                                                    |
-| Express/Node              | route registration files, middleware chains (auth!), inline `if` guards in handlers, SQL/ORM models, `jobs/`+crontab refs, webhook handlers                                                                                                                                                                                  |
-| Django                    | `urls.py`, model `Meta`/constraints/`clean()`, DRF serializers + permissions classes, celery tasks, admin.py (reveals internal workflows)                                                                                                                                                                                    |
-| Laravel                   | `routes/`, FormRequests (validation), Policies/Gates, Jobs + scheduler in `Kernel.php`, migrations                                                                                                                                                                                                                           |
-| Go                        | mux/router setup, middleware, struct tags, `cmd/` binaries (each is a component)                                                                                                                                                                                                                                             |
+| Ecosystem                 | Highest-yield locations                                                                                                                                                                                                                                                                                                                  |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rails                     | `config/routes.rb`, model validations + callbacks + `aasm`/state machines, `app/policies` (Pundit) / `ability.rb` (CanCan), Sidekiq/ActiveJob workers, `db/schema.rb`, specs (esp. request + model specs)                                                                                                                                |
+| Express/Node              | route registration files, middleware chains (auth!), inline `if` guards in handlers, SQL/ORM models, `jobs/`+crontab refs, webhook handlers                                                                                                                                                                                              |
+| Django                    | `urls.py`, model `Meta`/constraints/`clean()`, DRF serializers + permissions classes, celery tasks, admin.py (reveals internal workflows)                                                                                                                                                                                                |
+| Laravel                   | `routes/`, FormRequests (validation), Policies/Gates, Jobs + scheduler in `Kernel.php`, migrations                                                                                                                                                                                                                                       |
+| Go                        | mux/router setup, middleware, struct tags, `cmd/` binaries (each is a component)                                                                                                                                                                                                                                                         |
 | Frontend (React/Vue/etc.) | router config / file-based routes (pages a user reaches), the component tree, the design-system import (`@mui/*`, Tailwind config, shadcn `components.json`) to judge consistency, the data layer (react-query/tRPC/fetch wrappers) to tie UI back to backend queries, charts/tables/editors (the `custom-logic` port risk), auth wiring |
 
 ### Phase 2 — Test excavation (do not skip)
@@ -91,7 +91,7 @@ Where intent hides, per ecosystem (read these first):
 Tests are the closest thing to an executable product spec. For every test file:
 
 - `describe`/`context`/`it` names → **scenarios** (attach to the matching workflow in `workflows.json` under `scenarios[]`, with `fromTest` set).
-- User-flow/journey harnesses (`pikkuUserFlow` stories, cucumber `.feature` files, Playwright journeys) are the highest-grade scenario source — they already ARE given/when/outcome sequences; extract them verbatim.
+- User-flow/journey harnesses (`pikkuUserFlow` stories, `.feature` files, Playwright journeys) are the highest-grade scenario source — they already ARE given/when/outcome sequences; extract them verbatim.
 - Assertions → confirmations of policies and invariants (upgrade their `confidence` to `high`, add the test as evidence).
 - Fixtures/factories → entity attribute shapes and realistic example data.
 - Edge-case tests → business rules that exist **nowhere else in the code** (e.g. "replayed webhook events are idempotent" may only be stated in a test).
@@ -105,9 +105,9 @@ Run each lens over the surveyed material. Rules that counter the classic failure
 
 **Domains** — infer from data ownership, workflows, and vocabulary; NEVER from folder names. `controllers/` is not a domain; "Billing" is. A domain owns entities and the commands that mutate them.
 
-**Entities** — domain concepts, not tables. Include: attributes (from schema + serializers + fixtures), relationships, **lifecycle states and transitions** (grep status/state columns, then find every write to them — each write site is a transition with a trigger), ownership (which actor's rows), constraints.
+**Entities** — domain concepts, not tables. Include: attributes (from schema + serializers + fixtures), relationships, **lifecycle states and transitions** (grep status/state columns, then find every write to them — each write site is a transition with a trigger), ownership (which virtual user's rows), constraints.
 
-**Commands** — every way state changes: routes, jobs, webhooks, CLI, admin consoles, DB triggers. Name them imperative `VerbNoun` in domain language: `POST /api/users/:id/status` → `ActivateUser`. For each: actor, preconditions (every `if (...) return 4xx` guard is a precondition or policy), effects, events produced. Convention: authentication/token issuance is a command (`LogInUser`, effect: "issues a session/JWT") even though it writes no rows — it changes the caller's security state.
+**Commands** — every way state changes: routes, jobs, webhooks, CLI, admin consoles, DB triggers. Name them imperative `VerbNoun` in domain language: `POST /api/users/:id/status` → `ActivateUser`. For each: virtual user, preconditions (every `if (...) return 4xx` guard is a precondition or policy), effects, events produced. Convention: authentication/token issuance is a command (`LogInUser`, effect: "issues a session/JWT") even though it writes no rows — it changes the caller's security state.
 
 **Queries** — reads and views, `GetX`/`ListX`/`SearchX`. Record the tenancy scoping each applies (a missing `WHERE user_id=` that exists elsewhere is a gaps.json security entry).
 
@@ -142,7 +142,7 @@ Run each lens over the surveyed material. Rules that counter the classic failure
 
 ### Phase 4 — Cross-check, validate, synthesize
 
-1. Cross-checks before writing: every command has an actor and at least one precondition or policy (or you explain why it is genuinely unguarded); every state transition appears in some command/workflow — if a state is only reachable by manual/DB intervention, record the transition with trigger `"none (manual/DB-only)"` AND add a gaps.json entry; every event has a producer; every api surface maps to a defined concept; every integration is used by some command/workflow.
+1. Cross-checks before writing: every command has a virtual user and at least one precondition or policy (or you explain why it is genuinely unguarded); every state transition appears in some command/workflow — if a state is only reachable by manual/DB intervention, record the transition with trigger `"none (manual/DB-only)"` AND add a gaps.json entry; every event has a producer; every api surface maps to a defined concept; every integration is used by some command/workflow.
 2. Write all 14 JSON files, sorting **unordered identity collections** by `name` (or `path`) — on first extraction too, not just re-runs. Arrays whose order carries meaning (`workflows[].steps`, and any other observed sequence) stay in their observed order: sorting them would rewrite the behavior you extracted. Run the validator: done means `0 error(s)` and exit 0, and every WARN explicitly reviewed and either fixed or justified in your summary.
 3. Write `blueprint.md`: product summary → domain map → per-domain narrative (entities/commands/events with the interesting rules) → workflows → integrations/architecture → invariants → gaps and open decisions → rebuild recommendation. Write it for the engineer who will rebuild the product and has never seen the legacy code.
 

package/skills/pikku-software-archaeology/references/blueprint.schema.json

@@ -36,7 +36,7 @@
       "required": [
         "name",
         "purpose",
-        "actors",
+        "virtualUsers",
         "capabilities",
         "terminology",
         "evidence",
@@ -49,7 +49,7 @@
           "description": "1-3 sentences: what problem, for whom"
         },
         "targetUsers": { "type": "array", "items": { "type": "string" } },
-        "actors": {
+        "virtualUsers": {
           "type": "array",
           "minItems": 1,
           "items": {
@@ -212,7 +212,7 @@
               },
               "ownership": {
                 "type": "string",
-                "description": "which actor/tenant owns rows of this entity"
+                "description": "which virtual user/tenant owns rows of this entity"
               },
               "constraints": { "type": "array", "items": { "type": "string" } },
               "evidence": { "$ref": "#/$defs/evidence" },
@@ -233,7 +233,7 @@
             "required": [
               "name",
               "domain",
-              "actor",
+              "virtualUser",
               "input",
               "preconditions",
               "effects",
@@ -247,7 +247,7 @@
                 "description": "imperative VerbNoun: ApproveInvoice"
               },
               "domain": { "$ref": "#/$defs/conceptName" },
-              "actor": { "type": "string" },
+              "virtualUser": { "type": "string" },
               "trigger": {
                 "type": "string",
                 "description": "how it is invoked today (route, job, webhook, cron)"
@@ -305,7 +305,7 @@
             "required": [
               "name",
               "domain",
-              "actor",
+              "virtualUser",
               "description",
               "returns",
               "evidence",
@@ -317,7 +317,7 @@
                 "description": "GetX / ListX / SearchX"
               },
               "domain": { "$ref": "#/$defs/conceptName" },
-              "actor": { "type": "string" },
+              "virtualUser": { "type": "string" },
               "description": { "type": "string" },
               "input": {
                 "type": "array",
@@ -448,7 +448,7 @@
             "required": [
               "name",
               "kind",
-              "actor",
+              "virtualUser",
               "trigger",
               "steps",
               "result",
@@ -458,7 +458,7 @@
             "properties": {
               "name": { "type": "string" },
               "kind": { "type": "string", "enum": ["user", "admin", "system"] },
-              "actor": { "type": "string" },
+              "virtualUser": { "type": "string" },
               "trigger": { "type": "string" },
               "steps": {
                 "type": "array",

package/skills/pikku-theme/SKILL.md

@@ -184,4 +184,4 @@ and pass them to `pikku ui theme apply`. The recipe is in `references/from-a-ref
 ## Hosted only
 
 Interactive theme pickers, design extraction, stock images, site crawling, favicon generation, AI-generated logos and
-agent-driven build flows exist only in Pikku Studio and are not part of the CLI.
+agent-driven build flows are not part of the CLI; a hosting platform may offer them.

package/skills/pikku-workflow/SKILL.md

@@ -284,7 +284,7 @@ compensated. The error arrives as `wire.graph.recoveringFrom`
 object (`{ success: false, reason }`) instead.
 
 Full step options: `description`, `retries`, `retryDelay`, `compensate: false`
-(plus `actor`, which is scenario-only — see `pikku-scenario`).
+(plus `virtualUser`, which is scenario-only — see `pikku-scenario`).
 
 ### Parallel fan-out