@pikku/skills 0.12.22 → 0.12.25

package/skills/{pikku-react-query/SKILL.md → pikku-react/references/react-query.md}

@@ -1,25 +1,5 @@
----
-name: pikku-react-query
-description: 'Use the Pikku auto-generated React Query hooks (`usePikkuQuery`, `usePikkuMutation`, `usePikkuInfiniteQuery`) to call backend RPC functions from a React frontend with full type safety. TRIGGER when: writing React components that need to call a Pikku function, fetch data, mutate data, or paginate; user mentions React Query, useQuery, useMutation, or building a frontend that talks to a Pikku backend. DO NOT TRIGGER when: working on the backend (use pikku-rpc / pikku-feature) or wiring a non-React frontend.'
-installGroups: [client, fabric]
----
-
 # Pikku React Query Hooks
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Pikku generates a typed React Query layer from your backend `expose: true`
-functions. You don't write `useQuery`/`useMutation` against `fetch`
-yourself — you call hooks named after RPCs and get full type inference for
-input + output.
 
 ## Discover what's available on the client
 
@@ -77,7 +57,7 @@ The two generated files come from `pikku.config.json`'s
 `clientFiles.fetchFile` and `clientFiles.rpcWiringsFile`. Hooks live in
 the file at `clientFiles.reactQueryFile` (typically `api.gen.ts`).
 
-`apiUrl()` is the shared server-URL helper — see **pikku-react**. Never
+`apiUrl()` is the shared server-URL helper — see `references/client.md`. Never
 inline `?? 'http://localhost:3000'`: a deploy that supplies the URL as a
 runtime binding leaves `import.meta.env.VITE_API_URL` undefined in the
 bundle, so the fallback is the branch that actually runs.
@@ -206,7 +186,7 @@ instead.
 When the project defines any workflow, the same file also gains
 `useStartWorkflow(name)` (mutation → `{ runId }`), `useRunWorkflow(name)`
 (mutation → the workflow's output) and `useWorkflowStatus(name, runId?)` (query,
-disabled until `runId` is set). See the **pikku-workflows-client** skill.
+disabled until `runId` is set). See `references/workflows.md`.
 
 ## Calling RPCs without React Query
 

package/skills/{pikku-workflows-client/SKILL.md → pikku-react/references/workflows.md}

@@ -1,26 +1,5 @@
----
-name: pikku-workflows-client
-description: 'Run Pikku workflows from a React frontend and track their progress. Covers `useRunWorkflow` (run-and-wait), `useStartWorkflow` (fire-and-poll), and `useWorkflowStatus` (live status). TRIGGER when: a React component needs to invoke or display the status of a Pikku workflow, the user mentions long-running tasks / background jobs / progress UI tied to a workflow, or asks how to start/track a workflow from the client. DO NOT TRIGGER when: the user is wiring the workflow itself (use pikku-workflow) or only making regular RPC calls (use pikku-react-query).'
-installGroups: [client]
----
-
 # Pikku Workflows — Client Hooks
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-When a project defines any workflow — DSL or `pikkuWorkflowGraph` — three
-React Query hooks are auto-generated alongside the standard RPC hooks. They handle
-the two common shapes: **run-and-wait** (short workflows where the
-client waits for the result) and **fire-and-poll** (long workflows where
-the client gets a `runId` and polls status).
 
 ## Discover what workflows exist
 
@@ -36,7 +15,7 @@ below.
 
 These hooks are generated into the same `api.gen.ts` as `usePikkuQuery` —
 no extra setup beyond `PikkuProvider` + `QueryClientProvider` (see the
-**pikku-react** and **pikku-react-query** skills).
+`references/client.md` and `references/react-query.md`).
 
 ## `useRunWorkflow(name, options?)` — run and wait
 

package/skills/pikku-scenario/SKILL.md

@@ -1,17 +1,18 @@
 ---
 name: pikku-scenario
 description: >-
