@pikku/skills 0.12.10 → 0.12.12

package/skills/pikku-product-second-opinion/references/report-template.md

@@ -6,7 +6,8 @@ reader. Delete any section that would be empty rather than padding it.
 ---
 
 # {App name}, in plain English — and where it could get better
-*A second opinion on {scope: the whole app / the competitor-tracking system / …}*
+
+_A second opinion on {scope: the whole app / the competitor-tracking system / …}_
 
 **How to read this:** no technical background needed. Part 1 is the summary — if
 you read nothing else, read that. Parts 2–3 go area by area for anyone who wants
@@ -21,9 +22,9 @@ opportunities. No jargon.}
 
 **If it were me, this is the order I'd tackle things:**
 
-| Fix | Why it matters to you | Effort | Payoff |
-|---|---|---|---|
-| {…} | {business impact} | Small/Medium/Large | High/Medium/Low |
+| Fix | Why it matters to you | Effort             | Payoff          |
+| --- | --------------------- | ------------------ | --------------- |
+| {…} | {business impact}     | Small/Medium/Large | High/Medium/Low |
 
 ---
 
@@ -38,6 +39,7 @@ opportunities. No jargon.}
 **What's working.** {genuine credit — the parts that are solid and worth keeping}
 
 **What's holding you back.**
+
 - **{Problem in plain terms}.** What it means for you: {business impact}.
   Severity: {Minor / Worth fixing / Serious / Urgent}. Effort to fix: {Small /
   Medium / Large}.
@@ -54,11 +56,12 @@ off. Say whether it's a cheap rewire or an expensive rebuild.}
 libraries — AND anything a rebuild would move them ONTO. Each gets both sides.}
 
 **{Technology}.**
