@pikku/skills 0.12.43 → 0.12.46

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

@@ -8,8 +8,8 @@ the last phase, and nothing in it is needed before then.
 `pikku deploy` builds and ships without any hosted service:
 
 ```sh
-bunx --bun pikku deploy plan  --provider standalone --runtime bun
-bunx --bun pikku deploy apply --provider standalone --runtime bun
+bunx --bun pikku deploy plan  --provider standalone
+bunx --bun pikku deploy apply --provider standalone
 ```
 
 `standalone` comes from the installed `@pikku/deploy-standalone` adapter: it
@@ -108,6 +108,14 @@ workspace). Serve each behind its own hostname, and put the API behind `/api` on
 prefix, everything else under `/api/*` reaches the pikku server unprefixed. Get
 this wrong and sign-in fails on one app only, which is a miserable thing to debug.
 
+To serve one frontend from the pikku server's own origin instead — one binary,
+one hostname, first-party cookies — give its `frontends` entry `"serve": {}`
+(`urlPrefix` defaults to `/`, `spaFallback` to true). `pikku serve`, `pikku dev`
+and a standalone deploy then mount its built `dist`. Pikku never builds it, so
+build the frontend first. Only one entry may set `serve`.
+
+To ship an app as a desktop or Android app, read `references/native-app.md`.
+
 Before shipping, run the full gate:
 
 ```sh
@@ -129,7 +137,7 @@ out of.** The server-side pass proves the functions; it renders nothing. The
 pages are client-rendered, so a component that throws still returns HTTP 200
 with an empty shell — the same trap §6 warns about, and the release gate is
 exactly where it gets shipped past. Run the browser pass, and run it **for every
-environment in `pikkufabric.config.json`**, not just the first:
+environment in `pikku.config.json`**, not just the first:
 
 ```sh
 bunx --bun pikku scenario run local --spawn --run browser
@@ -150,11 +158,13 @@ every save — but run it.
 Everything above is open source. This is the contract that keeps
 `pikku fabric init` a one-command import later, instead of a migration.
 
-- **`pikkufabric.config.json` describes reality.** Every app has an entry with
-  the right `cwd`, `port`, `kind` and `dev.command`; exactly one is `primary`;
-  `serves` and `personas` name real personas from the personas section. Leave `projectId` as
-  `__PROJECT_ID__` — that placeholder means "unlinked", and linking the project
-  writes the real one. Do not invent a value to make it look configured.
+- **`frontends` in `pikku.config.json` describes reality.** Every app has an
+  entry with the right `cwd`, `kind` and `dev` (`command`, `port`); exactly one
+  is `primary`; `serves` and `personas` name real personas from the personas
+  section.
+- **`fabric.projectId` in `pikku.config.json` is optional.** Leave it out unless you
+  have the real id; the CLI writes it after finding the project from the git
+  remote. Do not invent a value.
 - **One `definePersonas` call**, every persona reachable through exactly one
   frontend. Fabric materialises these as its virtual users; a persona nobody
   serves imports as a person with no way in.

package/skills/pikku-changes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-changes
-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.'
+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|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, 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 checkout linked to a Fabric project (`pikku fabric config` shows one). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
 installGroups: [fabric]
 ---
 
@@ -10,7 +10,7 @@ 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.
 
-Run every command from the checkout: the project comes from `pikkufabric.config.json`.
+Run every command from the checkout: the project comes from its git remote (`pikku fabric config` shows which).
 `--json` works on all of them. Items are addressed as `2`, `#2` or their uuid.
 
 ## Which stage
@@ -33,19 +33,21 @@ something changed. `next` does the waiting and exits only when there is work.
    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`.
+   `--claimed-by`. It is woken by fabric's change events the moment an item is filed
+   or answered, and sleeps exactly until a held item becomes claimable; when the event
+   stream is unavailable it falls back to checking every `--interval` seconds.
 
 2. When it exits, read the exit code:
 
-   | 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 |
+   | 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                        |
 
-3. For each item: `show` → fix → commit → `done`, or `ask` and move on. Then start
-   `next` again, in the background.
+3. For each item: `show` → fix → commit → `done`; or `ask` and move on; or `reply`
+   saying why you are leaving it. Then start `next` again, in the background.
 
 Without `--claim` it only reports what is claimable; claim it yourself:
 
@@ -53,8 +55,10 @@ Without `--claim` it only reports what is claimable; claim it yourself:
 pikku fabric changes claim --change-ids 3,4 --title "Checkout pass" --claimed-by claude-code
 ```
 
