@pikku/skills 0.12.42 → 0.12.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.42",
+  "version": "0.12.44",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-auth/references/better-auth.md

@@ -500,10 +500,9 @@ value for the address being signed in as and compares, so a credential minted
 for one persona is refused for every other, and the root itself is never a valid
 credential. A root under 32 characters refuses the endpoint outright rather than
 deriving weak credentials from it (the server log names the problem; the client
-is not told which). Callers rarely derive by hand — `pikku dev` mints one per
-persona into `VITE_DEV_ACTOR_SECRETS` for the browser switcher, `pikku persona
-secret <id>` mints them for a run, and the two `PersonaSignIn` implementations
-derive on the fly.
+is not told which). Callers rarely derive by hand — `pikku persona secret <id>`
+mints them for a run, and the two `PersonaSignIn` implementations derive on the
+fly. The browser switcher holds none: it signs in through `/sign-in/persona`.
 
 **Which command is running decides whether it works, not whether a secret is
 set.** `pikku dev` sets `PIKKU_DEV_ACTOR_SIGN_IN` and mints an ephemeral
@@ -559,9 +558,11 @@ actor`. So the secret cannot take over a **real user's** account — the blast
   paragraph above. The comparison is constant-time and length-hiding, so a wrong
   credential leaks neither the length nor a prefix of the right one.
 
-This is the endpoint `pikku scenario` signs its actors in through, and the one
-the frontend dev switcher posts to — see `pikku-scenario` for declaring the
-actors and `pikku-react` for `useDevActors()`.
+This is the endpoint `pikku scenario` signs its actors in through. The frontend
+switcher does not use it: it lists from `/sign-in/personas` and posts a persona
+id to `/sign-in/persona`, both served by
+`pikkuActor({ personaSignIn: { personas, featureFlags } })` with no credential — see
+`pikku-scenario` for the setup and `pikku-react` for `useDevActors()`.
 
 ### Provisioning personas
 

package/skills/pikku-build/references/app.md

@@ -573,17 +573,13 @@ frontend running against a dead API looks exactly like an app bug, so if every
 request fails, check that both halves came up.
 
 **Start the stack through `bun run dev`, not by launching `vite` or `pikku dev`
-yourself.** The dev script reads the personas, derives one credential per
-persona from `SCENARIO_ACTOR_SECRET`, and hands both to the frontend as
-`VITE_DEV_ACTORS` / `VITE_DEV_ACTOR_SECRETS`. Vite reads those once, at boot. A
-frontend started any other way — or restarted by hand later — has an empty
-actor list, and the switcher silently disappears from every page. If you do
-start the frontend on its own (say :3000 is taken by another project), you owe
-it three things: the two `VITE_DEV_*` values the dev script would have computed,
-and `VITE_API_PROXY` pointing at your API — the dev proxy defaults to
-`http://localhost:3000`, so beside another project's server your sign-ins go to
-_its_ API and come back `401 Invalid actor secret`, which reads like a bad
-credential rather than the wrong server.
+yourself.** The "Sign in as …" switcher asks the API for its personas at
+runtime, so the frontend needs nothing baked in — but it does need to reach
+_your_ API. If you start the frontend on its own (say :3000 is taken by another
+project), point `VITE_API_PROXY` at your API: the dev proxy defaults to
+`http://localhost:3000`, so beside another project's server the switcher lists
+_its_ personas, or none, which reads like a missing switcher rather than the
+wrong server.
 
 The `--bun` in `bunx --bun pikku …` is load-bearing — keep it. Without it the
 CLI's `#!/usr/bin/env node` shebang hands the process to whatever Node is on
@@ -709,6 +705,21 @@ new RPC and does not re-run `afterStart`, so a fresh function answers 404 and
 anything provisioned at boot is missing — failures that read like a wiring bug
 and are nothing but a stale process.
 
+**Run the whole suite, not the milestone's own scenarios.** The milestone's
+scenarios are the ones you wrote to pass; the regression lives in someone
+else's. Tightening what "archived" means is a one-function change that reads as
+local and quietly breaks the milestone-01 scenario nobody re-ran.
+
+**Restart the server after adding a function, and never edit one while a run is
+in flight.** Hot reload does not register a new RPC and does not re-run
+`afterStart`, so a fresh function answers 404 and anything provisioned at boot
+is missing — failures that read like a wiring bug and are nothing but a stale
+process. The same reload is what makes a run unrepeatable if you edit during
+it: a browser pass is long enough to feel like free time, and a schema touched
+at minute four hot-reloads into a half-generated contract, so every scenario
+after that point fails on something you have already fixed. Wait for the run or
+kill it — a run you edited under is not a result.
+
 ### 7a. Coverage — which functions have actually been run
 
 Green scenarios tell you the journeys you wrote still work. They say nothing

