@pikku/skills 0.12.43 → 0.12.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.43",
+  "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-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`.