-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
+A `claim` refused with a 409 says per item why — held for the filer, inside another
+group's lease, done — and when a held or leased item is **claimable at** (a local
+`HH:MM`; `list` and `show` print the same). An item inside someone else's live lease
+cannot be taken. 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.
 
 ## Reading an item
@@ -67,7 +71,7 @@ For held items, run `next --claim` rather than retrying. The lease is 30 minutes
 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.
+   was at _that_ commit. Find today's equivalent; never edit line 42 because it said 42.
 
 ## When to ask
 
@@ -97,6 +101,24 @@ pikku fabric changes shot --change-id 3 --label "Bigger" --kind option --image a
 
 `--kind evidence` is a picture that proves something, shown inline.
 
+## Replying without asking
+
+`ask` is for a decision you need from them: it parks the item as needing an answer.
+`done` closes it. Everything else you have to say goes in a `reply`, which leaves the
+item's status exactly where it was:
+
+- you are not doing it, and why ("the copy comes from the CMS, not the app");
+- it is blocked on something that is not a question ("needs STRIPE_KEY set on the stage");
+- you could not reproduce it — attach what you saw.
+
+```bash
+pikku fabric changes reply 3 --message "Cannot reproduce on develop @ a91c4e2 — this is what I see." \
+  --image seen.png --image-label "develop @ a91c4e2" --author-name claude-code
+```
+
+Never `ask` a question you do not need answered just to leave a note, and never
+`done --note` an item you did not do — both tell the filer the wrong thing.
+
 ## Committing
 
 One item, one commit — `done` records one sha, and that is what a human reverts. The
@@ -117,7 +139,7 @@ pikku fabric changes done --change-id 7 --note "What you did, for whoever reads
 ```
 
 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
+An item you decided not to do is not `done`: `reply` with why and leave it for a
 human to dismiss.
 
 Writes need the `changes:project:write` scope; `list`, `show` and `next` without

package/skills/pikku-concepts/references/bootstrap.md

@@ -8,10 +8,9 @@ There are two ways to start a Pikku app. Pick based on whether you need to own t
 
 ```typescript
 // src/lifecycle.ts
-import { pikkuServerLifecycle } from '@pikku/core'
-import type { SingletonServices } from '../types/application-types.js'
+import { pikkuServerLifecycle } from '#pikku/setup'
 