-- *Buys you:* {in business terms}
-- *Costs you:* {in business terms — bills, hiring, shipping speed, upgrade work,
+
+- _Buys you:_ {in business terms}
+- _Costs you:_ {in business terms — bills, hiring, shipping speed, upgrade work,
   the risk of betting on something young. Don't soften it. If it hasn't shipped a
   stable 1.0, say so and say what that means: pin the version, budget upgrades.}
-- *Usually:* {recommendation tied to their stage — normally "keep it, watch this"}
+- _Usually:_ {recommendation tied to their stage — normally "keep it, watch this"}
 
 {The same bar applies to anything you're recommending they move to. A stack you
 propose with no cons listed is a pitch, not a second opinion.}

package/skills/pikku-queue/SKILL.md

@@ -63,7 +63,7 @@ Not every adapter supports every option. Each adapter declares a
 silently ignored — so check the startup logs if a setting appears to have no
 effect.
 
-`groupConcurrency` limits how many jobs run concurrently *per group* (jobs
+`groupConcurrency` limits how many jobs run concurrently _per group_ (jobs
 carrying a `JobGroup` with an `id` and optional `tier`), so one noisy tenant
 cannot consume the whole worker:
 

package/skills/pikku-react/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-react
-description: 'Set up @pikku/react in a React app: PikkuProvider context, createPikku factory, and the usePikkuRPC / usePikkuFetch hooks for direct (non-React-Query) calls. TRIGGER when: the user is bootstrapping a React frontend that talks to a Pikku backend, asks how to wire `PikkuProvider`, or needs to make one-off RPC calls outside of useQuery/useMutation. DO NOT TRIGGER when: the user is asking about useQuery/useMutation hooks (use pikku-react-query) or about workflows (use pikku-workflows-client).'
+description: 'Set up @pikku/react in a React app: PikkuProvider context, createPikku factory, and the usePikkuRPC / usePikkuFetch hooks for direct (non-React-Query) calls. TRIGGER when: the user is bootstrapping a React frontend that talks to a Pikku backend, asks how to wire `PikkuProvider`, or needs to make one-off RPC calls outside of useQuery/useMutation. TRIGGER when: user asks about the dev actor switcher, "sign in as" / quick-login UI, useDevActors, VITE_DEV_ACTORS, or the app-missing-actor-quick-login validate finding. DO NOT TRIGGER when: the user is asking about useQuery/useMutation hooks (use pikku-react-query) or about workflows (use pikku-workflows-client).'
 installGroups: [core]
 ---
 
@@ -58,8 +58,8 @@ export function apiUrl(): string {
 ```
 
 **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
+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
@@ -173,17 +173,17 @@ helpers live in **pikku-realtime**.
 
 ## 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()`                             |
+| 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          | **pikku-workflows-client**                    |
-| Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-realtime**) |
+| Longer-running workflow UX          | **pikku-workflows-client**                         |
+| Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-realtime**)      |
 
 The first three live in your generated `api.gen.ts` (see the
 **pikku-react-query** skill). This skill covers the rest.
@@ -203,7 +203,7 @@ 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
+_is_ `CorePikkuFetchOptions` plus `serverUrl` — flat, not nested under a
 `fetchOptions` key:
 
 ```tsx
@@ -228,6 +228,46 @@ 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 the secret cannot 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,
+  secret: import.meta.env.DEV
+    ? import.meta.env.VITE_SCENARIO_ACTOR_SECRET
+    : 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.
+- **`actors` is empty unless the host supplied both a list and a secret**, 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-better-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.
+
 ## What NOT to do
 
 - Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`

package/skills/pikku-realtime/SKILL.md

@@ -66,8 +66,7 @@ see `pikku-services`.
 ## 2. Enable the server side
 
 ```bash
-yarn pikku enable events           # auth required by default
-yarn pikku enable events --noAuth  # public events
+yarn pikku enable events
 ```
 
 This sets `scaffold.events` in `pikku.config.json`. The next `pikku all` generates
@@ -97,19 +96,38 @@ a one-word change, not a different import:
 
 ```ts
 export class PikkuRealtime {
-  constructor(options?: { reconnect?: boolean; reconnectDelayMs?: number; reconnectMaxDelayMs?: number })
-  setPikkuFetch(fetch: PikkuFetch): void   // server URL + auth come from here, not the constructor
+  constructor(options?: {
+    reconnect?: boolean
+    reconnectDelayMs?: number
+    reconnectMaxDelayMs?: number
+  })
+  setPikkuFetch(fetch: PikkuFetch): void // server URL + auth come from here, not the constructor
 
   // WebSocket at /events — many topics on one connection
-  subscribe<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): () => void
-  unsubscribe<K extends keyof EventHubTopics>(topic: K, handler?: (data: EventHubTopics[K]) => void): void
+  subscribe<K extends keyof EventHubTopics>(
+    topic: K,
+    handler: (data: EventHubTopics[K]) => void
+  ): () => void
+  unsubscribe<K extends keyof EventHubTopics>(
+    topic: K,
+    handler?: (data: EventHubTopics[K]) => void
+  ): void
 
   // SSE at GET /events/:topic — one EventSource per topic
-  subscribeToTopic<K extends keyof EventHubTopics>(topic: K, handler: (data: EventHubTopics[K]) => void): { close: () => void }
+  subscribeToTopic<K extends keyof EventHubTopics>(
+    topic: K,
+    handler: (data: EventHubTopics[K]) => void
+  ): { close: () => void }
 
   // generic escape hatches — see references/other-routes.md
-  subscribeToSSE<T>(path: string, handler: (data: T) => void): { close: () => void }
-  connectToChannel(channelRoute: string, protocols?: string | string[]): WebSocket
+  subscribeToSSE<T>(
+    path: string,
+    handler: (data: T) => void
+  ): { close: () => void }
+  connectToChannel(
+    channelRoute: string,
+    protocols?: string | string[]
+  ): WebSocket
 
   close(): void
 }
@@ -137,14 +155,16 @@ Envelope the payload as `{ topic, data }`: the generated client dispatches on th
 `topic` field, so a bare payload arrives but no handler fires.
 
 ```ts
-import { pikkuFunc } from '#pikku'
+import { pikkuFunc } from '#pikku/function'
 
 export const createTodo = pikkuFunc({
   input: CreateTodoInput,
   output: CreateTodoOutput,
   func: async ({ kysely, eventHub }, data) => {
     const todo = await kysely
-      .insertInto('todos').values(data).returningAll()
+      .insertInto('todos')
+      .values(data)
+      .returningAll()
       .executeTakeFirstOrThrow()
 
     await eventHub.publish('todo-created', null, {
@@ -160,7 +180,9 @@ A thin helper removes the duplication:
 
 ```ts
 async function publishEvent<K extends keyof EventHubTopics>(
-  hub: EventHubService<EventHubTopics>, topic: K, data: EventHubTopics[K]
+  hub: EventHubService<EventHubTopics>,
+  topic: K,
+  data: EventHubTopics[K]
 ) {
   return hub.publish(topic, null, { topic, data })
 }
@@ -187,7 +209,9 @@ const pikku = createPikku(
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
 
 createRoot(document.getElementById('root')!).render(
-  <PikkuProvider pikku={pikku}><App /></PikkuProvider>
+  <PikkuProvider pikku={pikku}>
+    <App />
+  </PikkuProvider>
 )
 ```
 
@@ -214,7 +238,8 @@ function TodoList() {
   useEffect(() => {
     // WebSocket multi-topic:
     const off = realtime.subscribe('todo-created', ({ todo }) =>
-      setTodos((prev) => [...prev, todo]))
+      setTodos((prev) => [...prev, todo])
+    )
     return off
 
     // Single-topic SSE (auto-cleanup on close) instead:
@@ -223,7 +248,13 @@ function TodoList() {
     // return () => sub.close()
   }, [realtime])
 
-  return <ul>{todos.map((t) => <li key={t.id}>{t.title}</li>)}</ul>
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.title}</li>
+      ))}
+    </ul>
+  )
 }
 ```
 
@@ -235,12 +266,12 @@ sockets (`subscribeToSSE`, `connectToChannel`). See
 
 ## When to pick which transport
 
-| Need                                       | Use                           |
-| ------------------------------------------ | ----------------------------- |
-| Many topics in one connection              | `realtime.subscribe`          |
-| Single live stream, simple cleanup         | `realtime.subscribeToTopic`   |
-| Bidirectional (client also sends messages) | `realtime.subscribe`          |
-| WebSockets blocked by infra                | `realtime.subscribeToTopic`   |
+| Need                                       | Use                         |
+| ------------------------------------------ | --------------------------- |
+| Many topics in one connection              | `realtime.subscribe`        |
+| Single live stream, simple cleanup         | `realtime.subscribeToTopic` |
+| Bidirectional (client also sends messages) | `realtime.subscribe`        |
+| WebSockets blocked by infra                | `realtime.subscribeToTopic` |
 
 Both auto-clean on the server (the eventHub's `onChannelClosed` hook unsubscribes
 all topics for the dead channel id). Don't write manual cleanup unless you're

package/skills/pikku-rpc/SKILL.md

@@ -75,10 +75,12 @@ The `POST /rpc/:rpcName` endpoint that dispatches every `expose: true` function
 is **generated, not hand-written**. Turn it on and let codegen own it:
 
 ```bash
-pikku enable rpc            # sets scaffold.rpc = true (auth required)
-pikku enable rpc --noAuth   # sets scaffold.rpc = { auth: false } (public)
+pikku enable rpc            # sets scaffold.rpc = true
 ```
 
+The flag says the endpoint exists, not who may call it — each exposed function
+is gated by its own `auth`, permissions and scopes.
+
 This writes `rpc-public.gen.ts` with an `rpcCaller` function and its `wireHTTP`
 call already wired. Do not write that wiring yourself — a hand-rolled copy
 collides with the generated route on the same path.

package/skills/pikku-rtl/SKILL.md

@@ -18,7 +18,7 @@ Set `dir` **once at the document root** from the active locale, then let the
 browser and Mantine mirror everything — _provided_ every custom style is written
 **flow-relative** (start/end), never **physical** (left/right). Get those two
 things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
-*layout* code — directional icons still need one manual step, covered below.
+_layout_ code — directional icons still need one manual step, covered below.
 
 ## Agent Operating Procedure
 

package/skills/pikku-scenario/SKILL.md

@@ -46,7 +46,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/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenario'
 
 export const orderSupportScenario = pikkuScenario<
   { value?: number },
@@ -175,7 +175,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/workflow/pikku-workflow-types.gen.js'
+import { pikkuFeature } from '#pikku/scenario'
 import {
   credentialLazyLoadScenario,
   credentialRoundTripScenario,
@@ -240,7 +240,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/core/workflow'
+import type { PikkuBrowserWire } from '#pikku/scenario'
 import type {} from '@pikku/playwright'
 
 /** Arrive on the shop, from wherever the browser happens to be. */
@@ -377,6 +377,9 @@ export const seesTheOrderConfirmed = pikkuScenarioStep<
   { status: string }
 >({
   name: 'seesTheOrderConfirmed',
+  // Both bindings run as the persona, so the step declares one and the runner
+  // injects `wire.actor` — non-optional in every binding.
+  actor: true,
   template: 'sees order {orderId} confirmed',
   // Both run on `--run browser`. Each returns what it observed, and the runner
   // compares them — so this fails when the page disagrees with the database.
@@ -385,8 +388,9 @@ export const seesTheOrderConfirmed = pikkuScenarioStep<
       .locate({ testId: 'order-status', where: { 'data-order': orderId } })
       .getAttribute('data-status'),
   }),
-  default: async ({ rpc }, { orderId }) => ({
-    status: (await rpc.invoke('getOrder', { orderId })).status,
+  // Through the actor, not through a `rpc` service — see "What a step is given".
+  default: async (_services, { orderId }, { actor }) => ({
+    status: (await actor.invoke('getOrder', { orderId })).status,
   }),
 })
 ```
@@ -408,8 +412,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/workflow/pikku-workflow-types.gen.js'
-import { requireActor } from '@pikku/core/workflow'
+import { pikkuScenarioStep } from '#pikku/scenario'
 
 export const buysAnApple = pikkuScenarioStep<
   { qty: number },
@@ -418,8 +421,9 @@ export const buysAnApple = pikkuScenarioStep<
   name: 'buysAnApple',
   description: 'buys an apple',
   template: 'buys {qty} apples',
-  default: async (_services, { qty }, { scenarioStep }) => {
-    return await requireActor(scenarioStep).invoke('placeOrder', { qty })
+  actor: true,
+  default: async (_services, { qty }, { actor }) => {
+    return await actor.invoke('placeOrder', { qty })
   },
 })
 ```
@@ -443,12 +447,63 @@ Rules that bite:
 - **The step is referenced by its typed string name, not by importing the const** — exactly like `workflow.do`. The name is the step's `pikkuFuncId` and is checked against the generated step map. A non-literal target is a critical error (`PKU678`).
 - **Steps are not RPCs.** They are deliberately never network-callable — a browser-driving step must not be.
 - **`actor.invoke` is typed over the exposed RPC map**, so the name and the payload are checked and the result comes back narrowed — no cast. `actor.invokeRaw(name, data, { headers })` is the same call reporting `{ status, ok, body }` instead of throwing; use it whenever the refusal _is_ the assertion.
-- **`actor` and `env` are optional on the wire**, because a pure assertion step needs neither. Narrow them with `requireActor(scenarioStep)` and `requireScenarioEnv(scenarioStep)` from `@pikku/core/workflow` rather than a local guard — both name the step and say what to pass. `env` is `{ apiUrl, appUrl? }` from the environment the run targets, and is how a raw-HTTP step learns the target's URL: a step runs in the CLI process, where there is no `variables` service and `process.env` is not the answer.
+- **A step that runs as somebody declares `actor: true`**, and the runner injects `wire.actor` — non-optional inside every binding, with no guard to write and nothing to unwrap. A `browser` binding implies it, because a window is opened as somebody. Leave it off for a step with no persona to be: an assertion over what an earlier step returned, or one that posts credentials precisely because it must not reuse an actor's session. Dispatching a step that declared it without `{ actor: actors.x }` fails before the body runs (`ScenarioActorRequired`); a step that did not declare it has no `actor` on its wire at all.
+- **`env` is optional on the wire**, because most steps need nothing from it. Narrow it with `requireScenarioEnv(scenarioStep)` from `#pikku/scenario` rather than a local guard — it names the step and says what to pass. `env` is `{ apiUrl, appUrl? }` from the environment the run targets, and is how a raw-HTTP step learns the target's URL: a step runs in the CLI process, where there is no `variables` service and `process.env` is not the answer.
 - **Steps default to `retries: 0`**, unlike ordinary workflow steps. Retrying a failed assertion is wrong; pass `retries` explicitly if a step is genuinely flaky-by-nature.
 - **Step results are persisted**, so return JSON-serialisable data — never a `Locator` or a client object.
 - **`description` documents the step; `template` is what the report renders.** `template`'s `{placeholders}` are filled from the input the step was called with, so one step reads differently for each call — `sees {state} addon {packageName}` reports as "sees available addon @pikku/addon-stripe". Reflect every input field in the template, and type the values so they read as words (`state?: 'installed' | 'available'`, not `installed?: boolean`). A placeholder with no value renders as nothing and the whitespace collapses.
 - 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
