@pikku/skills 0.12.44 → 0.12.47

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
@@ -520,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-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

package/skills/pikku-service-backends/references/mongodb.md

@@ -73,6 +73,7 @@ import {
   MongoDBChannelStore,
   MongoDBWorkflowService,
 } from '@pikku/mongodb'
+import { RedisLeaseService } from '@pikku/redis'
 
 const createSingletonServices = pikkuServices(async (config) => {
   const logger = new PinoLogger()
@@ -82,9 +83,23 @@ const createSingletonServices = pikkuServices(async (config) => {
   const channelStore = new MongoDBChannelStore(mongo.db)
   await channelStore.init()
 
-  const workflowService = new MongoDBWorkflowService(mongo.db)
+  const leaseService = new RedisLeaseService(config.redisUrl)
+  const workflowService = new MongoDBWorkflowService(mongo.db, {
+    leaseService,
+  })
   await workflowService.init()
 
-  return { config, logger, database: mongo, channelStore, workflowService }
+  return {
+    config,
+    logger,
+    database: mongo,
+    channelStore,
+    leaseService,
+    workflowService,
+  }
 })
 ```
+
+`MongoDBWorkflowService` requires a `leaseService` to lock runs and steps, and
+`@pikku/mongodb` ships none — pair it with Redis, a Kysely lease service, or
+`InMemoryLeaseService` for a single process.

package/skills/pikku-service-backends/references/redis.md

@@ -9,16 +9,17 @@ Redis-backed implementations of Pikku's core service interfaces, using
 connection — an ioredis `Redis` instance, `RedisOptions`, or a connection
 string — in its constructor. None of them need an `init()` call.
 
-| Service | Interface | Purpose |
-| --- | --- | --- |
-| `RedisChannelStore` | `ChannelStore` | WebSocket channel state persistence |
-| `RedisEventHubStore` | `EventHubStore` | Event hub state persistence |
-| `RedisWorkflowService` | `PikkuWorkflowService` | Workflow definition storage |
-| `RedisWorkflowRunService` | `WorkflowRunService` | Workflow execution tracking |
-| `RedisDeploymentService` | `DeploymentService` | Deployment state management |
-| `RedisAgentRunService` | `AgentRunService` | Agent execution tracking |
-| `RedisSecretService` | `SecretService` | Encrypted secret storage (envelope encryption) |
-| `RedisSessionStore` | `SessionStore` | Persisted user sessions |
+| Service                   | Interface              | Purpose                                        |
+| ------------------------- | ---------------------- | ---------------------------------------------- |
+| `RedisChannelStore`       | `ChannelStore`         | WebSocket channel state persistence            |
+| `RedisEventHubStore`      | `EventHubStore`        | Event hub state persistence                    |
+| `RedisWorkflowService`    | `PikkuWorkflowService` | Workflow definition storage                    |
+| `RedisWorkflowRunService` | `WorkflowRunService`   | Workflow execution tracking                    |
+| `RedisDeploymentService`  | `DeploymentService`    | Deployment state management                    |
+| `RedisAgentRunService`    | `AgentRunService`      | Agent execution tracking                       |
+| `RedisSecretService`      | `SecretService`        | Encrypted secret storage (envelope encryption) |
+| `RedisSessionStore`       | `SessionStore`         | Persisted user sessions                        |
+| `RedisLeaseService`       | `LeaseService`         | Named leases with fencing tokens               |
 
 There is no Redis implementation of `AgentStorageService` — AI conversation
 storage is MongoDB-only.
@@ -51,11 +52,38 @@ await secrets.rotateKEK(): Promise<number>
 await secrets.close(): Promise<void>
 ```
 
+## `RedisLeaseService`
+
+Each lease is a hash Redis expires itself, and every check-and-set is one Lua
+script that reads the time with `TIME`, so a lease is judged — and its
+`expiresAt` reported — on Redis's clock, never the worker's. A fast worker
+clock can neither take a live lease nor stretch its own.
+
+The token comes from a counter stored beside the lease that release never
+deletes, so the next holder always gets a higher token. That counter is one
+small key per lease name, kept forever. On a replicated Redis with async
+failover a promoted replica can miss the latest `INCR`, so a token is only as
+durable as the write it rode on.
+
+```typescript
+import { RedisLeaseService } from '@pikku/redis'
+import { holdLease } from '@pikku/core/services'
+
+const leaseService = new RedisLeaseService(config.redisUrl, {
+  keyPrefix: 'pikku', // lease keys are `<prefix>:lease:{<key>}`
+})
+
+await holdLease(leaseService, 'nightly-report', async (lease, signal) => {
+  // ...
+})
+```
+
 ## Full setup
 
 ```typescript
 import {
   RedisChannelStore,
+  RedisLeaseService,
   RedisWorkflowService,
   RedisSecretService,
 } from '@pikku/redis'
@@ -64,12 +92,22 @@ const createSingletonServices = pikkuServices(async (config) => {
   const logger = new PinoLogger()
 
   const channelStore = new RedisChannelStore(config.redisUrl)
-  const workflowService = new RedisWorkflowService(config.redisUrl)
+  const leaseService = new RedisLeaseService(config.redisUrl)
+  const workflowService = new RedisWorkflowService(config.redisUrl, {
+    leaseService,
+  })
 
   const secrets = new RedisSecretService(config.redisUrl, {
     key: config.kekPassphrase,
   })
 
-  return { config, logger, channelStore, workflowService, secrets }
+  return {
+    config,
+    logger,
+    channelStore,
+    leaseService,
+    workflowService,
+    secrets,
+  }
 })
 ```

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

@@ -113,8 +113,8 @@ subscribe to its events as `<source>:<event>`:
   logged and dropped; so is one no `wireTrigger` listens for. Both still get a
   `200`, so the provider does not retry forever.
 - `receive(services, { body, headers, method, url, query })` gets the **raw
-  bytes** — verify the signature over those — and returns `{ events: [{ name,
-id?, data }] }`, or `{ respond: { status, body } }` for a handshake. Throwing
+  bytes** and only parses them: it returns `{ events: [{ name, id?, data }] }`,
+  or `{ respond: { status, body } }` for a handshake. Throwing
   rejects the request with the error's status (`UnauthorizedError` → 401).
   Omitted, the JSON body becomes one event dispatched to a trigger named just
   `<source>`.
@@ -129,12 +129,31 @@ 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`. 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`.
+- Signature checks belong in `verify`, never in `receive`. pikku runs it on
+  every request against the secret in the credential
+  `<name>WebhookSecret` (camelCased: `microsoft-outlook` →
+  `microsoftOutlookWebhookSecret`; `credential` overrides it). Declaring
+  `verify` declares that credential as a singleton string, so there is no
+  `defineCredential` and no service holding the secret; `credentialDescription`
+  tells whoever sets it where to find it. Pick the declared form that matches
+  the provider:
+  - `{ hmac: { header, prefix?, algorithm, encoding, secretEncoding? } }`:
+    a signature over the raw body in one header (GitHub, Shopify, Linear).
+  - `{ token: { header, prefix? } }`: the provider echoes the shared secret
+    (GitLab, Telegram).
+  - `{ publicKey: { header, algorithm?, dsaEncoding? } }`: signed with the
+    provider's private key; the stored secret is its PEM public key (Wise).
+  - Anything else (a timestamp in the signed payload, a signature in the body
+    or query, a URL in the signed string) is a function
+    `(request, secret, services) => boolean`, built from `hmacDigest`,
+    `verifyHmacSignature`, `verifyPublicKeySignature` and
+    `timingSafeStringEqual` in `@pikku/core/hmac`.
+
+  A request with a body that fails is refused with a 401. A bodiless request
+  that fails (a HEAD probe, a validation token in the query) still reaches
+  `receive` so it can answer the handshake, but any events it returns are
+  refused. A handshake that hands over the secret (Asana) stores it with
+  `credentialService.set` under the same credential name.
 
 `check`, `setup` and `teardown` register the route with the provider. Each gets
 `{ url, label, events, previous? }`, where `events` are only the ones some

package/skills/pikku-workflow/SKILL.md

@@ -237,38 +237,52 @@ with `outcome: 'success' | 'denied'`, the decider under `userIdentity`, and the
 run, reason and refusal in `metadata`. Wire an `audit` service to keep it; a
 project without one records nothing and is otherwise unaffected.
 
-### Error handling: `onError`, never try/catch
+### Failure: `compensate`, never try/catch
 
 **Do not wrap steps in try/catch.** The DSL extractor serialises the body into a
 step graph, and a `catch` block is control flow it cannot represent — so the
-graph would no longer describe what actually runs, which is the whole point of
-the DSL mode. This is a settled design decision, not a temporary limitation.
+graph would no longer describe what actually runs. This is a settled design
+decision, not a temporary limitation.
 
-Use the `onError` step option instead: it names an RPC to invoke when the step
-has failed _after_ exhausting its retries.
+Declare how a function is undone **on the function itself**. When a later step
+fails (after its retries), the engine runs the `compensate` of every earlier
+step that completed, newest first, then the failed step's own:
 
 ```typescript
-await workflow.do(
-  'Charge',
-  'chargePayment',
-  { orderId },
-  {
-    retries: 3,
-    retryDelay: '1s',
-    onError: 'refundReservation', // compensation RPC
-  }
-)
+export const chargePayment = pikkuFunc({
+  func: async ({ payments }, { orderId }) => payments.charge(orderId),
+  compensate: async ({ payments }, { orderId }, { workflow }) => {
+    const { ok, output } = workflow!.compensatingFor!
+    // ok: false → the charge itself failed; output is null, `error` is set
+    if (ok) await payments.refund(output.chargeId)
+  },
+})
 ```
 
-The handler receives `{ error: { message } }`, and the original error is still
-thrown afterwards — so the workflow still fails. `onError` is **compensation, not
-recovery**: it exists to undo work, not to swallow the failure and carry on. If
-you genuinely need to branch on a failure, have the step return a result object
-(`{ success: false, reason }`) and branch on that, the way the `processOrder`
-example branches on `payment.success`.
-
-Full step options: `description`, `retries`, `retryDelay`, `onError` (plus
-`actor`, which is scenario-only — see `pikku-scenario`).
+- `compensate` gets the **same input** as the forward call. `wire.workflow.compensatingFor`
+  is `{ ok: true, output, stepName }` or `{ ok: false, output: null, error, stepName }`.
+- It is never callable over HTTP, MCP or RPC — only the engine runs it, as the
+  durable step `<step>:compensate` with the same retry defaults as forward steps.
+- Opt a call site out with `{ compensate: false }` (graph nodes likewise).
+- A run ends `compensated` (everything undone), `compensation_failed` (a
+  compensation ran out of retries; `stuckSteps` names them — steps that ran
+  before a stuck one are not undone, parallel siblings still are) or `failed`
+  (nothing needed undoing).
+- `await workflow.milestone('paid')` bounds the unwind: steps finished before the
+  last milestone are kept, and the run ends `compensated` with `restedAt: 'paid'`.
+- A failing child workflow unwinds itself first; a stuck child makes the parent
+  `compensation_failed`. Cancelling a run (`cancelRun`) unwinds it the same way,
+  children first.
+
+To **recover** instead of undo, use a graph node's `recover`:
+`recover: 'nodeId' | ['a','b'] | 'ignore'`. The failure is routed to those nodes
+(`'ignore'` continues to `next` with a null output) and the failing step is not
+compensated. The error arrives as `wire.graph.recoveringFrom`
+(`{ nodeId, stepName, error }`). The DSL has no recovery — branch on a result
+object (`{ success: false, reason }`) instead.
+
+Full step options: `description`, `retries`, `retryDelay`, `compensate: false`
+(plus `actor`, which is scenario-only — see `pikku-scenario`).
 
 ### Parallel fan-out