package/skills/pikku-changes/SKILL.md

@@ -1,172 +1,124 @@
 ---
 name: pikku-changes
-description: 'Work a project''s changes queue — the todo list someone filed by walking a deployed stage. Covers `pikku fabric changes list|claim|show|ask|shot|done`, when to ask a question instead of guessing, and how to offer options as images. TRIGGER when: the user says "work the changes", "pick up the changes queue", names a change by its #number, or you are otherwise idle in a repo that has a pikkufabric.config.json. DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
+description: 'Work a Fabric project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku fabric changes next|claim|show|ask|shot|done`: waiting for work without polling, asking instead of guessing, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against <stage>", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a repo that has a pikkufabric.config.json. DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
 installGroups: [fabric]
 ---
 
 # Working a changes queue
 
-Someone walked the deployed app and circled twenty things. Each one is a row with their
-words, a picture of what they were looking at, and the elements the circle enclosed. You
-have the repo and the app running locally. Your job is to empty the queue without making
-them regret filing.
+Someone walked the deployed app and circled things. Each item is their words, a
+screenshot of what they saw, and the elements the circle enclosed. You have the repo.
+Empty the queue without making them regret filing.
 
-## The loop
-
-Every argument is a flag; nothing is positional. `--json` works on any of them. The
-project comes from the local `pikkufabric.config.json`, so `--project-id` is only needed
-when you are not in the checkout.
+Run every command from the checkout: the project comes from `pikkufabric.config.json`.
+`--json` works on all of them. Items are addressed as `2`, `#2` or their uuid.
 
-```bash
-pikku fabric changes list --pickup-only --json
-pikku fabric changes claim --change-ids <id>,<id> --title "Checkout pass" --claimed-by claude-code
-pikku fabric changes show --change-id <id>
-pikku fabric changes ask --change-id <id> --question "…" --option "…" --option "…" --author-name claude-code
-pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
-pikku fabric changes done --change-id <id> --note "What you did"
-```
+## Which stage
 
-`list --pickup-only` is the one a harness wants: it skips items still inside the grace
-window, so a batch someone is mid-way through typing is picked up together rather than item
-by item as it lands.
+The queue is per project. "Against develop" or a pasted stage URL narrows it:
+`--stage` takes a branch, the stage URL (as filed, path optional) or a stage id. With
+no stage named, work the whole project. An unknown name prints the stages there are.
 
-Deciding what belongs together is yours: `claim` with `--change-ids` and no `--group-id`
-forms the group. Claim an existing one with `--group-id`.
+## The loop
 
-Claim before working. The lease expires (30 minutes by default, `--lease-minutes` to
-change it), so an abandoned claim returns to the queue rather than parking the work
-forever — but a second harness picking up something you are halfway through is the failure
-this prevents.
+**Never poll.** No `sleep` loops, no repeated `list`, no re-running `show` to see if
+something changed. `next` does the waiting and exits only when there is work.
 
-## Reading an item
+1. Start `next` as a **background** command, and stop there until it exits:
 
-`show` gives you four things, in descending order of trustworthiness:
+   ```bash
+   pikku fabric changes next --stage develop --claim --claimed-by claude-code
+   ```
 
-1. **Their words.** The title and body are the requirement. Everything else is evidence.
-2. **The screenshot.** What they actually saw, at their width, with their data. When the
-   other addresses disagree with the picture, the picture is right.
-3. **The circled elements** — a testid, a source anchor, a CSS path. The testid greps
-   straight to a component because it is the i18n message key.
-4. **The source anchor**, printed as `src/routes/app.orders.tsx:42 as of a91c4e2`. That line
-   number is where the JSX was **at that commit**. Read it as a starting point and find
-   today's equivalent; never edit line 42 of today's file because the anchor said 42.
+   It waits out the grace window (a just-filed item is held about a minute so a batch
+   being typed arrives together), claims what is ready as one group, prints it, and
+   exits. It also wakes when someone answers a question you asked under that
+   `--claimed-by`.
 