+
+A step has the signature of an ordinary pikku function, which makes it look as
+though it runs where the application runs. It does not — **it runs in the CLI
+process**, and the services object is built there, by hand:
+
+```typescript
+{ logger, workflowService, workflowRunService, agentRunner? }
+```
+
+That is the whole list. There is no `kysely`, no `variables`, no `secrets`, and
+none of the project's own singleton or wire services. A step that destructures
+one gets `undefined` and fails on first use — `Cannot read properties of
+undefined (reading 'selectFrom')` — which reads like a broken container and is
+not.
+
+`rpc` is the trap worth naming, because it is present and it throws. It is a
+`guardRpc` whose every member refuses:
+
+> Scenario tried to run 'getOrder' as an internal step. Every workflow.do in a
+> scenario must carry { actor: actors.x } so it executes against 'local'.
+
+The same guard covers `rpc.agent.run/stream/resume/approve/interrupt` and
+`startWorkflow`.
+
+This is the design, not a gap: **everything a step touches of the application
+goes over the wire as somebody.** A test that could reach into the database
+would be testing a different program from the one a person uses. So there are
+exactly three ways in, and they are all through the actor:
+
+- `actor.invoke(name, data)` — typed over the exposed RPC map, carrying the
+  actor's session. Declare `actor: true` and destructure it off the wire.
+- `.invokeRaw(name, data, { headers })` — same call, reporting
+  `{ status, ok, body }`, for when the refusal is the assertion.
+- a plain `fetch` against `requireScenarioEnv(scenarioStep).apiUrl`, for
+  anything not an RPC — a websocket, a file upload, a webhook.
+
+Two consequences follow, and both shape how steps get written:
+
+- **A step cannot observe anything the app does not publish.** If a test needs a
+  fact the client never sees, the fix is to emit it on the stream or expose it
+  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
+  (`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
+  model can pass an `llm` to `runConversation` instead of relying on this one.
+
 ### Browser steps
 
 Declaring a `browser` binding is the whole switch: inside that binding `wire.browser` is guaranteed present and non-optional, and a step without one never sees a browser at all. There is nothing to null-check.
@@ -468,7 +523,9 @@ export const opensTheCart = pikkuScenarioStep<
     await browser.goto(path)
     return { url: browser.page.url() }
   },
-  default: async ({ rpc }) => ({ url: (await rpc.invoke('getCart', {})).url }),
+  default: async (_services, _data, { actor }) => ({
+    url: (await actor.invoke('getCart', {})).url,
+  }),
 })
 ```
 
@@ -525,11 +582,68 @@ A persona holds only what is true of that kind of person for the app's whole lif
 
 `kind: "system"` is the app acting on its own — a schedule, a cleanup, a send. It gets **no actor**: there is nobody to sign in. Give it one by hand only if it genuinely has a service account.
 
+#### Declaring personas in TypeScript
+
+`definePersonas({ … })` is the code form of the block above, and there may be
+**one 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 persona 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 persona: **`actor.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
+persona's instructions. Anything that must shape how someone talks belongs in
+`personality` or in the task.
+
 An actor with no `persona` is its own persona, so a project that never declares any keeps working unchanged.
 
 - `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
 - **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
 
+### The 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`), 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_SCENARIO_ACTOR_SECRET`. Neither 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 the secret never reaches a
+production bundle in the first place.
+
+Do not hand-roll the switcher: `useDevActors()` (`pikku-react`) is the logic and
+`<DevActorSwitcher />` from `@pikku/mantine/dev` is a ready rendering of it.
+`pikku fabric validate` **requires** any frontend with a login screen to ship
+one — without it a reviewer is locked out of their own sandbox.
+
 ## Running
 
 ```bash
@@ -568,14 +682,13 @@ Coverage is attributed by running scenarios against a server that is collecting
 Prerequisite in `pikku.config.json`:
 
 ```bash
-pikku enable scenarios            # sets scaffold.scenarios = true (session required)
-pikku enable scenarios --noAuth   # sets scaffold.scenarios = { "auth": false }
+pikku enable scenarios            # sets scaffold.scenarios = true
 ```
 
-`scaffold.scenarios` is a boolean or `{ auth?, path? }`. The legacy string forms
-(`"auth"` / `"no-auth"`) are **rejected by the config loader**, not reinterpreted —
-under a shape where a string could be a path, silently reading one as a flag
-would be worse than failing.
+`scaffold.scenarios` is a boolean or `{ path? }` — whether the surface exists
+and where it is written. A bare string is **rejected by the config loader**, not
+reinterpreted: under a shape where a string could be a path, silently reading
+one as a flag would be worse than failing.
 
 `scaffold.scenarios` generates the coverage and stub RPCs into your project (`pikkuScenarioTakeLiveCoverage`, `pikkuScenarioResetLiveCoverage`, `pikkuScenarioResetStubs`, `pikkuScenarioGetStubCalls`), so scenario runs work against any server. The coverage RPC reads `<outDir>/function/pikku-functions-meta-verbose.gen.json` off disk at request time — codegen always writes it, but it has to be deployed alongside the app or the RPC returns `null`.
 
@@ -592,9 +705,7 @@ The run resets coverage before each scenario and snapshots after, writing **`<ou
   "generatedAt": "…",
   "environment": "local",
   "scenarios": {
-    "<name>": {
-      /* FunctionCoverageReport */
-    },
+    "<name>": {/* FunctionCoverageReport */},
   },
 }
 ```

package/skills/pikku-schedule/SKILL.md

@@ -51,7 +51,12 @@ development and a single-instance deployment, wrong for anything else.
 ### Scheduling a one-off RPC
 
 ```typescript