-export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+export const lifecycle = pikkuServerLifecycle({
   beforeStart: async ({ kysely }) => {
     await runMigrations(kysely)
   },

package/skills/pikku-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-fabric
-description: 'Build, convert and debug apps on the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `pikkufabric.config.json`, the `pikku all` + `tsc` verification loop, and reading logs, traces and metrics from a deployed stage. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, asking about Fabric deployment, database or project conventions, asking about a `pikku fabric validate` finding including app-missing-actor-quick-login, or a deployed stage is erroring, timing out or behaving differently than local ("why is prod failing", "check the logs"). DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy instead — or the failure reproduces locally, which is where to debug it.'
+description: 'Build, convert and debug apps on the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, the optional `fabric.projectId` in `pikku.config.json`, the `pikku all` + `tsc` verification loop, and reading logs, traces and metrics from a deployed stage. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, asking about Fabric deployment, database or project conventions, asking about a `pikku fabric validate` finding including app-missing-actor-quick-login, or a deployed stage is erroring, timing out or behaving differently than local ("why is prod failing", "check the logs"). DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy instead — or the failure reproduces locally, which is where to debug it.'
 installGroups: [fabric]
 ---
 
@@ -91,6 +91,31 @@ Numbers must be consecutive and gap-free, and an applied migration is frozen —
 correct a mistake with a new forward migration, never by editing or renaming one
 that has already run (the recorded hash will no longer match).
 
+**Forward-only rule.** Once a migration exists on the base branch (or any stage
+has applied it), never edit, rename or delete it — add a NEW numbered migration
+that makes the change. A stage records a migration by name and never re-runs it,
+so an edit never reaches a database that already applied it. Two guards enforce
+this:
+
+- `pikku fabric validate` reports `migration-modified-after-base-*` (error) for
+  any `db/<engine>/*.sql` that exists on the base ref (default `origin/main`, else `main`, `origin/master`, `master`,
+  compared at the branch's merge-base; override with `--migrations-base <ref>`
+  or `PIKKU_MIGRATIONS_BASE`) but was modified, deleted or renamed in the working
+  tree. New files are fine. It is skipped outside a git repo or with no base ref.
+  In CI use a full clone (`fetch-depth: 0`) so the base ref exists.
+- `pikku fabric deploy apply` runs the migration-history checks first and
+  refuses to create a deployment if any fail. It compares against the stage
+  being deployed and the production (`main`) stage's applied ledger, and against
+  the base ref — a branch stage can be reset at will, but main's history reaches
+  production. Findings: `migration-applied-file-missing-*`, `migration-drift-*`,
+  `migration-gap`, `migration-modified-after-base-*`. Unlike `validate`, a check
+  that cannot run refuses too: an unreadable ledger (`migration-drift-unchecked`)
+  or a base ref that does not resolve (`migration-base-unresolved`). There is no
+  override flag — fix the history.
+
+Fix a finding by restoring the file (`git checkout origin/main -- db/sqlite/<file>`)
+and putting the change in a new migration.
+
 Run migrations: `pikku db migrate`. It also regenerates `.pikku/db/schema.gen.ts`
 (Kysely types) and `.pikku/db/zod.gen.ts` — there is no separate types step.
 
@@ -111,8 +136,10 @@ to be a migration instead.
 
 This is **local dev data only**: enough rows that a fresh dev database isn't an
 empty app. Nothing else ever runs it. A deployed stage applies `db/<engine>/*.sql`
-and stops there — reset refuses `NODE_ENV=production` and refuses a database
-outside the runtime directory, and no deploy step reaches for the seed file.
+and stops there — the one exception is a disposable stage deployed with
+`pikku fabric deploy apply <branch> --reset` (see Deploy), which is never
+production. Local reset refuses `NODE_ENV=production` and refuses a database
+outside the runtime directory.
 
 So the test is not "is this row realistic?", it is **"would the app be broken
 without it in production?"** If yes, it is configuration and belongs in a
@@ -186,47 +213,70 @@ packages/functions/
 apps/app/              # Frontend(s)
 db/sqlite/             # Plain .sql migrations, numbered, gap-free (project root)
 db/sqlite-dev-seed.sql # Dev-only test data, applied by `pikku db reset`
-pikku.config.json      # Pikku + deploy config (project root)
-pikkufabric.config.json # Fabric project link + frontends (project root)
+pikku.config.json      # Pikku + deploy config, and the frontends (project root)
 ```
 
-## `pikkufabric.config.json`
+## How a checkout is linked to its Fabric project
+
+`fabric.projectId` in `pikku.config.json` names the project. It is optional. Order
+tried:
+
+1. `FABRIC_PROJECT_ID` env var — CI and scripts.
+2. `fabric.projectId` in `pikku.config.json`.
+3. The git remote, matched against Fabric's projects. The id found is written
+   into `pikku.config.json` so the lookup happens once. It is never committed
+   for you; commit it or not. A deploy ignores a `pikku.config.json` whose only
+   change is `fabric.projectId`. If two projects share one repo the CLI refuses; pick
+   one with `FABRIC_PROJECT_ID=<projectId>`.
+
+`pikku fabric config` prints which project, api url and login the current
+checkout resolves to, and where each came from, and the project's settings.
+The settings Fabric needs that `pikku.config.json` does not describe are stored
+on the project, not in a file, and set with `key=value` arguments:
 
-Links the repo to a Fabric project and declares its frontends:
+```bash
+pikku fabric config showcase.name="Watering Log" showcase.tags=voice,realtime
+pikku fabric config guide.docs=docs/guide guide.theme.primaryColor=teal
+pikku fabric config scenarios.env.STRIPE_MODE=test   # the scenario run only
+pikku fabric config showcase.tint=                   # an empty value clears it
+```
+
+The keys are `showcase.name` (≤60), `showcase.description` (≤160),
+`showcase.tags` (comma-separated, ≤6, from Fabric's fixed list),
+`showcase.tint` (`#rrggbb`), `guide.docs`, `guide.theme.primaryColor`,
+`guide.theme.fontFamily`, `guide.theme.headingFontFamily` and
+`scenarios.env.<NAME>`. Every assignment is checked before any is applied, so a
+refused one changes nothing. Whether the project appears on the public
+showcase is Fabric's decision, not a setting.
+
+`pikku fabric link` creates
+`origin` (with `--gitea`) if there is none, imports the project, writes
+`projectId`, and queues the first deploy; it commits and pushes nothing. A
+custom production domain is set with `pikku fabric domains add`. Production
+always maps to `main`; without a domain it lives on the platform
+`*.pikkufabric.app` hostnames.
+
+The apps are the `frontends` in `pikku.config.json`,
+the same list `pikku serve`, `pikku app` and native builds read, and
+`pikku fabric validate` and `smoke` read them from there:
 
 ```json
-{
-  "projectId": "my-project-id",
-  "production": {
-    "domain": "example.com"
-  },
-  "frontends": {
-    "app": {
-      "cwd": "apps/app",
-      "primary": true,
-      "deploy": true,
-      "kind": "ssr",
-      "dev": {
-        "command": ["yarn", "dev"],
-        "port": 7105,
-        "healthPath": "/"
-      }
+"frontends": {
+  "app": {
+    "cwd": "apps/app",
+    "primary": true,
+    "deploy": true,
+    "kind": "ssr",
+    "dev": {
+      "command": ["yarn", "dev"],
+      "port": 7105,
+      "healthPath": "/"
     }
   }
 }
 ```
 
-- `projectId`: written by `pikku fabric init` / `link`. Templates ship the
-  `__PROJECT_ID__` placeholder — that is _not_ a link, and the CLI treats it as
-  unlinked.
-- `production.domain`: optional custom domain. Production always maps to `main`;
-  without a domain it lives on the platform `*.pikkufabric.app` hostnames.
-- `frontends`: each entry declares a frontend app with its dev command and port
-
-Several CLI messages call this file `fabric.config.json` — `fabric init --force`,
-`fabric link --apiUrl`, and the `domains` commands' "No fabric.config.json found".
-The file the CLI actually reads and writes is `pikkufabric.config.json`; don't
-create the shorter name to satisfy an error message.
+Each `frontends` entry declares a frontend app with its dev command and port.
 
 ## RPC is the default transport
 
@@ -352,6 +402,24 @@ pikku fabric deploy apply my-branch -y  # a named one
 that drop or rewrite data — that stays `--allow-destructive`, typed out on
 purpose.
 
+### Rebuilding a disposable stage: `--reset`
+
+A non-production stage whose migration history or schema has drifted (an app's
+`develop` branch) can be wiped and rebuilt in one deploy:
+
+```bash
+pikku fabric deploy apply develop --reset      # asks first, naming app + stage
+pikku fabric deploy apply develop --reset -y   # prints the warning, skips the prompt
+```
+
+It is the deployed counterpart of `pikku db reset`: **all data on that stage is
+deleted**, every migration is re-applied and `db/<engine>-dev-seed.sql` is
+loaded. It is refused for `--production`, for `main`, and with `--deployment-id`
+(it only applies to a deploy it creates). It needs a fabric server that reports
+the reset back on the deployment; against one that does not, the command fails
+naming the deployment it created without a reset, and wipes nothing. `-y` does
+not imply `--allow-destructive`.
+
 Inferring the branch is safe because the git safety check refuses any branch
 without an upstream or out of sync with it, so it cannot ship an unpushed
 commit; the branch it picked is printed before the build starts. A detached
@@ -430,8 +498,8 @@ repo, and if it is installed with "selected repositories" this one must be in
 the selection. There is no CLI flag that works around a missing installation:
 `init` returns "Connect the GitHub account '<owner>'". Send the user to install
 it, or create the project in the console instead (which provisions a Fabric-hosted
-git repo you push to) and write the returned `projectId` into
-`pikkufabric.config.json` yourself.
+git repo you push to) and clone it — the remote links the checkout, or put
+the id in `fabric.projectId` in `pikku.config.json`.
 
 Deploy refuses to run unless the target branch equals its upstream — the guard
 compares `main` against `main@{upstream}`. So the remote you pushed to must be
@@ -477,17 +545,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 —
@@ -521,7 +588,7 @@ Fix every `error` and `warn` in the output before continuing. Then:
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
 4. **Replace `process.env` calls**: plain config becomes `defineVariable` + `variables.get()`, anything sensitive becomes `defineSecret` + `secrets.getSecret()`.
 5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles` — plus `metaLocale` if the team does not work in English, which is the language every `description`, `title` and step `template` is then authored in.
-6. **Add `pikkufabric.config.json`** at project root with `projectId`, `production.domain`, and `frontends` (production is always `main`, so there is no `production.branch`).
+6. **Declare the apps** as `frontends` in `pikku.config.json`. There is no fabric config file; `projectId` is optional; without it the CLI finds the project from the git remote.
 7. **Run `pikku all`** — verify codegen succeeds and there are no type errors.
 8. **Run `pikku fabric validate`** once more to confirm no structural issues remain.
 

package/skills/pikku-kysely/SKILL.md

@@ -374,6 +374,7 @@ a log line or an audit row. See `pikku-services` for the reveal rules.
 import {
   PikkuKysely,
   PgKyselyChannelStore,
+  PgKyselyLeaseService,
   PgKyselyWorkflowService,
 } from '@pikku/kysely-postgres'
 
@@ -385,10 +386,22 @@ const createSingletonServices = pikkuServices(async (config) => {
   const channelStore = new PgKyselyChannelStore(db.kysely)
   await channelStore.init()
 
-  const workflowService = new PgKyselyWorkflowService(db.kysely)
+  const leaseService = new PgKyselyLeaseService(db.kysely)
+  await leaseService.init()
+
+  const workflowService = new PgKyselyWorkflowService(db.kysely, {
+    leaseService,
+  })
   await workflowService.init()
 
-  return { config, logger, database: db, channelStore, workflowService }
+  return {
+    config,
+    logger,
+    database: db,
+    channelStore,
+    leaseService,
+    workflowService,
+  }
 })
 ```
 
@@ -409,8 +422,20 @@ await channelStore.init()
 ### MySQL Setup
 
 ```typescript
-import { MySQLKyselyWorkflowService } from '@pikku/kysely-mysql'
+import {
+  MySQLKyselyLeaseService,
+  MySQLKyselyWorkflowService,
+} from '@pikku/kysely-mysql'
+
+const leaseService = new MySQLKyselyLeaseService(kyselyInstance)
+await leaseService.init()
 
-const workflowService = new MySQLKyselyWorkflowService(kyselyInstance)
+const workflowService = new MySQLKyselyWorkflowService(kyselyInstance, {
+  leaseService,
+})
 await workflowService.init()
 ```
+
+Every persistent workflow service takes a required `leaseService` and locks runs
+and steps on it. Pass the same instance you register as the app's
+`leaseService`.

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-service-backends/SKILL.md

@@ -46,6 +46,7 @@ behind the interface.
 | `PikkuWorkflowService`, `WorkflowRunService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
 | `SessionStore`, `AgentRunService`, `DeploymentService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
 | `AgentStorageService`, `AgentRunStateService` | MongoDB **only** | `@pikku/mongodb` |
+| `LeaseService` | `RedisLeaseService` | `@pikku/redis` |
 
 SQL is the third option for every store interface in that table —
 `KyselyChannelStore`, `KyselyWorkflowService`, `KyselySecretService` and friends