-Resolution is a guess and the panel says so. If the circle and the anchor point at
-different things, believe the circle.
+2. When it exits, read the exit code:
 
-## When to ask
+   | code | meaning | do |
+   | --- | --- | --- |
+   | 0 | work printed (claimed, and/or `Answered`) | work it, then step 3 |
+   | 2 | `--timeout`/`--once` found nothing | stop, or restart `next` |
+   | 3 | session refused | tell the user to run `pikku fabric login`; stop |
+   | 1 | anything else (bad `--stage`, fabric down for minutes) | report the message; stop |
 
-Ask when the item admits more than one reasonable implementation and you would be **picking
-for them**. Do not ask to confirm something the item already says.
+3. For each item: `show` → fix → commit → `done`, or `ask` and move on. Then start
+   `next` again, in the background.
 
-Ask:
-- "Make the total stand out" — bigger, bolder, coloured, or moved above the fold?
-- "This should be faster" — is it the spinner, the request, or the number of steps?
-- Anything that changes what data is stored, what an existing user sees, or what something costs.
+Without `--claim` it only reports what is claimable; claim it yourself:
 
-Do not ask:
-- "Should I use flexbox or grid?" — that is yours.
-- "Do you want me to fix the typo?" — they filed it; fix it.
-- "Can you confirm you want the button blue?" — they said blue.
+```bash
+pikku fabric changes claim --change-ids 3,4 --title "Checkout pass" --claimed-by claude-code
+```
 
-A question costs them a context switch, not typing. That is the budget you are spending.
+A `claim` refused with a 409 says per item why (held, claimed by someone else, done).
+For held items, run `next --claim` rather than retrying. The lease is 30 minutes
+(`--lease-minutes`); an abandoned claim returns to the queue by itself.
 
-## What a good question looks like
+## Reading an item
 
-One decision. Their vocabulary, not the codebase's. And the choices in `--option`, not in
-the sentence.
+`pikku fabric changes show 3` gives, most trustworthy first:
 
-> **Bad:** "How would you like me to handle the ambiguity in the checkout total component's
-> emphasis requirement?"
->
-> **Good:** `--question "Make the total stand out — which way?"`
-> `--option "Bigger" --option "Move it above the delivery line"`
+1. **Their words.** The title and body are the requirement. Everything else is evidence.
+2. **The screenshot.** What they saw, at their width, with their data. When the other
+   addresses disagree with the picture, the picture is right.
+3. **The circled elements**: a testid (greps straight to a component, it is the i18n
+   key), a source anchor, a CSS path.
+4. **The source anchor**, `src/routes/app.orders.tsx:42 as of a91c4e2`, is where the JSX
+   was at *that* commit. Find today's equivalent; never edit line 42 because it said 42.
 
-**A choice written into the prose is not a choice.** Every `--option` becomes a button in
-the panel and the console, and clicking one records the answer; a question that says
-"(a) build it, (b) leave existing bookings, (c) hold" makes them re-type in free text what
-they should have been able to click, and leaves you parsing prose to find out which one
-they meant. If you can enumerate them in the sentence, you can pass them as flags.
+## When to ask
 
-Pass them even when there are only two, and even when one is "hold until I check" — that
-last one is a real option and it is the one most often left off. The filer can always
-choose "say something else", so the list constrains nothing.
+Ask when the item admits more than one reasonable implementation and you would be
+picking for them — "make the total stand out" (bigger? bolder? moved?), anything that
+changes stored data, what an existing user sees, or what something costs. Do not ask
+what the item already says, or implementation choices that are yours.
 
-Batch per group. Three questions about one checkout flow go out together; three separate
-asks about the same screen is three interruptions for one context switch.
+One decision, in their vocabulary, with the choices as `--option` flags — each becomes
+a button. Include "hold until I check" when it is real. Batch questions per group.
 
-Then **park it**. `ask` flips the item to `needs_answer` and you move to the next item. Do
-not sit waiting — pick answers up on your next `show`, and bound your polling so an
-unanswered item does not spin forever.
+```bash
+pikku fabric changes ask --change-id 3 --question "Make the total stand out — which way?" \
+  --option "Bigger" --option "Move it above the delivery line" --author-name claude-code
+```
 
-## When to show instead of ask
+Then **park it** and move on. The answer wakes `next` (same `--claimed-by`); it prints
+under `Answered`, and `show` has the reply.
 