-const taskId = await schedulerService.scheduleRPC('5m', 'sendReminder', data, session)
+const taskId = await schedulerService.scheduleRPC(
+  '5m',
+  'sendReminder',
+  data,
+  session
+)
 await schedulerService.getTask(taskId) // { rpcName, scheduledFor, status, … } | null
 await schedulerService.getAllTasks() // pending one-offs only
 await schedulerService.unschedule(taskId) // true when it was still pending

package/skills/pikku-schema-ajv/SKILL.md

@@ -52,7 +52,7 @@ called `schema` in the source, which reads backwards.
 
 - **Registration is name-keyed and never re-compiles.** A second
   `compileSchema('X', …)` with a different schema is a no-op; the first one wins
-  for the process lifetime. `@pikku/schema-cfworker` *does* recompile on a
+  for the process lifetime. `@pikku/schema-cfworker` _does_ recompile on a
   changed value, so a dev hot-reload after codegen picks up a changed schema
   there but not here — restart the process instead.
 - **AJV is a module-level singleton**, shared by every `AjvSchemaService` you
@@ -62,7 +62,7 @@ called `schema` in the source, which reads backwards.
   become `1` — the wiring layer is what coerces, not this service.
 - `ajv-formats` is registered, so `format` keywords (`email`, `uuid`, `date-time`)
   are enforced.
