@pikku/skills 0.12.25 → 0.12.26

package/skills/pikku-permissions/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: pikku-permissions
+description: >-
+  Use when deciding WHO may call a function — resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes, and where ownership belongs versus where it does not.
+  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, or about to write an `if` in a function body that decides whether the caller is allowed.
+  DO NOT TRIGGER when: the question is how to sign someone in or seed a persona (that is pikku-auth), or how to shape a paginated list (that is pikku-list-query).
+installGroups: [core]
+---
+
+# Pikku Permissions
+
+## The rule
+
+**Authorization goes in the `permissions` field. Never in the `func` body.**
+
+`permissions` runs before `func`, and it is DECLARED — `pikku meta` and the auditor can
+see it. An `if` in the body is the same check, invisible: nothing can tell you which
+functions are gated or how, and the next person to add a caller gets no warning.
+
+```typescript
+// RIGHT
+export const deleteBook = pikkuFunc({
+  permissions: { owner: isBookOwner },
+  func: async ({ kysely }, { bookId }) => {
+    await kysely.deleteFrom('book').where('bookId', '=', bookId).execute()
+  },
+})
+
+// WRONG — the gate is buried in the body
+export const deleteBook = pikkuFunc({
+  func: async ({ kysely }, { bookId }, { session }) => {
+    const book = await kysely.selectFrom('book')...executeTakeFirst()
+    if (book?.ownerId !== session.userId) throw new UnauthorizedError()
+    await kysely.deleteFrom('book').where('bookId', '=', bookId).execute()
+  },
+})
+```
+
+## `auth: true` IS NOT OWNERSHIP — this is the one people get wrong
+
+`auth: true` means "somebody is signed in". It does NOT mean "this row is theirs". A CRUD
+function set to `auth: true` and nothing else lets ANY signed-in user delete ANY other
+user's row by passing its id. Every function that takes a row id needs BOTH: `auth: true`
+for the session, and a `permissions` entry for the ownership.
+
+Equally: do NOT write an `isSignedIn` permission that returns `!!session`. That re-checks
+authentication, which `auth: true` already did. A permission answers *may this user do
+this* — role, ownership, tier — never *is there a session*.
+
+## Single row vs list — where ownership actually goes
+
+This is the distinction to get right, and both halves are correct code:
+
+- **A function taking a row id** (`get`, `update`, `delete`) — ownership is a
+  PERMISSION. Load the row, compare the owner to the session. It is a yes/no question
+  about one row, which is exactly what a permission is.
+- **A function returning many rows** (`list`, `search`, any stats query) — ownership is
+  a `WHERE` clause in the query, because "only their rows" is a filter, not a yes/no.
+  There is no permission to write here; scoping the query IS the enforcement.
+
+A list that fetches everything and then filters in JS is a bug, not a permission.
+
+## Writing the checkers
+
+Put them in `src/permissions/`, one file per entity, and reuse one checker across every function on that
+entity rather than writing a near-copy per function.
+
+```typescript
+// src/permissions/book.ts
+import { pikkuPermission, pikkuAuth } from '#pikku/auth'
+
+// Data-aware: gets the input, so it can load the row the caller named.
+export const isBookOwner = pikkuPermission(
+  async ({ kysely }, { bookId }, { session }) => {
+    const book = await kysely
+      .selectFrom('book')
+      .select('ownerId')
+      .where('bookId', '=', bookId)
+      .executeTakeFirst()
+    return book?.ownerId === session?.userId
+  },
+)
+
+// Session-only: no input needed. Use for role and flag gates.
+export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
+```
+
+## OR and AND
+
+```typescript
+permissions: {
+  owner: isBookOwner,            // OR — an owner may
+  admin: isAdmin,                // OR — an admin may
+  editor: [isAdmin, isBookOwner] // AND — both, inside one group
+}
+```
+
+Groups are OR'd; entries inside a group array are AND'd.
+
+## Roles
+
+If the app has roles, the role lives on the session (see pikku-auth / `mapSession`) and
+every mutating or admin-only function names it in `permissions`. Gate the FUNCTION — hiding
+an admin button in the UI is UX, never enforcement, and a member who guesses the RPC name
+gets straight through if the function itself is open.
+
+## Scopes
+
+`scopes: ['admin:invoices:void']` is an AND gate checked BEFORE permissions and before
+input validation. Declare the tree once with `defineScope`; a function naming an
+undeclared scope fails codegen rather than gating on nothing. A grant satisfies a scope if
+it is that scope, an ancestor, or a wildcard — a session holding `admin` satisfies
+`admin:invoices:void`. Most apps need roles, not scopes; reach for these only when the
+plan asked for granular grants.
+
+## The one sanctioned exception
+
+`permissionsInBody: true` — for a check that genuinely cannot be a permission because the
+identity arrives in the payload and there is no session: a webhook signature, a signed
+token, an invite code. It is purely declarative and enforces nothing; its job is to tell
+the auditor the openness is deliberate. Anything expressible as a permission must be one.
+
+## After changes
+
+`pikku all` — regenerates and typechecks the checkers. A permission whose signature is
+wrong fails here, not at runtime.

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