-If the answer is visual and you can build it, build all of them and attach images:
+If the answer is visual and you can build it, build each variant, screenshot all of
+them in one pass at one width (baseline included), and attach them — the panel turns
+`--kind option` shots into a pick-one:
 
 ```bash
-pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
-pikku fabric changes shot --change-id <id> --label "Above the line" --kind option --image b.png
+pikku fabric changes shot --change-id 3 --label "Bigger" --kind option --image a.png
 ```
 
-The panel turns a set of `option` attachments into a pick-one they open full-screen, and
-picking one writes the choice into the thread. Capture every variant in **one pass at one
-width**, including the baseline — variants shot at different sizes are not comparable, and
-comparing is the whole point.
-
-`--kind evidence` is the other use: a picture that proves something, rendered inline rather
-than as a choice.
+`--kind evidence` is a picture that proves something, shown inline.
 
 ## Committing
 
-One item, one commit. `done` records a single `head_commit`, and that sha is what a human
-reverts when they change their mind — so an item folded in with three others cannot be
-undone without taking the other three with it. Land unrelated work separately.
-
-The subject carries the short id the way a GitHub issue number does, and the uuid goes in a
-trailer so `git log --grep` has an exact handle:
+One item, one commit — `done` records one sha, and that is what a human reverts. The
+subject carries the short id; the uuid goes in a trailer:
 
 ```
-feat(login): #4 make the sign-in heading brown
+fix(booking): #7 stop the date picker closing on the first click
 
 Change-Id: 0f3c8a12-9b44-4d2e-8f01-27c6a1d9e5b3
 ```
 
-Both ids come from `show`. The type and scope are the usual conventional-commit ones —
-`feat`, `fix`, `style`, `refactor` — with the scope naming the screen or area they were
-looking at, not the file you edited.
-
-More:
-
-```
-fix(booking): #7 stop the date picker closing on the first click
-style(nav): #12 tighten the spacing around the logo
-```
-
-Reverting one later is then:
-
-```bash
-git revert $(git log --grep="Change-Id: <uuid>" --format=%H -1)
-```
+Scope names the screen they were looking at, not the file you edited.
 
 ## Finishing
 
-`done` records the branch and commit that closed it, which is what strikes the item through
-on the page it was filed on and tells them where the fix landed. Both default to the
-checkout you are standing in, so run it from there and let it read git:
-
 ```bash
-pikku fabric changes done --change-id <id> \
-  --note "What you did, for whoever reads the thread later"
+pikku fabric changes done --change-id 7 --note "What you did, for whoever reads the thread"
 ```
 
-`--branch` and `--head-commit` override them, for the case where the fix landed somewhere
-other than where you are. Never type a sha by hand — one that does not exist points the
-filer at nothing.
-
-An item you decided not to do is not `done`. Say why in the thread and leave it for a human
-to dismiss.
-
-## Scope
+Branch and commit default to the checkout you are in — run it there, never type a sha.
+An item you decided not to do is not `done`: say why in the thread and leave it for a
+human to dismiss.
 
-Writes need the `changes:project:write` scope on your bearer. `list` and `show` are reads.
-The project comes from the local `pikkufabric.config.json`, so run these from the checkout.
+Writes need the `changes:project:write` scope; `list`, `show` and `next` without
+`--claim` are reads.

package/skills/pikku-fabric/SKILL.md

@@ -477,17 +477,16 @@ reviewer has no seed password, so without the control they are locked out of the
 app they were asked to look at.
 
 Satisfy it with `<DevActorSwitcher />` from `@pikku/mantine/dev`, or with your
-own UI built on `useDevActors()` from `@pikku/react` — validate accepts either
-call site as evidence, so custom rendering passes. See **pikku-react** for the
-props and **pikku-scenario** for where the actor list comes from.
+own UI built on `useDevActors()` or `signInAsPersona()` from `@pikku/react` —
+validate accepts any of those call sites as evidence, so custom rendering
+passes. Either way the server needs `personaSignIn` on `pikkuActor`; see
+**pikku-scenario** for it and **pikku-react** for the props.
 
 The validator also accepts the shapes that predate the package — a hand-rolled
 `signInAsActor()` or a literal `POST /auth/sign-in/actor` — so an older app does
 not fail the build. **Treat that as a grace period, not the target: migrate those