-- A failed validation throws `UnprocessableContentError` (a 422). A *missing*
+- A failed validation throws `UnprocessableContentError` (a 422). A _missing_
   schema throws a bare string, `Missing validator for <name>` — not an `Error`,
   so `catch (e) { e.message }` reads `undefined`. That normally means codegen
   didn't run.

package/skills/pikku-schema-cfworker/SKILL.md

@@ -63,7 +63,7 @@ surface as behaviour changes rather than compile errors:
   underlying cause swallowed — check the schema by hand when you see it.
 
 A failed validation throws `UnprocessableContentError` (422) with the validator
-errors joined; a *missing* schema throws a bare string, `Missing validator for
+errors joined; a _missing_ schema throws a bare string, `Missing validator for
 <name>`, not an `Error`.
 
 ## Usage Patterns

package/skills/pikku-security/SKILL.md

@@ -62,7 +62,7 @@ Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '#pikku'
+import { addHTTPMiddleware } from '#pikku/http'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
@@ -118,14 +118,18 @@ response.
 
 ```typescript
 // permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku'
+import { pikkuAuth, pikkuPermission } from '#pikku/function'
 
-export const isAuthenticated = pikkuAuth(async (_services, session) => !!session)
-export const isVerified = pikkuAuth(async (_services, session) => !!session?.emailVerified)
+export const isAuthenticated = pikkuAuth(
+  async (_services, session) => !!session
+)
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
+)
 
 // wirings/auth.wiring.ts
 import { authCookie } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '#pikku'
+import { addHTTPMiddleware } from '#pikku/http'
 
 addHTTPMiddleware('*', [
   authCookie({