-  Use when writing or running Pikku scenarios, or when asked to test Pikku functions or improve
-  test 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 flow doubles as an e2e test and a
-  staged/production health check. Covers scenario.do / expectEventually / expectError /
-  expectService / expectScore, declared steps via pikkuScenarioStep (including browser steps driven by
-  @pikku/playwright) written as intent rather than as clicks, with the actions factored into
-  shared browser utilities, actors and environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
-  `pikku scenario list|run` commands, live function coverage via `pikku dev --coverage`, and
-  plain unit tests for pure function logic. TRIGGER when: user asks about scenarios, testing a
-  Pikku function, test coverage, end-to-end flows, browser/UI e2e, or health checks. DO NOT
-  TRIGGER when: user asks about running an existing test suite (use Bash) or CI configuration.
+  Use when writing or running Pikku scenarios, running a persona as a virtual user, 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
+  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
+  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
+  runs against a stage. DO NOT TRIGGER when: user asks about running an existing suite (use
+  Bash) or CI config.
 installGroups: [core]
 ---
 
@@ -29,6 +30,13 @@ Use this skill as an execution checklist, not reference material.
 
 **`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
+
+| You are…                                                         | Read                        |
+| ---------------------------------------------------------------- | --------------------------- |
+| Writing or running scenarios                                     | this skill                  |
+| Running a persona as a model-driven virtual user against a stage | `references/persona-run.md` |
+
 ## 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.
@@ -379,10 +387,13 @@ identifier is an API, and it is read by the toolchain.
 
 ```typescript
 // pikku.config.json: { "metaLocale": "de" }