-to `<DevActorSwitcher />`.** The hand-copied version is exactly the duplication
-the package exists to remove, and the copies drift — the ones that prompted this
-had already diverged on the `import.meta.env.DEV` gate that keeps the shared
-secret out of production bundles.
+to `<DevActorSwitcher />`.** They put a per-persona credential in the frontend
+bundle, which the persona endpoint exists to avoid.
 
 Do **not** satisfy it with Better Auth's `/dev/quick-login`. That is a different
 endpoint with a different purpose — one fixed admin, not the declared personas —

package/skills/pikku-react/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   direct usePikkuRPC / usePikkuFetch calls, realtime subscriptions, agent and workflow hooks, and
   the dev actor switcher. TRIGGER when: writing a React component that fetches or mutates backend
   data, wiring PikkuProvider, paginating, running or tracking a workflow from the client, or
-  asking about useDevActors / VITE_DEV_ACTORS / quick login. DO NOT TRIGGER when: working on the
+  asking about useDevActors / DevActorSwitcher / quick login. DO NOT TRIGGER when: working on the
   backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), or writing
   user-facing copy (use pikku-i18n).
 installGroups: [client]

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

@@ -251,14 +251,9 @@ 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,
+const { actors, signInAs, pendingId, isPending, error } = useDevActors({
   apiUrl: apiUrl(),
+  app: appSlug,
   onSignedIn: () => navigate({ to: '/' }),
 })
 ```
@@ -267,21 +262,19 @@ const { actors, signInAs, pendingEmail, isPending, error } = useDevActors({
   `<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.
+- **No credential reaches the bundle.** It lists from `/auth/sign-in/personas`
+  and `signInAs(id)` posts only the persona id to `/auth/sign-in/persona`. The
+  server decides who is offered and who may sign in, and offers nobody in
+  production — see **pikku-scenario** for `personaSignIn`.
+- **It takes `onSignedIn` rather than a router**, since every app lands
+  somewhere different.
+- `listDevActors()` and `signInAsPersona()` are exported too, for a non-React
+  caller. The endpoint only
+  signs in rows flagged `actor: true`, so it can never impersonate a real user —
+  see **pikku-auth**.
+
+Do not hand-write the list-and-sign-in pair per app; that copy-paste is exactly
+what this replaced.
 
 ### Linking from a Mantine element: `renderRoot`, not `component`
 

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

@@ -83,13 +83,17 @@ Declared actors are not only for automated runs. `signInPath` is Better Auth's
 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 dev server bakes both halves into the frontend from the declared
-personas — the sandbox's, or the template's `bun run dev`, never `pikku dev`: `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-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.
+The switcher holds no credential. It lists personas from
+`/auth/sign-in/personas` and signs in by posting only a persona id to
+`/auth/sign-in/persona`; the server resolves the address. One server piece
+serves both, in the auth config:
+
+```ts snippet:personaSignIn
+```
+
+It is always open under `pikku dev`. A deployed stage needs actor
+sign-in opted in **and** its `devSwitcher` feature flag on; production never
+has the opt-in, so it lists nobody and refuses every persona sign-in.
 
 Do not hand-roll the switcher: `useDevActors()` (`pikku-react`, a separate install) is the logic and
 `<DevActorSwitcher />` from `@pikku/mantine/dev` is a ready rendering of it.
@@ -98,52 +102,16 @@ one — without it a reviewer is locked out of their own sandbox.
 When the switcher is missing, it is one of three things, and none of them
 errors:
 
-- **The frontend was not started by the dev script.** The two `VITE_DEV_*` vars
-  are computed by `bun run dev` and read by vite once, at boot. A bare `vite dev`
-  — including one restarted by hand — has an empty list and renders nothing.
-- **`SCENARIO_ACTOR_SECRET` is not in `.env`.** No root secret, no per-persona
-  credentials, and the switcher filters out every actor it cannot sign in.
+- **The list is empty.** On a deployed stage that is the gate
+  doing its job — check the opt-in and the `devSwitcher` flag. Locally, check
+  the personas declare an `email` (via `scenarios.emailDomain`) and are not
+  `runnable: false`.
+- **`personaSignIn` is missing, or the frontend calls another API.** A dev
+  proxy (`VITE_API_PROXY`, default `http://localhost:3000`) that points at
+  another project's API lists that project's personas, or none.
 - **It is not mounted on the page you are looking at.** The template mounts it
   on the login screen. A public homepage that replaces the `/` → `/app`
   redirect needs its own `<DevActorSwitcher />` in the public layout.
 