@@ -195,6 +195,26 @@ const pikku = createPikku(PikkuFetch, PikkuRPC, {
 })
 ```
 
+`transformDate: true` revives **fully-zoned ISO-8601 instants** — `2026-03-14T08:12:00Z`,
+`2026-03-14T08:12:00.000+01:00` — into `Date` objects. Nothing else is touched: a bare
+`2026-03-14`, a zoneless `2026-03-14T08:12:00`, and a shaped-but-impossible
+`2026-02-31T00:00:00Z` all stay the strings the server sent, because each names a reading
+rather than a moment and `new Date` would guess a different instant per machine.
+
+So the field's runtime type follows the VALUE, not the schema — one `z.string()` column can
+arrive as a `Date` from one row and a string from the next. Two consequences, both of which
+typecheck:
+
+- **A string method on a revived field throws at runtime.** `row.createdAt.split('T')[0]` —
+  there is no string to slice.
+- **A raw `Date` in JSX crashes the route.** `<span>{row.createdAt}</span>` throws
+  `Objects are not valid as a React child (found: [object Date])` and the page falls into its
+  error boundary — a white screen, with nothing catching it first.
+
+Format before rendering, with whatever date library the project already uses, and let it take
+either type. Coercing instead (`` `${d}` ``, `String(d)`) does not crash but prints
+`Mon Jun 15 2026 02:00:00 GMT+0200`, which is a different bug.
+
 There is no request-interceptor hook. For a token that changes after startup,
 call the setter on the shared instance — RPC and realtime pick it up because
 they hold the same fetch:

package/skills/pikku-realtime/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: pikku-realtime
+description: >-
+  Use when making ANY view live/realtime in a Pikku app — a board, shared list, dashboard, ticker, bidding room, live count — or when adding two-way chat/presence. Covers the DEFAULT event-hub SSE path and the two-way WebSocket channel.
+  TRIGGER when: the user wants live updates, realtime, "update without refresh", a live board/feed/ticker/room, presence, or chat; or when data that MORE THAN ONE signed-in user can change should reflect others
+  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (that is pikku-schedule/pikku-workflow).
+installGroups: [core, client]
+---
+
+# Pikku Realtime (SSE + WebSocket channels)
+
+There is NOTHING to hand-roll and NOTHING to "find". The event-hub SSE transport
+is already wired into every app, and the two patterns below ARE the realtime
+templates. Start from them and rename — never grep the project for existing
+`sse`/`eventHub` code to copy, never write a custom `EventSource`, and never
+write a bespoke `sse: true` route for a plain live feed.
+
+## Pick the transport (almost always SSE)
+
+- **Server → client live updates → SSE via the event-hub.** This is the DEFAULT
+  for making any view live: a board, list, dashboard, ticker, feed, or a "room"
+  (a bidding room, sale room, live auction). The client only RECEIVES — the
+  change itself happens through a NORMAL HTTP RPC (`placeBid`, `updateLot`, …)
+  that publishes the new row.
+- **Client → server push mid-session → a WebSocket channel.** ONLY when the
+  BROWSER must send up the socket without a page action: live chat messages,
+  typing indicators, cursors/presence.
+
+A screen being called a "room", or being multi-user, or being live is NOT a
+reason to use a channel. If the browser isn't pushing frames up, it's SSE.
+
+## Level 1 — live updates (event-hub SSE, the default)
+
+Two halves; both are required or nothing arrives.
+
+**Backend — publish after every write.** In each create/update/status function,
+AFTER the DB write, publish the changed row on a topic:
+
+```ts
+const lot = await kysely
+  .updateTable('lot')
+  .set({ status: 'sold' })
+  .where('id', '=', input.lotId)
+  .returning(['id', 'status', 'currentBid', 'updatedAt'])
+  .executeTakeFirstOrThrow()
+await eventHub.publish('lot-updated', null, { topic: 'lot-updated', data: lot })
+return lot
+```
+
+**A topic is PUBLIC — publish a projection, never `returningAll()`.** The generated
+`/events/:topic` route is wired `auth: false` with a sessionless handler, so anyone who can
+reach the origin can subscribe to any topic name and read every frame on it. `returningAll()`
+then ships the whole row — `reservePrice`, `sellerId`, internal notes, whatever the table
+grows next — to unauthenticated subscribers, and it does it silently because the RPC's own
+`output` schema never sees the event payload. List the columns the topic is FOR, the way the
+example does. If a change genuinely has per-viewer content, it does not belong on a topic:
+publish an id-only "something changed" frame and let each client refetch through an
+authenticated RPC that applies its own permissions.
+
+The **2nd arg is the channel to EXCLUDE** from the broadcast: pass `null` from a
+normal HTTP/RPC write (there is no one to skip); pass `channel.channelId` ONLY
+when you publish from INSIDE a channel handler, or the sender gets an echo of its
+own update. `eventHub` is already injected — do not wire it.
+
+**Frontend — subscribe over SSE.** The generated
+`PikkuRealtime.subscribeToTopic(topic, handler)` opens an SSE stream to the
+built-in `/events/:topic` route. Seed state from a normal query, then patch it as
+events arrive; the event is the `{ topic, data }` envelope, so read `.data`.
+
+```tsx
+import { useEffect } from 'react'
+import { useQueryClient } from '@tanstack/react-query'
+import { realtime } from '../lib/pikku'
+
+export function useLiveLots() {
+  const queryClient = useQueryClient()
+
+  useEffect(() => {
+    const subscription = realtime.subscribeToTopic('lot-updated', () => {
+      queryClient.invalidateQueries({ queryKey: ['listLots'] })
+    })
+    return () => subscription.close()
+  }, [queryClient])
+}
+```
+
+**Invalidate; do not hand-patch the cache.** The generated hooks key a query as
+`[name, input]` — `['listLots', { status: 'open', cursor: undefined }]`, one entry per set of
+arguments — so `setQueryData(['listLots'], …)` writes to a key nothing reads and the screen
+never changes. `invalidateQueries({ queryKey: ['listLots'] })` prefix-matches, so it refreshes
+every variant of that list whatever input each one was fetched with.
+
+Patching also has to know the payload's shape, and a list RPC returns
+`ListOutput<Lot>` — `{ rows, nextCursor, totalCount? }`, not `Lot[]` — so a `rows.map(...)`
+updater is reading `.map` off an object. Refetching sidesteps both, and it re-applies the server's own filtering,
+which a locally patched row does not: a lot that just moved to `sold` may no longer belong in
+an "open lots" list at all.
+
+`subscribeToTopic` returns `{ close }` — ALWAYS close on unmount or you leak the
+stream. Never hand-roll an `EventSource`.
+
+## Level 2 — two-way channel
+
+Only when the client pushes up the socket. The backend channel lives in its own
+`*.channel.ts` with `onConnect`/`onMessage` handlers:
+
+```ts
+import { pikkuChannelFunc, wireChannel } from '#pikku/channel'
+
+export const onMessage = pikkuChannelFunc<{ text: string }>({
+  func: async ({ eventHub }, input, { channel, session }) => {
+    const message = { id: crypto.randomUUID(), text: input.text, userId: session!.userId }
+    await eventHub.publish('room', channel.channelId, { topic: 'room', data: message })
+    return message
+  },
+})
+
+wireChannel({ name: 'room', route: '/room', auth: true, onMessage })
+```
+
+The frontend opens it with `PikkuRealtime.connectToChannel(path)`, which returns
+a socket you both `.send(...)` on and read via `onmessage`:
+
+```tsx
+useEffect(() => {
+  const socket = realtime.connectToChannel('/room')
+  socket.onmessage = (event) => appendMessage(JSON.parse(event.data))
+  return () => socket.close()
+}, [])
+```
+
+Publish server→client fan-out from a channel handler with
+`eventHub.publish(topic, channel.channelId, envelope)` — the 2nd arg excludes the
+sender, so the browser that sent the message does not receive its own echo.
+
+## Do NOT
+
+- Do **not** grep the project for existing SSE/eventHub infra to reverse-engineer
+  or copy — the patterns above ARE the template (same rule as never reading
+  `.gen.ts` to learn an API).
+- Do **not** write a custom `sse: true` HTTP route or a bespoke `EventSource` for
+  an ordinary live feed — the event-hub covers it. (A dedicated `sse: true` route
+  is only for a long-job PROGRESS stream, and is not needed for an initial build.)
+- Do **not** use a WebSocket channel for a live board/ticker/room — that is SSE.
+  A channel is for client→server push (chat/presence) ONLY.
+- Do **not** forget the backend `eventHub.publish(...)` — a subscribed frontend
+  with no publisher is a silent, empty stream.

package/skills/pikku-seo/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: pikku-seo
+description: >-
+  On-page SEO rules for the app's PUBLIC pages: per-route head() titles and meta descriptions, Open Graph tags, one-h1 heading hierarchy, semantic/crawlable markup, JSON-LD on the landing page, and noindex for the logged-in area.
+  TRIGGER when: building or reworking any public page (landing, pricing, about, blog/content pages), writing page titles or meta tags, or the user asks about SEO / Google / discoverability / social sharing previews.
+  DO NOT TRIGGER when: working on logged-in /app screens (they are noindexed — only the one robots rule below applies), backend functions, database, or deployment.
+installGroups: [client]
+---
+
+# SEO Rules
+
+Apps render SSR from the edge, so crawlers see full HTML — the ranking work is
+getting the on-page signals right while you build. These rules apply to PUBLIC
+routes only (the landing page and any marketing/content pages). The logged-in
+`/app` area is private: it gets `noindex` and nothing else from this skill.
+
+## Per-route head() — every public route, no exceptions
+
+Titles and descriptions live in TanStack Start's `head()` on the route, merged
+root → leaf (the leaf's title/meta win). The root route already carries the
+site-wide defaults and OG tags; every public page you add MUST override both:
+
+```tsx
+export const Route = createFileRoute('/pricing')({
+  head: () => ({
+    meta: [
+      { title: 'Pricing — Acme Scheduling' },
+      {
+        name: 'description',
+        content:
+          'Simple per-seat pricing for Acme Scheduling. Start free, upgrade when your team grows — no setup fees, cancel anytime.',
+      },
+      { property: 'og:title', content: 'Pricing — Acme Scheduling' },
+      { property: 'og:description', content: 'Simple per-seat pricing. Start free.' },
+    ],
+  }),
+  component: PricingPage,
+})
+```
+
+`head()` strings are plain strings (they do not go through the Mantine i18n
+gate) — write real copy for THIS app, in the app's voice.
+
+- **Title**: unique per page, 50–60 characters, the page's primary topic first,
+  brand at the end (`Topic — AppName`). The template's `__APP_TITLE__` default
+  must never survive the rebrand, on any page.
+- **Description**: unique per page, 150–160 characters, states the concrete
+  value of the page in plain language — a reason to click, not a keyword list.
+- **Dynamic public pages** (e.g. a public detail page) build both from loader
+  data: `head: ({ loaderData }) => ({ meta: [{ title: `${loaderData.name} — AppName` }, ...] })`.
+- **Never invent URLs**: the deployed domain is unknown at build time, so do
+  NOT emit `canonical`, `og:url`, or `og:image` pointing at a made-up domain —
+  omit them (same principle as the `/api` serverUrl rule). `og:image` only if a
+  real asset exists in the app.
+
+## Logged-in area = noindex
+
+The `/app` route (the authenticated layout route) gets exactly one meta entry:
+
+```tsx
+head: () => ({ meta: [{ name: 'robots', content: 'noindex' }] })
+```
+
+Never noindex a public page, and never put per-page SEO effort into `/app`
+screens — they are invisible to crawlers by design.
+
+## Headings — exactly one h1 per page
+
+- Every page has EXACTLY ONE h1 (`<Title order={1}>` in Mantine, `<h1>` in
+  Tailwind) and it names the page's primary topic — aligned with the title tag,
+  not identical boilerplate.
+- Logical hierarchy below it: h1 → h2 → h3, no skipped levels, headings
+  describe the content under them. Never pick a heading level for its font
+  size — set the size on the correct level (`<Title order={2} fz="xs">`).
+
+## Crawlable, semantic markup
+
+- Landmarks on public pages: `<nav>`, `<main>`, `<footer>` (Mantine: `component="nav"` etc.).
+- Navigation between public pages uses real links (`<Link>`/`<a href>`) with
+  descriptive anchor text — crawlers follow hrefs; a `div onClick` navigation
+  is invisible to them. No public page may be orphaned: every public page is
+  reachable by link from the landing page (directly or via nav/footer).
+- Every meaningful `<img>` has alt text describing the image; decorative images
+  get `alt=""`. Prefer descriptive file names for real assets.
+- Readable URLs: public routes are lowercase, hyphen-separated, and named for
+  their content (`/pricing`, `/how-it-works`) — never `/page2` or query-param
+  navigation.
+
+## JSON-LD on the landing page
+
+The landing page carries one structured-data script describing the product.
+Only mark up what is visibly true on the page — never invent ratings, reviews,
+or offers (fake schema is a Google penalty, not a boost):
+
+```tsx
+head: () => ({
+  meta: [
+    /* title + description as above */
+  ],
+  scripts: [
+    {
+      type: 'application/ld+json',
+      children: JSON.stringify({
+        '@context': 'https://schema.org',
+        '@graph': [
+          { '@type': 'Organization', name: 'Acme Scheduling', description: '…' },
+          { '@type': 'WebSite', name: 'Acme Scheduling' },
+        ],
+      }),
+    },
+  ],
+})
+```
+
+Add further types only when the page genuinely IS that thing and shows the
+required fields: `FAQPage` for a real FAQ section, `Article` for a blog post
+(headline, datePublished, author), `Product`/`Offer` for a real price list.
+Omit `url`/`logo` fields — deployed domain unknown (see "never invent URLs").
+
+## Verify
+
+Open each PUBLIC page and read its `<head>`: a title, a meta description, and
+exactly one `h1`. A public page is not done while any of the three is missing.
+Signed-in pages under `/app` are exempt once `noindex` is set — they are not
+indexed, so their head tags do not matter.
+
+## Don'ts
+
+- No keyword stuffing — write for the reader; one clear topic per page.
+- Don't duplicate the same title/description across pages (worse than absent).
+- Don't render SEO-critical copy only after client-side effects — it must be
+  in the SSR HTML (loader data is fine; `useEffect`-fetched content is not).
+- Don't add robots.txt/sitemap plumbing — the platform owns that layer.

package/skills/pikku-software-archaeology/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pikku-software-archaeology
 description: 'Use when reverse-engineering an existing repository into a Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner who holds the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language — JS, TS, Ruby, Python, PHP, Go) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator audience. DO NOT TRIGGER for: documenting code structure, generating API docs from an already-clean codebase, or an engineer-facing code review.'
+installGroups: [core]
 ---
 
 # Software Archaeology

package/skills/pikku-webhook/SKILL.md

@@ -121,6 +121,31 @@ With neither secret set, deliveries go **unsigned**. A missing named secret is
 logged as an error and still sends unsigned; treat that log line as a
 misconfiguration, not noise.
 
+## What this does not give you
+
+There is no subscription model. `webhookSchema` owns exactly two tables —
+`webhookDelivery` and `webhookDeliveryAttempt` — and both are delivery-side
+history. Nothing stores _which_ URL belongs to which customer, which events
+they asked for, or whether their endpoint is still enabled.
+
+That is the app's table, and every app that exposes webhooks to its users
+needs one:
+
+| Column    | Why                                                                                                           |
+| --------- | ------------------------------------------------------------------------------------------------------------- |
+| `url`     | where to POST                                                                                                 |
+| `secret`  | the raw HMAC key, passed as `SendWebhookInput.secret`                                                         |
+| `events`  | which event names this endpoint subscribed to                                                                 |
+| `enabled` | so a failing endpoint can be paused without deleting it                                                       |
+| scope     | the org/tenant column you filter on — mirror it into `organizationId` so the delivery log scopes the same way |
+
+So one emitted event becomes a `SELECT` over your endpoint table and one
+`send()` per row. Everything after that call — signing, queueing, retrying,
+recording — is the primitive's.
+
+The single-integration case needs none of this: one fixed URL on the row it
+belongs to, and `send()` straight at it.
+
 ## Verifying on the receiving side
 
 `sign()` produces `sha256=<hex>` (GitHub style, body only, no timestamp) into

package/skills/pikku-workflow/SKILL.md

@@ -27,6 +27,43 @@ See `pikku-concepts` for the core mental model.
 
 Build durable, multi-step workflows with automatic retry, sleep, suspend/resume, and parallel execution. Steps are cached for replay safety.
 
+## Decide FIRST: should this even BE a workflow?
+
+The deciding question is: **does any part of this cross an external boundary that can fail and MUST NOT be lost or double-run** — a payment authorised/captured through a provider, a third-party API call, an email/webhook, a wait for approval? If yes → workflow (durability, retries, restart-survival, and a visible run). If it's **a single algorithm done in one shot, purely local, and not reused elsewhere** → a plain `pikkuFunc` is correct; do NOT wrap it in a workflow.
+
+- **Checkout WITH payment → workflow.** Get cart → compute total → **(atomic: create order + order items, deduct stock, clear cart)** → **charge payment through the provider** → send confirmation email. It's a workflow because the payment leg (and the email) are external and must be **retried, not lost, and not charged twice** across a restart — and the user benefits from seeing where the run is.
+- **Checkout with NO external payment** — e.g. it just records the order and decrements stock in one transaction, nothing leaves the process — is a **single-shot algorithm**: a plain `pikkuFunc` wrapping one `kysely.transaction`. Not a workflow. A workflow here would add durability machinery for a thing that already commits atomically in one shot.
+- **One durable step is NOT a workflow — it's a queue worker.** A lone side-effect that must be retried / not lost (send one email, fire one webhook, one external charge) → a **queue worker** (`pikku-queue`), enqueued fire-and-forget. A workflow adds a step graph for a thing that has no steps to orchestrate. (A single non-durable step is just a direct RPC call.)
+- Also workflows: onboarding sequences, settlements/payouts, digests and batch sends, anything that waits (`sleep`/`suspend`) or fans out with retries — the common thread is **multiple** steps or a durable wait, never a single step.
+
+**HARD RULE — never a single-RPC (one-step) workflow.** A workflow whose body is one `workflow.do('x', 'someRpc', …)` is a mislabeled durable function, not orchestration. Route by durability, NOT into a workflow:
+
+- **Not durable** — the caller wants the result now / it can just run in-request → **call the RPC directly** (this is also the synchronous path). No workflow, no queue.
+- **Durable** — must be **retried / not lost / survive a restart** (one email, one webhook, one external charge) → a **queue worker** (`wireQueueWorker` + `queueService.add(...)`). Fire-and-forget, retried by the queue.
+
+There is no "one-step workflow is justified for the durability" exception — durability for a single step is a QUEUE. A workflow earns its name only with genuine multi-step orchestration (a `sleep`/`suspend` wait, fan-out, or a saga).
+
+**Atomicity is a TRANSACTION, not a workflow.** All-or-nothing multi-write units (create order + items + deduct stock + clear cart) belong inside ONE `kysely.transaction(async (trx) => { … })` — a single step or a single plain `pikkuFunc` — **never split across workflow steps.** A step is a unit of RETRY and REPLAY, not a unit of atomicity: pikku opens no transaction around `workflow.do`, so a step that does three writes and throws on the third leaves the first two committed, and the retry runs them again. Spreading one logical transaction over several steps is the same failure one level up. Your writes are atomic only where YOU opened a transaction, so open one inside the step (reach for compensating/saga steps only when you truly need cross-service rollback). So a payment checkout is a workflow whose _atomic DB writes are ONE step that opens ONE transaction_, with the payment charge and email as the other durable steps around it.
+
+**A retried step re-runs its side effects.** Replay caching only covers steps that already
+returned; a step that failed — or that timed out after the provider accepted it — runs again
+from the top, so a charge, an email or a webhook can fire twice. Durability is at-least-once,
+not exactly-once. Pass a stable idempotency key the provider deduplicates on, derived from the
+workflow's own data rather than generated inside the step:
+
+```typescript
+await workflow.do('Charge', 'chargePayment', {
+  orderId: data.orderId,
+  amount: data.amount,
+  idempotencyKey: `order-${data.orderId}-charge`,
+})
+```
+
+`randomUUID()` or `Date.now()` inside the step is a different key on every attempt, which is
+the double-charge. Where the provider has no such header, make the step itself idempotent —
+check for the effect before performing it, or record a unique row that the second attempt
+collides with.
+
 ## Choosing the right factory
 
 | Factory                    | When to use                                                                                                                                                                                                | Step-graph view?              |