@pikku/skills 0.12.21 → 0.12.25

package/skills/pikku-react/references/client.md

@@ -0,0 +1,293 @@
+# Pikku React
+
+
+## What ships
+
+```tsx
+import {
+  PikkuProvider,
+  createPikku,
+  usePikkuFetch,
+  usePikkuRPC,
+  usePikkuRealtime,
+  usePikkuAgent,
+  usePikkuWorkflow,
+  asI18n,
+} from '@pikku/react'
+```
+
+`usePikkuRealtime` is only valid when you wired a `PikkuRealtime` class via
+`createPikku` — see the setup section. `usePikkuAgent` and `usePikkuWorkflow`
+are thin bindings over the RPC client that pin one agent/workflow name, so a
+component never repeats it. `asI18n` is the i18n brand (see **pikku-i18n**).
+
+## Resolving the server URL
+
+Every client (`createPikku`, realtime, the auth client) resolves its base
+through one shared helper in `src/lib/env.ts`. Write this once:
+
+```ts
+// Endpoints come from env, never hardcoded.
+export function apiUrl(): string {
+  // SSR: the client hooks only run in the browser, so a placeholder is fine.
+  if (import.meta.env.SSR) {
+    return import.meta.env.VITE_API_URL ?? '/__api'
+  }
+  return import.meta.env.VITE_API_URL ?? `${window.location.origin}/api`
+}
+```
+
+**Never fall back to `http://localhost:3000`.** `import.meta.env.VITE_API_URL`
+is substituted by Vite at _build_ time, so any deploy that supplies the URL as
+a _runtime_ env var or platform binding leaves it `undefined` in the shipped
+bundle — the fallback is then the only branch that ever runs in the browser. A
+localhost fallback means every request from a deployed app goes to the user's
+own machine. `origin + '/api'` is same-origin, needs no build-time knowledge of
+the domain, and is correct wherever the app is served from.
+
+For local dev, set `VITE_API_URL`, or proxy `/api` → your backend in
+`vite.config.ts` under `server.proxy`. One `/api` entry also covers
+`/api/auth/*`; only add more entries for root-level routes outside `/api`.
+
+## Setup at the app root
+
+```tsx
+import { createPikku, PikkuProvider } from '@pikku/react'
+import { PikkuFetch } from './pikku/pikku-fetch.gen'
+import { PikkuRPC } from './pikku/pikku-rpc.gen'
+import { apiUrl } from './lib/env'
+
+const pikku = createPikku(PikkuFetch, PikkuRPC, {
+  serverUrl: apiUrl(),
+})
+
+createRoot(document.getElementById('root')!).render(
+  <PikkuProvider pikku={pikku}>
+    <App />
+  </PikkuProvider>
+)
+```
+
+If the project also exposes realtime events (see **pikku-wiring**), pass
+the `PikkuRealtime` class as the third argument and the instance gets a
+`realtime` field too:
+
+```tsx
+import { PikkuRealtime } from './pikku/realtime.gen'
+
+const pikku = createPikku(PikkuFetch, PikkuRPC, PikkuRealtime, {
+  serverUrl: apiUrl(),
+})
+// pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch
+// (server URL + auth configured once).
+```
+
+The generated classes come from your `pikku.config.json`:
+
+| config field                 | generated file                                        |
+| ---------------------------- | ----------------------------------------------------- |
+| `clientFiles.fetchFile`      | typed HTTP client (`PikkuFetch` class)                |
+| `clientFiles.rpcWiringsFile` | RPC client (`PikkuRPC` class) calling all exposed fns |
+| `clientFiles.realtimeFile`   | `PikkuRealtime` (websocket events + SSE + channels)   |
+
+If a file isn't being generated, that field is missing from the config —
+add it and re-run `pikku all`.
+
+`createPikku(...)` accepts the same `CorePikkuFetchOptions` as `PikkuFetch`
+plus `serverUrl`. Auth headers, request interceptors, etc. are configured
+on the fetch instance — RPC and realtime inherit them automatically.
+
+## Calling an RPC directly (no React Query)
+
+Inside a component:
+
+```tsx
+import { usePikkuRPC } from '@pikku/react'
+
+function Logout() {
+  const rpc = usePikkuRPC()
+  return <button onClick={() => rpc.invoke('logoutUser', {})}>Sign out</button>
+}
+```
+
+`rpc.invoke(name, data)` is typed against `FlattenedRPCMap` — `name` must
+be an exposed function id, `data` matches the input schema, return value
+matches the output schema.
+
+You also have `rpc.<funcName>(data)` if the generated RPC client builds
+direct methods (project-dependent).
+
+## Calling fetch directly
+
+```tsx
+const fetch = usePikkuFetch()
+const data = await fetch.get('/some-rest-route', { searchParams: {...} })
+```
+
+Use this only when the function is wired via HTTP (REST shape) and you
+need a path-style call. For RPC calls, `usePikkuRPC()` is cleaner.
+
+## Realtime subscriptions
+
+If you wired a `PikkuRealtime` class into `createPikku`, use
+`usePikkuRealtime()` to grab the shared instance:
+
+```tsx
+import { usePikkuRealtime } from '@pikku/react'
+import type { PikkuRealtime } from './pikku/realtime.gen'
+
+function TodoList() {
+  const realtime = usePikkuRealtime<PikkuRealtime>()
+  useEffect(() => {
+    return realtime.subscribe('todo-created', ({ todo }) => {
+      /* ... */
+    })
+  }, [realtime])
+  // ...
+}
+```
+
+The hook throws if no `PikkuRealtime` was wired — that's how you know to
+add it to `createPikku(...)`. Full event-hub setup, publishing, and SSE
+helpers live in **pikku-wiring**.
+
+## When to reach for what
+
+| Need                                | Use                                                |
+| ----------------------------------- | -------------------------------------------------- |
+| Render data, dedupe + cache         | **usePikkuQuery** (react-query)                    |
+| Trigger a write, wait for result    | **usePikkuMutation** (react-query)                 |
+| Paginate                            | **usePikkuInfiniteQuery** (react-query)            |
+| One-off call from an event handler  | `usePikkuRPC()` direct                             |
+| Hit a REST endpoint (not RPC)       | `usePikkuFetch()`                                  |
+| Run one named workflow              | `usePikkuWorkflow('name')` → `.start/.run/.status` |
+| Talk to one named AI agent          | `usePikkuAgent('name')` → `.run/.stream/.approve`  |
+| Longer-running workflow UX          | `references/workflows.md`               |
+| Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-wiring**)      |
+
+The first three live in your generated `api.gen.ts` (see the
+`references/react-query.md`). This reference covers the rest.
+
+`usePikkuAgent` and `usePikkuWorkflow` bind the name once and hand back the
+call methods with it already applied:
+
+```tsx
+const agent = usePikkuAgent('todo-agent')
+const { text } = await agent.run({ message, threadId })
+
+const workflow = usePikkuWorkflow('onboardUser')
+const { runId } = await workflow.start({ email })
+const state = await workflow.status(runId)
+```
+
+## Authentication
+
+Auth is handled at the `PikkuFetch` layer, and `createPikku`'s options object
+_is_ `CorePikkuFetchOptions` plus `serverUrl` — flat, not nested under a
+`fetchOptions` key:
+
+```tsx
+const pikku = createPikku(PikkuFetch, PikkuRPC, {
+  serverUrl: apiUrl(),
+  credentials: 'include', // cookie sessions
+  authHeaders: { jwt: token }, // or { apiKey }
+  transformDate: true,
+})
+```
+
+There is no request-interceptor hook. For a token that changes after startup,
+call the setter on the shared instance — RPC and realtime pick it up because
+they hold the same fetch:
+
+```tsx
+pikku.fetch.setAuthorizationJWT(token) // null clears it
+pikku.fetch.setAPIKey(key)
+pikku.fetch.setHeader('x-tenant', tenantId)
+```
+
+`authHeaders.jwt` becomes `Authorization: Bearer …` and `authHeaders.apiKey`
+becomes `X-API-KEY`; setting a JWT takes precedence over an API key.
+
+### Dev actor sign-in (`useDevActors`)
+
+The dev-only "Sign in as …" control: one click signs in as a declared scenario
+persona with no password, so the app can be reviewed as each kind of user.
+`pikku fabric validate` **requires** any frontend with a login screen to ship one
+(`app-missing-actor-quick-login-<app>`) — without it a reviewer is locked out of
+their own sandbox.
+
+```tsx
+import { useDevActors } from '@pikku/react'
+
+const { actors, signInAs, pendingEmail, isPending, error } = useDevActors({
+  // Gate both reads on the bundler's dev flag so no credential can reach a
+  // production bundle. The sandbox dev server bakes them from your personas.
+  actors: import.meta.env.DEV ? import.meta.env.VITE_DEV_ACTORS : undefined,
+  secrets: import.meta.env.DEV
+    ? import.meta.env.VITE_DEV_ACTOR_SECRETS
+    : undefined,
+  apiUrl: apiUrl(),
+  onSignedIn: () => navigate({ to: '/' }),
+})
+```
+
+- **It is UI-free**, so render it however you like. For the default rendering use
+  `<DevActorSwitcher />` from `@pikku/mantine/dev` — a separate entry point from
+  `@pikku/mantine/core`, whose contract is "drop-in alias for `@mantine/core`"
+  and so must not export components Mantine has no counterpart for.
+- **`secrets` is `{ address: credential }`, not one shared value** — a
+  credential opens the one persona it was minted for (see
+  **pikku-auth**). `actors` is empty unless the host supplied both a list
+  and the credentials for it, and an actor with no credential is not offered, so
+  a production build renders nothing without you testing for it.
+- **It takes `onSignedIn` rather than a router**, and takes the env values rather
+  than reading them, because how env is spelled is a bundler fact
+  (`import.meta.env.VITE_*` vs `process.env.NEXT_PUBLIC_*`).
+- The underlying `signInAsActor()` and `parseDevActors()` are exported too, for a
+  non-React caller. The endpoint only accepts rows flagged `actor: true`, so it
+  can never impersonate a real user — see **pikku-auth**.
+
+Do not hand-write the `devActors()` / `signInAsActor()` pair per app; that
+copy-paste, including the `import.meta.env.DEV` gate, is exactly what this
+replaced.
+
+### Linking from a Mantine element: `renderRoot`, not `component`
+
+Handing TanStack's `Link` to a Mantine element as `component={Link}` compiles,
+renders, and navigates — and silently unties the type. Mantine's polymorphic
+`component` prop widens the router generic to `AnyRouter`, so `to` and
+`params` stop being checked against your actual routes. Renaming a route then
+breaks the running app instead of the build, which is the one thing the typed
+router exists to prevent.
+
+Wrap the typed `Link` once and reach it through `renderRoot`, which passes the
+props through without re-typing the element:
+
+```tsx
+// components/links.tsx — one wrapper the whole app links through
+import { Link } from '@tanstack/react-router'
+
+export const AssessmentLink = (props: { assessmentId: string; children: React.ReactNode }) => (
+  <Link to="/assessments/$assessmentId" params={{ assessmentId: props.assessmentId }}>
+    {props.children}
+  </Link>
+)
+```
+
+```tsx
+<Button renderRoot={(p) => <AssessmentLink assessmentId={id} {...p} />}>
+  Open
+</Button>
+```
+
+The wrapper is where `to` and `params` are checked, and it is checked once.
+
+## What NOT to do
+
+- Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`
+  goes once at the app root, the instance flows through Context.
+- Don't call `usePikkuRPC()` outside a `<PikkuProvider>` — it throws.
+- Don't write a custom RPC client. The generated one already covers every
+  exposed function with full types.
+- Don't hardcode user-facing strings. Every display string goes through an
+  i18n token — see **pikku-i18n** for the setup (it's English-only by default).

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.
@@ -46,7 +54,7 @@ Scenarios live in `srcDirectories` like any other function — by convention `*.
 `pikkuScenario` comes from the **generated** workflow types, not `@pikku/core`:
 
 ```typescript
-import { pikkuScenario } from '#pikku/scenario'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const orderSupportScenario = pikkuScenario<
   { value?: number },
@@ -175,7 +183,7 @@ Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs
 `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
-import { pikkuFeature } from '#pikku/scenario'
+import { pikkuFeature } from '#pikku/scenarios'
 import {
   credentialLazyLoadScenario,
   credentialRoundTripScenario,
@@ -240,7 +248,7 @@ Utilities are **not steps**. They are plain exported functions, they take the br
 
 ```typescript
 // shop.browser.ts — shared actions. Not steps: nothing here is an intent.
-import type { PikkuBrowserWire } from '#pikku/scenario'
+import type { PikkuBrowserWire } from '#pikku/scenarios'
 import type {} from '@pikku/playwright'
 
 /** Arrive on the shop, from wherever the browser happens to be. */
@@ -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
@@ -462,7 +472,7 @@ Assertions with no possible browser witness are a different thing and should not
 `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.
 
 ```typescript
-import { pikkuScenarioStep } from '#pikku/scenario'
+import { pikkuScenarioStep } from '#pikku/scenarios'
 
 export const buysAnApple = pikkuScenarioStep<
   { qty: number },
@@ -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.