-When the switcher is there but signing in fails with `401 Invalid actor
-secret`, check which server answered before checking the secret: a frontend
-whose dev proxy (`VITE_API_PROXY`, default `http://localhost:3000`) points at
-another project's API sends the sign-in there.
-
-**A runner of your own that starts vite has to bake them itself**, from the
-generated persona meta (`<outDir>/workflow/personas.gen.json`, which already
-carries the derived `email`):
-
-```js
-const personas = Object.values(JSON.parse(readFileSync(personasPath, 'utf8')))
-
-env.VITE_DEV_ACTORS = JSON.stringify(
-  personas.map(({ id, email, name, jobTitle }) => ({
-    key: id,
-    email,
-    name,
-    jobTitle: jobTitle ?? '',
-  }))
-)
-env.VITE_DEV_ACTOR_SECRETS = JSON.stringify(
-  Object.fromEntries(
-    await Promise.all(
-      personas.map(async ({ email }) => [
-        email,
-        await deriveActorSecret(env.SCENARIO_ACTOR_SECRET, email),
-      ])
-    )
-  )
-)
-```
-
-**Set `SCENARIO_ACTOR_SECRET` yourself**, at least 32 characters, in the
-environment both processes read. Left unset, `pikku dev` mints an ephemeral root
-for its own run that a separately spawned vite cannot see, so the two derive
-from different roots: the switcher renders every persona and each click is
-refused, which reads as a broken login rather than missing configuration. On a
-brand-new project the persona file does not exist until the first `pikku dev`
-codegen, after vite has baked an empty list — watch it and restart the frontend
-when it changes.
+When the switcher lists personas but a click 404s, that persona has no `email`
+or is `runnable: false`.

package/skills/pikku-wiring/references/trigger.md

@@ -105,6 +105,9 @@ subscribe to its events as `<source>:<event>`:
 ```
 
 - The route is `POST /webhooks/<name>` unless `method`/`route` say otherwise.
+  `method` may be a list, e.g. `['get', 'post']` for a provider that verifies
+  the URL with a GET and delivers events with a POST, or `['head', 'post']`
+  for one that checks the URL with a HEAD.
   It needs no session.
 - `events` maps each event name to a schema. An event that fails its schema is
   logged and dropped; so is one no `wireTrigger` listens for. Both still get a
@@ -126,9 +129,12 @@ id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
   even on queues that ignore job ids, and records each attempt and its last
   error. Its `webhookReceipt` table comes from `pikku db generate`; `pikku dev`
   and `pikku serve` use it when a Kysely database is configured.
-- `receive` sees singleton services without `secrets`: read the signing secret
-  in a service method, and declare it with `defineSecret`. Name it in `secret`
-  so deploy knows where `setup` should store it.
+- `receive` sees singleton services without `secrets`. Declare the signing
+  secret with `defineCredential({ type: 'singleton', ... })` and hold it as
+  `WebhookSigningSecret.fromCredential(provider, credentialService, name)`
+  from `@pikku/core/hmac`; `receive` calls `await signingSecret.load()` and
+  checks against what it returns. A handshake that hands over the secret
+  (Asana) stores it with `credentialService.set`.
 
 `check`, `setup` and `teardown` register the route with the provider. Each gets
 `{ url, label, events, previous? }`, where `events` are only the ones some
@@ -142,10 +148,9 @@ pikku webhooks teardown --url https://api.example.com --labelPrefix shop:prod --
 
 Each prints one JSON line per source (`ok`, `missing`, `drifted`, `created`,
 `updated`, `unchanged`, `manual`, `deleted`, `absent`, `skipped`, `failed`). `setup` only
-runs where `check` does not report `ok`, and a `setup` that returns a new signing
-secret prints it with the `secret` name to store it under. In CI pass
-`--secretsOut <file>`: secrets are written there (mode 600) as
-`{ secretName: secret }` and left out of stdout. Any step can be
+runs where `check` does not report `ok`. A `setup` that gets a signing secret
+from the provider stores it with `credentialService.set`, and `teardown`
+deletes it, so a new secret needs no deploy and never reaches stdout. Any step can be
 `ref('<addon>:<fn>')` to use an addon's implementation.
 
 ## Usage Patterns