-export const buysAnApple = pikkuScenarioStep<{ qty: number }, { orderId: string }>({
-  name: 'buysAnApple',          // identifier — English, always
-  description: 'kauft einen Apfel',  // prose — follows locale
-  template: 'kauft {qty} Äpfel',     // prose — follows locale
+export const buysAnApple = pikkuScenarioStep<
+  { qty: number },
+  { orderId: string }
+>({
+  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 }),
@@ -396,11 +407,10 @@ 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> the <actor> <template>` (`composeStepProse`), and both the
-keyword and the article `the` are English literals. The Console translates the
-Given/When/Then keywords into its own UI language; the CLI reporter does not, and
-nothing translates `the`. So `metaLocale: "de"` gives you German step prose inside an
-English frame — `Given the shopper kauft 1 Äpfel`. Write templates that read
+sentence as `<Keyword> <actor> <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
@@ -502,6 +512,7 @@ Rules that bite:
 - **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.
 
 #### What a step is given
@@ -548,7 +559,7 @@ Two consequences follow, and both shape how steps get written:
   as an RPC — which usually improves the product, since a client debugging the
   same problem needed it too.
 - **`agentRunner` is conditional.** It is built only when the project declares
-  agents, and `createDevAgentRunner` needs a base URL *and* a key together
+  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
@@ -596,12 +607,16 @@ import type messages from '../../../../apps/web/messages/en.json'
 
 export type MessageKey = keyof typeof messages
 
-export const t = (key: MessageKey, locale = baseLocale): string => { /* … */ }
+export const t = (key: MessageKey, locale = baseLocale): string => {
+  /* … */
+}
 ```
 
 ```typescript
 await page.getByLabel(t('jobs_apply_fullname')).fill(identity.name)
-await page.getByRole('button', { name: t('jobs_apply_submit'), exact: true }).click()
+await page
+  .getByRole('button', { name: t('jobs_apply_submit'), exact: true })
+  .click()
 ```
 
 - 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.
@@ -676,11 +691,11 @@ Generated files are exempt and never claim the slot.
 What that admits and what it does not:
 
 ```typescript
-personality: 'Wound up and short with it.'      // read
+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
+  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
@@ -704,14 +719,14 @@ An actor with no `persona` is its own persona, so a project that never declares
 ### The same actors sign a human in
 
 Declared actors are not only for automated runs. `signInPath` is Better Auth's
-`actor` plugin (see `pikku-better-auth`, a separate install), which any caller can post to — so the
+`actor` plugin (see `pikku-auth`, a separate install), which any caller can post to — so the
 frontend gets a one-click "Sign in as …" switcher over the **same** list, and an
 app can be reviewed as each kind of user without anyone knowing a seed password.
 
 The sandbox dev server bakes both halves into the frontend from the declared
 personas: `VITE_DEV_ACTORS` (the JSON actor list) and `VITE_DEV_ACTOR_SECRETS`
 (`{ email: credential }`, one per persona — `SCENARIO_ACTOR_SECRET` itself never
-goes in a bundle; see **pikku-better-auth**). Neither var is set in a production
+goes in a bundle; see **pikku-auth**). Neither var is set in a production
 build, so the control renders nothing there — but gate the reads on your
 bundler's dev flag anyway (`import.meta.env.DEV ? … : undefined`) so no
 credential reaches a production bundle in the first place.
@@ -825,22 +840,22 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 
 ## Red flags
 
-| 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.                                                                                        |
-| 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 `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 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. |
+| 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.                                                                                                             |
+| 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 `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 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.
 

package/skills/pikku-scenario/references/persona-run.md

@@ -0,0 +1,148 @@
+# Running a persona as a virtual user
+
+`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
+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:
+what it produces is _findings_, and their absence is only ever "not this time,
+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
+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
+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 \
+  --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
+`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                                                |
+| `--steps`              | Model turns before it stops (default 40)                                                                                                              |
+| `--mutations`          | Non-read calls before it stops                                                                                                                        |
+| `--duration`           | Wall clock before it stops, e.g. `30m`                                                                                                                |
+| `--seed`               | Replay — the same seed schedules the same run                                                                                                         |
+| `--model`              | The model they think with                                                                                                                             |
+| `--allow-approval`     | Offer the endpoints the app marked as needing a human's approval. Off by default: those are the ones that spend money                                 |
+| `--skip-role-check`    | Start without verifying declared roles against the stage                                                                                              |
+| `--api-url`            | Override the environment's `apiUrl`, for a target that only exists at run time. It replaces the url, not the environment's classification — see below |
+| `--out`                | Write the whole run — every step, response and finding — as JSON                                                                                      |
+
+## 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
+dials without replacing the character — a tuned `careless` user is still
+careless. Passing `--disposition` drops the persona's `tuning`, because you
+asked to run them differently rather than to bend their dials into another
+shape.
+
+| Disposition   | Who that is                                                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `realistic`   | The default. A competent user reading schemas and entering plausible values                                                   |
+| `careless`    | Busy, interrupted, half-remembering; submits twice, enters odd-but-legal values. **Where most production bugs actually live** |
+| `newcomer`    | First time here, holds no ids in their head, must find a path from the lists that exist (`emptyMemory`)                       |
+| `stale`       | Working from old notes — reaches for ids that may no longer resolve, to see how the product says so                           |
+| `auditor`     | Reconciling, not achieving: reads one fact from every endpoint claiming to know it and reports disagreement. Read-only        |
+| `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
+
+Three variables, checked in this order. None of them belongs in
+`pikku.config.json`.
+
+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.
+
+## Production is opt-in, twice
+
+A persona'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
+own, or whatever `--disposition` replaced it with — before the run starts. So
+`--disposition adversarial` cannot point an accountable persona at production.
+The build check trusts the file; the run check does not trust which artifact got
+deployed.
+
+**That rule is keyed on the environment's name, not its url.** `production:
+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
+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.
+
+## 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
+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
+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                                          |
+
+`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 `pikkuFabric` 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`
+  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.
+- **Do not use `--api-url` to reach a production host from a non-production
+  environment.** The disposition guard reads the named environment's
+  `production` flag, not the url you pointed it at, so nothing will stop you.
+- **Do not put any of the three credentials in `pikku.config.json`.** They are
+  environment variables.
+- **Do not pass `--allow-approval` casually.** The endpoints behind it are the
+  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;
+  a run that replaces Susan's goals is not Susan.

package/skills/pikku-service-backends/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: pikku-service-backends
+description: >-
+  Use when picking or wiring a backend for one of Pikku's core service interfaces — ContentService
+  (S3, Backblaze B2), QueueService (SQS), SecretService (AWS Secrets Manager, Redis, MongoDB),
+  SchemaService (AJV, cfworker), ChannelStore, EventHubStore, WorkflowService, SessionStore or
+  AgentRunService (Redis, MongoDB). Covers which backend to choose, what each one silently does
+  differently, and the failures they swallow. TRIGGER when: code uses S3Content, B2Content,
+  SQSQueueService, AWSSecrets, RedisChannelStore, RedisSecretService, MongoDBChannelStore,
+  PikkuMongoDB, AjvSchemaService or CFWorkerSchemaService, or the user asks how to store files,
+  secrets, channel state or sessions. DO NOT TRIGGER when: defining service factories themselves
+  (use pikku-services), SQL via Kysely (use pikku-kysely), or the Lambda/Cloudflare runtimes
+  themselves (use pikku-deploy).
+installGroups: [core]
+---
+
+# Pikku Service Backends
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
+3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+
+Constructor shapes and method signatures come from `pikku doc` — run
+`pikku doc --ai` for the installed surface. This skill is the part the compiler
+cannot tell you: which backend implements which interface, and what changes when
+you swap one for another.
+
+`pikku-services` covers how to build and wire a service. This covers what to put
+behind the interface.
+
+## Pick a backend
+
+| Interface | Backends | Package |
+| --- | --- | --- |
+| `ContentService` | `S3Content`, `B2Content` | `@pikku/aws-services`, `@pikku/backblaze` |
+| `QueueService` | `SQSQueueService` | `@pikku/aws-services` |
+| `SecretService` | `AWSSecrets`, `RedisSecretService`, `MongoDBSecretService` | `@pikku/aws-services`, `@pikku/redis`, `@pikku/mongodb` |
+| `SchemaService` | `AjvSchemaService`, `CFWorkerSchemaService` | `@pikku/schema-ajv`, `@pikku/schema-cfworker` |
+| `ChannelStore`, `EventHubStore` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
+| `PikkuWorkflowService`, `WorkflowRunService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
+| `SessionStore`, `AgentRunService`, `DeploymentService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
+| `AgentStorageService`, `AgentRunStateService` | MongoDB **only** | `@pikku/mongodb` |
+
+SQL is the third option for every store interface in that table —
+`KyselyChannelStore`, `KyselyWorkflowService`, `KyselySecretService` and friends
+live in `@pikku/kysely` and are covered by `pikku-kysely`, because using them
+means writing queries.
+
+Per-package detail: `references/aws.md`, `references/backblaze.md`,
+`references/redis.md`, `references/mongodb.md`, `references/schema.md`.
+
+## What changes when you swap a backend
+
+### Redis and MongoDB are not interchangeable, in two ways
+
+They cover almost the same interface list, but:
+
+- **MongoDB has AI conversation storage and Redis does not.**
+  `MongoDBAgentStorageService` is the only implementation of
+  `AgentStorageService`/`AgentRunStateService`. A Redis-only deployment cannot
+  persist agent conversations.
+- **Every MongoDB service needs `await init()`; no Redis service does.** `init()`
+  is what creates the collections and indexes. Constructing a
+  `MongoDBChannelStore` and using it without awaiting `init()` compiles and then
+  behaves like an unindexed collection — slow first, wrong later.
+
+Redis services take the connection directly (an ioredis `Redis`, `RedisOptions`,
+or a URL string). MongoDB services take a `Db`, which means a `PikkuMongoDB`
+wrapper has to be constructed and initialised before any of them.
+
+### The two content backends share a design and a trap
+
+`S3Content` and `B2Content` are close enough to swap, and both:
+
+- treat `bucket` on every call as a **logical** bucket stored as a path prefix
+  (`${bucket}/${key}`) inside the one real bucket the config names. Do not
+  provision a bucket per logical bucket — the config takes exactly one.
+- **ignore `visibility` on `getUploadURL`**.
+- **swallow write failures**: `writeFile`, `copyFile` and `deleteFile` log and
+  return `false` rather than throwing, while the read paths throw. An ignored
+  return value is a silently lost file.
+
+Where they diverge:
+
+| | `S3Content` | `B2Content` |
+| --- | --- | --- |
+| Signing failure | **Fails open** — logs and returns the *unsigned* URL | Throws |
+| `writeFile` memory | Streams | **Buffers the whole stream** to compute a SHA-1 |
+| Client-side upload integrity | Presigned, expires at a fixed 3600s | `X-Bz-Content-Sha1: do_not_verify` — unverified |
+| Credential rotation | Picked up by the SDK provider chain | Auth is cached for the instance's lifetime — construct a new `B2Content` |
+
+The S3 fail-open is the one to design around: on a private CloudFront
+distribution the client gets a 403, and on a public one you have just handed out
+an unrestricted link. Validate `signConfig` at boot rather than trusting a throw.
+
+### Secret backends differ on whether the app can write
+
+- **`AWSSecrets` is read-only.** `setSecret` and `deleteSecret` throw. Secrets
+  are managed out of band; the app only reads them.
+- **Redis and MongoDB do envelope encryption** and can write, delete, and
+  `rotateKEK()`. Rotation requires `previousKey` to have been set — a service
+  constructed without it cannot rotate later without a redeploy.
+- **Only MongoDB has audit hooks** (`audit`, `auditReads`).
+
+`AWSSecrets` also collapses every failure — missing, denied, binary-only — into
+the same `FATAL: Error finding secret: <id>`, with the real reason on the error's
+`cause`. Read `cause` before concluding a secret is absent; `hasSecret` returns
+`false` for any error and cannot distinguish the two either.
+
+### AJV and cfworker are not drop-in equivalents
+
+Swapping them changes behaviour without changing types:
+
+- **`useDefaults`**: AJV fills schema defaults into the validated object in
+  place. cfworker does not, so a field you relied on being defaulted arrives
+  `undefined` on Workers.
+- **Recompilation**: AJV caches by name for the process lifetime — a second
+  `compileSchema` with the same name is a no-op. cfworker replaces the validator
+  when the schema value changes, which is what lets a dev hot-reload pick up
+  regenerated schemas. On AJV, restart the process instead.
+- **Coercion is neither one's job.** `coerceTypes` is off; a query-string `"1"`
+  becomes `1` in the wiring layer, not here.
+
+Both throw `UnprocessableContentError` (422) on a failed validation, and both
+throw a **bare string** — `Missing validator for <name>` — for a *missing*
+schema. It is not an `Error`, so `catch (e) { e.message }` reads `undefined`.
+That almost always means codegen did not run.
+
+Use cfworker on Cloudflare Workers: AJV compiles with `new Function`, which the
+Workers runtime forbids.
+
+### SQS gives you no result back
+
+`SQSQueueService` sets `supportsResults = false` and `getJob()` always throws —
+the transport is fire-and-forget. So is the Azure Storage Queue backend. Reach
+for BullMQ or PgBoss (see `pikku-wiring`) when a caller needs the job's result.
+
+## What NOT to do
+
+- Do not ignore the boolean from `writeFile`, `copyFile` or `deleteFile`. Both
+  content backends report failure that way and neither throws.
+- Do not rely on `S3Content.signURL` throwing. It fails open and hands back an
+  unsigned URL.
+- Do not construct a MongoDB-backed service without awaiting `init()`.
+- Do not assume AJV and cfworker validate identically — `useDefaults` alone
+  changes what your function receives.
+- Do not provision one real bucket per logical bucket; the prefix is the bucket.
+- Do not reach for SQS when a caller needs the result of the job.