@pikku/skills 0.12.25 → 0.12.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.25",
+  "version": "0.12.26",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-a11y/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: pikku-a11y
+description: >-
+  Accessibility rules (WCAG 2.2) for the app UI: labeled inputs, real buttons/links, keyboard and focus, contrast and not-color-alone, modals, reduced motion.
+  TRIGGER when: building forms or any interactive UI, icon-only buttons, modals/drawers, tables/lists with actions, keyboard/focus work, or the user mentions accessibility / screen readers / WCAG.
+  DO NOT TRIGGER when: working on backend functions, database, or deployment with no UI.
+installGroups: [client]
+---
+
+# Accessibility Rules
+
+Mantine components are accessible ONLY when used properly — the rules below are the
+"properly". They apply to every page; heading order, landmarks, and image alt text are
+covered in the `pikku-seo` skill and apply app-wide, not just on public pages.
+
+## Every input has a label
+
+- Use the `label` prop on every Mantine input — a placeholder is NOT a label (it
+  disappears on input and is never announced as one). Placeholder = example value only.
+- Use the `error` and `description` props for validation/help text — Mantine associates
+  them with the input for screen readers; a loose `<Text c="red">` next to the field
+  does not.
+- Icon-only controls (`ActionIcon`, icon `Button`) MUST have `aria-label={m.key()}`
+  naming the action ("Delete item", not "Trash icon").
+
+## Interactive = a real button or link
+
+- Never `onClick` on a `div`/`Box`/`Card` — it is invisible to keyboard and screen
+  readers. Use `Button`, `ActionIcon`, `UnstyledButton`, or `<Link>`; navigation is a
+  link (href), actions are buttons.
+- Everything reachable by Tab, activatable by Enter/Space. Never remove focus outlines
+  (the theme owns the focus ring), never set `tabIndex` greater than 0, never trap focus
+  yourself.
+- Whole-row/whole-card click: put the button/link INSIDE with the row as its label —
+  don't make the container clickable and unfocusable.
+
+## Don't say it with color alone
+
+- Status must carry text or an icon, not only a color: a Badge says "Overdue", a form
+  error has a message — a red tint by itself is invisible to colorblind users.
+- Contrast comes from the theme; don't undermine it by stacking `c="dimmed"` on small
+  text over tinted backgrounds. Body copy stays at least AA-readable.
+- Touch targets: WCAG 2.2 minimum 24px — don't shrink `ActionIcon`/`Checkbox` below
+  size `sm`, and keep adjacent row actions spaced.
+
+## Overlays and motion
+
+- Modals/drawers: use Mantine `Modal`/`Drawer` and ALWAYS pass `title` — that is what
+  gets announced; focus trap and Escape come built in. (This project uses drawers, not
+  dialogs.)
+- Landing-page animation (the only custom-CSS surface) respects
+  `prefers-reduced-motion: reduce` — gate transforms/parallax behind the media query.
+
+## Self-check before declaring UI done
+
+Tab through the page once: every control reachable and visibly focused, every input
+labeled, every icon button named, every status readable without color. A browser
+scenario proves the flow works, not that it is reachable without a mouse — this
+manual pass is the only check that does.

package/skills/pikku-architect/SKILL.md

@@ -11,6 +11,7 @@ description: >-
   NOT TRIGGER when: the milestone notes themselves are still being written (use pikku-knowledge),
   the plan already exists and the job is to build it (use pikku-build), or the ask is a one-off
   edit to a working app.
+installGroups: [core]
 ---
 
 # Plan one milestone

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

@@ -15,7 +15,6 @@ The only acceptable auth implementation in a Pikku app is the one described in t
 
 ---
 
-
 ## Installation
 
 ```bash
@@ -448,9 +447,14 @@ someone" means **a particular kind of user** rather than one fixed admin.
 Register it explicitly — it is not automatic:
 
 ```typescript
-import { pikkuActor } from '@pikku/better-auth'
-
-plugins: [pikkuActor({ secret: SCENARIO_ACTOR_SECRET })]
+import { ACTOR_SIGN_IN_OPT_IN_ENV, pikkuActor } from '@pikku/better-auth'
+
+plugins: [
+  pikkuActor({
+    secret: SCENARIO_ACTOR_SECRET,
+    allowSignIn: await variables.get(ACTOR_SIGN_IN_OPT_IN_ENV),
+  }),
+]
 ```
 
 `POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
@@ -481,9 +485,19 @@ itself instead.
 A stage that genuinely must run scenarios opts in on purpose, with
 `PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in`. Any other value is
 ignored and warned about, so the hatch cannot be opened by copying a `true` from
-the line above, and it is the only hatch — there is no build-time option, because
-an option compiled into the bundle cannot be audited from the environment it
-runs in.
+the line above.
+
+**Pass it in on any runtime without a populated `process.env`.** The gate reads
+the environment by default, which is enough for Node but not for a Worker: there
+the opt-in arrives as a binding and reaches user code through the variables
+service, so a gate left to `process.env` stays shut on exactly the stages a
+deployment targets. `allowSignIn` takes the value the caller already read —
+`await variables.get(ACTOR_SIGN_IN_OPT_IN_ENV)` — and is checked against the same
+literal, near-miss warning included. It is deliberately a value and not a flag:
+what opens the gate is still something the deployment set and an operator can
+read back out of it, never something compiled into the bundle. A value passed
+here is the one consulted, so the environment cannot quietly override what the
+stage was configured with.
 
 **Signing in and provisioning are separate powers.** An unknown address becomes
 an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
@@ -624,3 +638,107 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables, kysely }) => be
 - Export exactly ONE `pikkuBetterAuth` per project; the CLI generates a single catch-all worker for all auth routes.
 - `betterAuthSession({ auth })` (generated) bridges the better-auth session into the Pikku session on every request — you never add it by hand.
 - MFA, organizations, passkeys, etc. are better-auth plugins: add them to `betterAuth({ plugins: [...] })`. The catch-all route already forwards their endpoints.
+
+---
+
+## Post-signup side effects
+
+Anything that must happen after a user signs up — a welcome email, seeding a first
+row, creating a personal organization — goes in `databaseHooks.user.create.after`
+inside the `betterAuth({...})` config. Never a custom signup RPC that writes the
+user itself: better-auth owns the `user` table, and a second write path desyncs it
+from the session bridge.
+
+## Two-factor (2FA / MFA)
+
+TOTP authenticator apps, email/SMS OTP, backup codes and trusted devices are all
+better-auth's `twoFactor()` plugin. Never hand-roll TOTP or OTP.
+
+1. **Enable + migrate** — add `twoFactor({ issuer: '<AppName>' })` to the `plugins`
+   array in the `pikkuBetterAuth` factory, then generate its schema and apply it as a
+   migration like any other table change. Run the CLI at the version of better-auth the
+   project actually has installed (`npx @better-auth/cli@<that version> generate`) — a
+   bare `npx @better-auth/cli` resolves the latest release, which can emit a schema for
+   a library you are not running. `twoFactorSecret` lands on `user`.
+2. **Client** — add `twoFactorClient({ onTwoFactorRedirect() { /* go to /2fa */ } })`
+   to `createAuthClient({ plugins: [...] })`, and expose thin wrappers
+   (`enable2FA`, `verifyTotp`, `disable2FA`, …) rather than leaking the raw
+   `authClient`, same as every other auth call.
+3. **OTP delivery** — `otpOptions.sendOTP` goes through the injected email service
+   and a rendered template, not a raw `sendEmail`. Set `storeOTP: 'encrypted'`.
+4. **Sign-in flow** — the challenge is raised on the three CREDENTIAL endpoints:
+   `signIn.email`, `signIn.username` and `signIn.phoneNumber`. Check
+   `context.data.twoFactorRedirect` in `onSuccess`; if true, route to a `/2fa` page
+   and verify via `verifyTotp`/`verifyOtp`/`verifyBackupCode` (`trustDevice: true`
+   for a 30-day trusted device). The response also carries `twoFactorMethods`
+   (`'totp'` only once that user has a verified secret, `'otp'` whenever
+   `otpOptions.sendOTP` is configured) — render the choice from it rather than
+   assuming TOTP. The session cookie is only created after verification: the
+   credential handler's session is deleted while the challenge is in flight, so a
+   hook reading `ctx.context.newSession` after sign-in must null-check it.
+5. **UI** — a QR rendered from `data.totpURI` plus the `data.backupCodes` list.
+   Enabling, disabling and regenerating backup codes all require the user's
+   password.
+
+TOTP secrets and backup codes are encrypted at rest with the auth secret, and
+`/two-factor/*` is rate-limited (3/10s) out of the box.
+
+**2FA gates credential sign-in only.** Magic link, email OTP and OAuth are not
+matched by the plugin's hook, so a user with 2FA enabled who signs in through one
+of them is NOT challenged. If every route into the app must be gated, either do not
+offer the passwordless ones to 2FA users or add your own check — enabling the
+plugin does not do it.
+
+## Security hardening
+
+The `pikkuBetterAuth` factory — where `betterAuth({...})` is built — is the one
+place to harden. Everything below is a `betterAuth` option, not a pikku one.
+
+- **Secret** — `BETTER_AUTH_SECRET` comes from the injected secrets service
+  (`await secrets.getSecret('BETTER_AUTH_SECRET')`), never `process.env`, a
+  literal, or a fallback default. 32+ chars, high entropy
+  (`openssl rand -base64 32`). Better Auth rejects placeholder secrets in
+  production.
+- **Trusted origins** — the `baseURL` origin is auto-trusted, so a single-domain
+  app serving its API same-origin needs nothing. Add `trustedOrigins` (or a
+  comma-separated `BETTER_AUTH_TRUSTED_ORIGINS` variable; wildcards like
+  `*.example.com` allowed) ONLY when the browser origin differs from the API
+  origin — embedded, preview, or custom-domain deployments. An untrusted
+  `callbackURL`/`redirectTo`/`origin` is a 403.
+- **CSRF** — keep it on (`advanced.disableCSRFCheck: false`, the default). A
+  proxy in front of the app must preserve the `/api/auth/*` prefix so origin
+  checks still work; do not disable the check to "fix" a redirect.
+- **Rate limiting** — on by default in production (100/10s global, 3/10s on
+  sign-in/up/change-password). `storage: 'memory'` resets on restart, so a
+  deployed app wants `storage: 'database'`. Tighten sensitive routes with
+  `customRules`, e.g. `'/sign-in/email': { window: 60, max: 5 }` — the key is matched
+  against the path with the base path ALREADY STRIPPED, so a rule written as
+  `'/api/auth/sign-in/email'` matches nothing and silently leaves the route on the
+  default.
+- **Cookies & sessions** — `httpOnly`, `sameSite: 'lax'` and `path: '/'` are
+  unconditional, but `secure` and the `__Secure-` name prefix are NOT: they follow a
+  `baseURL` on `https://` (or production, or an explicit
+  `advanced.useSecureCookies: true`). A deployment whose TLS terminates at a proxy
+  and passes an `http://` baseURL through therefore ships session cookies with no
+  `secure` flag — set `useSecureCookies` there rather than assuming. Defaults are
+  `session.expiresIn` 7d and
+  `updateAge` 1d. Add `freshAge` for sensitive actions, and
+  `cookieCache: { strategy: 'jwe' }` if the session carries sensitive data — see
+  the cookieCache section above, which you want enabled regardless. Only enable
+  `crossSubDomainCookies` if auth is genuinely shared across subdomains.
+- **OAuth tokens** — set `account.encryptOAuthTokens: true` (AES-256-GCM) if you
+  store provider tokens to call their APIs later.
+- **Audit** — drive auth events from `databaseHooks` (`session.create.after`,
+  `user.update.after` for email changes, `account.create.after` for links) into
+  whatever audit service the app injects, never a bespoke audit table wired into
+  a function body. Returning `false` from a `before` hook blocks the operation.
+- **Background tasks** — on a serverless target, hand genuinely disposable work
+  (analytics, logging) to `advanced.backgroundTasks.handler` → `ctx.waitUntil(promise)`
+  so it does not delay the response. Not mail: the default handler is
+  `p.catch(() => {})`, so anything that must actually arrive — an invitation, a
+  password reset — is lost without a trace if the platform reaps the request first.
+  Better Auth sends its own through `runInBackgroundOrAwait`, which awaits when no
+  handler is configured; do the same for yours.
+- **Enumeration** — handled already (generic "Invalid credentials", dummy work on
+  unknown users). Keep your own error copy generic too; never leak "user not
+  found".

package/skills/pikku-build/SKILL.md

@@ -12,6 +12,7 @@ description: >-
   or wants one specific surface explained rather than built (use that surface's skill).
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
 argument-hint: '[feature description]'
+installGroups: [core]
 ---
 
 # Build on Pikku

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

@@ -265,7 +265,7 @@ the database still holds that code no longer declares — both need §0's bootst
 to have run, and both are worth a look once it has.
 
 **One warning about the scaffold's own notes:** `knowledge/index.md` may claim
-the people live in `pikku.config.json`, put there by a `fabric persona` command.
+the people live in `pikku.config.json`, put there by a persona command.
 That is stale. In this template they live in `personas.ts` as above, and
 `pikku.config.json` carries no personas key at all — only `scenarios.emailDomain`.
 Trust the file you can read over the note describing it.

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

@@ -8,6 +8,61 @@ leaves `pikkufabric.config.json` pointing at an app nobody has designed yet.
 If the split is "one app with paths", you never need this file — add route
 segments under `/app` and give each audience its own entries in `useNavItems()`.
 
+## Deciding it is two apps, not one
+
+The split you are acting on should already be recorded, but this is the reasoning
+behind it — and the place people get it wrong is the third case at the bottom.
+
+**A group that comes in through its own front door gets its own app.** A role
+*inside* an app is not that: it changes which nav items and which buttons a person
+sees, and lives in `useNavItems()` and the `permissions` on the function, not in a
+route subtree.
+
+**The test is which side of the counter they are on.** Colleagues share one app and
+differ by nav — the mechanic, the person on the counter, the bookkeeper. Someone
+across the counter with an account of their own gets their own — the customer, the
+tenant, the patient. One app is a real answer and often the right one.
+
+**The asymmetry that forces a split is sign-up.** Where staff accounts are created
+*for* people and customers create their own, the two need different sign-up, different
+onboarding and different session shape, and bending one app around both costs more
+than the second app does. Do not collapse two audiences into one app to save a build.
+
+Never invent a person the notes do not name in order to reach two.
+
+### The group that never signs in
+
+Some people use the product with no account at all — ordering from a menu, booking a
+table, opening an invitation. They are not a third case, and **they do not get their
+own frontend**: an app is built around the personas who sign into it. What they get is
+the public route space every app already has.
+
+- **`/app/*` is the signed-in application.** One `beforeLoad` on `/app` bounces a
+  signed-out visitor to the login. There is no per-route exception.
+- **Every other route is public** — `/`, `/menu`, `/book`, `/r/$code`. No gate, no
+  session.
+- **`/` is a landing page and you must write it.** A starter that forwards `/` to
+  `/app` does so only because it ships no homepage. Leave the forward in and the
+  product's front door is a sign-in form: the anonymous visitor arrives at a login it
+  has no account for and never reaches the thing it came for — **while every check
+  still passes**, because everything that looks at the app signs in first. This is the
+  failure this section exists for.
+
+So a screen whose users have no account goes at `/menu`, never `/app/menu`.
+
+### The frontend guard is UX and proves nothing
+
+The bundle is on the origin and the nav is a client-side decision; anyone can read
+both. The security boundary is the `permissions` field on the function — see
+pikku-permissions. Hiding a nav item keeps people out of screens that would confuse
+them; it never protects data. Never let a hidden UI be the only thing between a user
+and someone else's record: if the invoices nav item is hidden but `listAllInvoices`
+has no `permissions`, the app is wide open and the nav is decoration.
+
+Worth a scenario each, because they are two different claims: that a mechanic cannot
+*see* the invoices nav item, and that their call to an invoices RPC is *refused*. The
+second is the one that catches a `permissions` field nobody wired.
+
 ## The clone
 
 ```bash

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

@@ -74,8 +74,8 @@ Everything above is open source. This is the contract that keeps
 - **`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 `fabric init` writes
-  the real one. Do not invent a value to make it look configured.
+  `__PROJECT_ID__` — that placeholder means "unlinked", and linking the project
+  writes the real one. Do not invent a value to make it look configured.
 - **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-fabric/SKILL.md

@@ -291,24 +291,40 @@ reload).
 pikku fabric login              # opens a browser; needs a human, wait for it
 pikku fabric init https://github.com/<owner>/<repo>
 pikku fabric validate           # must pass clean
-pikku fabric deploy apply --production --sync --auto-approve
+pikku fabric deploy apply --production -y
 ```
 
+The branch is positional and defaults to the checked-out one, and `-y` is the
+short form of `--auto-approve`, so a one-shot deploy is:
+
+```bash
+pikku fabric deploy apply -y            # the branch you are standing on
+pikku fabric deploy apply my-branch -y  # a named one
+```
+
+`-y` answers the prompts and nothing more. It does **not** approve migrations
+that drop or rewrite data — that stays `--allow-destructive`, typed out on
+purpose.
+
+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
+HEAD is refused by name rather than travelling on as a branch called `HEAD`.
+
 There is no `deploy plan` subcommand — `apply` runs the same auth, git-safety
 and ref resolution itself, and fabric produces the real plan server-side.
 
 `apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
-it refuses rather than hangs. `--auto-approve` supplies that confirmation; drop
-it only when a human is at a real terminal.
+it refuses rather than hangs. `--auto-approve` (`-y`) supplies that confirmation;
+drop it only when a human is at a real terminal.
 
-By default `apply` queues the deploy, prints the deployment id and returns. That
-tells you nothing about whether it worked. `--sync` waits for a terminal state
-and exits non-zero unless the deployment went live, which is the only form worth
-running in CI:
+`apply` waits for a terminal state and exits non-zero unless the deployment went
+live. `--detach` opts out — it queues the deploy, prints the deployment id and
+returns 0, which tells you nothing about whether it worked:
 
 | exit | meaning                                                                 |
 | ---- | ----------------------------------------------------------------------- |
-| 0    | live (or queued, without `--sync`)                                      |
+| 0    | live (or queued, under `--detach`)                                      |
 | 1    | the command could not run — not logged in, unsafe git state, bad flags  |
 | 2    | the deployment failed, errored, timed out server-side, or was cancelled |
 | 3    | the deployment is blocked and nothing the CLI can do will unblock it    |
@@ -318,14 +334,14 @@ Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
 Why it parked is the whole story, and it is `statusReason`, not `status`:
 
 - `awaiting_approval` — the plan is fine, a human has to publish it.
-  `--auto-approve` does that; without it you get exit 3 and the command to run.
+  `-y` does that; without it you get exit 3 and the command to run.
   One exception: if fabric marked any pending migration **destructive** — a
-  drop, a truncate, a rewrite — `--auto-approve` alone declines and exits 3,
+  drop, a truncate, a rewrite — `-y` alone declines and exits 3,
   because a standing yes was given before anyone knew the plan dropped a table.
   The CLI lists the migrations and fabric's reasons; `--allow-destructive`
-  accepts them for that deploy.
+  accepts them for that deploy, and `-y` implies it.
 - `needs_config` — a declared secret or variable has no value covering the
-  stage. The CLI names them. `--auto-approve` will **not** force this through;
+  stage. The CLI names them. `-y` will **not** force this through;
   set the values and re-attach — `pikku fabric secrets set <name>` for a
   declared secret, `pikku fabric variables set <name> --value <v>` for a declared
   variable. They are separate stores: a secret is sealed to the stage and cannot
@@ -334,24 +350,25 @@ Why it parked is the whole story, and it is `statusReason`, not `status`:
   stage exactly as it is from `.env`, and `--value '"true"'` is the string.
 - `needs_attention` — the plan is red. Nothing to approve.
 
-`--sync` defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
+The wait defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
 it prints the deployment id and the re-attach command rather than lying about
 the outcome.
 
 Splitting kick-off from waiting across two CI jobs is the reason
-`--deployment-id` exists:
+`--deployment-id` exists, and what `--detach` is for — the first job here has to
+return the id and exit rather than wait:
 
 ```bash
-id=$(pikku fabric deploy apply --production --auto-approve --json | jq -r 'select(.event=="result").deploymentId')
+id=$(pikku fabric deploy apply --production -y --detach --json | jq -r 'select(.event=="result").deploymentId')
 # …later, in another job…
-pikku fabric deploy apply --deployment-id "$id" --sync --auto-approve
+pikku fabric deploy apply --deployment-id "$id" -y
 ```
 
 `--deployment-id` skips the git safety check entirely (the deployment already
 pins a sha, and the checkout is allowed to have moved on) and refuses to be
-combined with `--branch`/`--production`, which would let the two disagree.
+combined with a branch or `--production`, which would let the two disagree.
 
-Under `--json`, `--sync` emits one NDJSON event per line — `created`/`attached`,
+Under `--json`, the wait emits one NDJSON event per line — `created`/`attached`,
 `status` on each transition, `blocked`, `approved` — and the last line is the
 terminal result object, tagged `"event": "result"`.
 

package/skills/pikku-i18n/SKILL.md

@@ -63,9 +63,11 @@ is what makes an RTL language just another locale file.
 - **Do not `asI18n()` a hardcoded English string.** `asI18n` exists to pass
   opaque server data (a name, a slug, an id) through the i18n gate. An enum value
   goes through its generated label map.
-- **Do not wrap `m`.** No re-export module, no branding layer. `m.some__key()`
-  already satisfies the `I18nNode` gate; a wrapper adds nothing and costs
-  per-message tree-shaking.
+- **Do not wrap `m` without a reason you can name.** `m.some__key()` already
+  satisfies the `I18nNode` gate, so a plain re-export module adds nothing and
+  costs per-message tree-shaking. Wrapping the namespace is only worth it when it
+  buys a feature the gate cannot — debug masking of translated copy, say — and
+  then the catalogue has to be small enough to ship whole.
 - **Do not translate message keys.** `auth__login__title` stays English in
   `de.json`; only the value changes.
 - **Do not edit or commit `src/paraglide/`, `i18n-enum.gen.ts` or `enums.gen.ts`.**

package/skills/pikku-knowledge/SKILL.md

@@ -13,6 +13,7 @@ description: >-
   brief to record. DO NOT TRIGGER when: user asks what
   functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
   note), or to write a scenario test (use pikku-scenario).
+installGroups: [core]
 ---
 
 # Pikku Knowledge

package/skills/pikku-list-query/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: pikku-list-query
+description: >-
+  Use when building a paginated/infinite-scroll list — any RPC that returns rows a user scrolls through (tables, card grids, search results). Covers pikkuListFunc, the ListInput/ListOutput cursor contract, and the generated usePikkuInfiniteQuery hook.
+  TRIGGER when: user asks for infinite scroll, "load more", a paginated table/list/grid, or a list that could grow beyond a single page.
+  DO NOT TRIGGER when: the list is small and fixed (e.g. a settings page with 5 items) — a plain pikkuFunc + usePikkuQuery returning a full array is simpler and correct there.
+installGroups: [core, client]
+---
+
+# Pikku List Queries
+
+## Agent Operating Procedure
+
+1. Capture baseline. Run `pikku all` BEFORE writing code; only NEW errors are yours to fix.
+2. Write the backend function with `pikkuListFunc` (below) — never a bespoke `{items: [...]}` shape once the list can page.
+3. Run `pikku all` to regenerate `usePikkuInfiniteQuery` for the new function.
+4. Wire the frontend with `usePikkuInfiniteQuery`, not a hand-rolled `useState` page counter and not a raw `useInfiniteQuery` — the generated hook already resolves cursor plumbing from your function's types.
+5. Validate with `pikku all`.
+
+## The `pikkuListFunc` contract
+
+A list function is a normal `pikkuFunc`/`pikkuSessionlessFunc` whose input/output conform to two shared shapes from `@pikku/core`:
+
+```typescript
+interface ListInput<F extends Record<string, unknown> = {}, S extends string = never> {
+  cursor?: string // opaque — echo back whatever you returned as nextCursor
+  limit?: number // page size; server may cap it
+  sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
+  filter?: Filter<F> // structured AND/OR tree, Prisma-style leaf operators
+  search?: string // free-text search across server-chosen fields
+}
+
+interface ListOutput<Row> {
+  rows: Row[]
+  nextCursor: string | null // null = no more pages
+  totalCount?: number // optional — skip when expensive to compute
+}
+```
+
+Adopting this shape is what makes the function eligible for the generated `usePikkuInfiniteQuery` hook — the react-query codegen structurally detects any RPC whose output includes `nextCursor` and generates an infinite-query hook for it automatically. No manual wiring, no opt-in flag.
+
+```typescript
+import { pikkuListFunc } from '#pikku/function'
+
+interface Item {
+  id: string
+  label: string
+}
+
+export const listItems = pikkuListFunc<{ status?: string }, Item>({
+  expose: true,
+  auth: true,
+  readonly: true,
+  description: 'List items for the signed-in user, paginated.',
+  // `input` is inferred as ListInput<{ status?: string }> from the generics above —
+  // never re-annotate it inline.
+  func: async ({ kysely }, input, { session }) => {
+    // `limit` is caller-supplied on an exposed RPC, so it is CAPPED, not trusted —
+    // `ListInput` says "server may cap" and this is where that happens.
+    const limit = Math.min(Math.max(Math.trunc(input.limit ?? 20) || 20, 1), 100)
+    const parsed = input.cursor ? Number(input.cursor) : 0
+    const offset = Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0
+
+    let query = kysely.selectFrom('item').where('userId', '=', session!.userId)
+    const status = leafEquals(input.filter, 'status')
+    if (status !== undefined) {
+      query = query.where('status', '=', status)
+    }
+
+    const rows = await query.orderBy('createdAt', 'desc').offset(offset).limit(limit).execute()
+    const nextOffset = offset + rows.length
+    const totalCount = await query
+      .select((eb) => eb.fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+
+    return {
+      rows: rows.map((r) => ({ id: r.id, label: r.label })),
+      nextCursor: nextOffset < totalCount.count ? String(nextOffset) : null,
+      totalCount: totalCount.count,
+    }
+  },
+})
+```
+
+Cursor doesn't have to be a numeric offset — any opaque string works (a keyset value, an encoded timestamp, etc.), as long as you can turn it back into a query position on the next call.
+
+## Frontend: `usePikkuInfiniteQuery`
+
+Generated automatically alongside `usePikkuQuery`/`usePikkuMutation` once `reactQueryFile` is configured (see the react-query wiring docs) — no separate setup for list functions specifically.
+
+```tsx
+import { usePikkuInfiniteQuery } from '.pikku/pikku-react-query.gen'
+
+function ItemList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = usePikkuInfiniteQuery(
+    'listItems',
+    { limit: 20 }, // never pass cursor here — the hook manages it
+  )
+
+  const rows = data?.pages.flatMap((page) => page.rows) ?? []
+
+  return (
+    <>
+      {rows.map((row) => (
+        <div key={row.id}>{row.label}</div>
+      ))}
+      {hasNextPage && (
+        <button disabled={isFetchingNextPage} onClick={() => fetchNextPage()}>
+          Load more
+        </button>
+      )}
+    </>
+  )
+}
+```
+
+For scroll-triggered loading (rather than a button), pair it with an `IntersectionObserver` sentinel at the end of the list that calls `fetchNextPage()` when it enters the viewport and `hasNextPage` is true — don't poll on a scroll event handler.
+
+## Common mistakes
+
+- **Bespoke output shape** (`{items, total}` with no `nextCursor`) — compiles, but disqualifies the function from `usePikkuInfiniteQuery`; you're left hand-rolling pagination state. Use `ListOutput<Row>`'s field names (`rows`, `nextCursor`) even if you don't need `filter`/`sort`/`search` yet — they're optional.
+- **Fixed large `limit` instead of real pagination** (e.g. `{ limit: 500 }` fetched once) — works until the collection outgrows the cap, then silently truncates. If a list can grow unbounded, page it from the start.
+- **Passing `cursor` manually into `usePikkuInfiniteQuery`'s input argument** — the hook injects it into each page request itself; the input you pass is the _base_ filter/limit shared by every page.
+
+## `filter` is a TREE, not a bag of fields
+
+`Filter<F>` is recursive: an **array** is an AND of its children, a **multi-key object** is
+an OR keyed by labels that mean nothing at evaluation time, and only a **single-key object**
+is a leaf. A leaf's value is either the value itself or an operator object
+(`{ contains, in, gt, gte, lt, lte, not, startsWith, … }`).
+
+So `'status' in input.filter` answers `false` for `[{ status: 'open' }, { userId: 'u1' }]`
+and for `{ status: { in: ['open', 'held'] } }` — the first because the filter is an array,
+the second because the value is an operator object rather than the string the code then
+compares. Both cases **silently return unfiltered rows**, which on a list endpoint means
+handing back records the caller asked to exclude. Pikku ships no filter-to-SQL helper: the
+backend decides what it accepts, and it has to say so.
+
+Read exactly the shape you support, and refuse the rest rather than ignoring it:
+
+```typescript
+import type { Filter } from '@pikku/core/function'
+
+/** The one shape this endpoint accepts: a single-key leaf with a plain value. */
+function leafEquals<F extends Record<string, unknown>, K extends keyof F & string>(
+  filter: Filter<F> | undefined,
+  field: K,
+): F[K] | undefined {
+  if (!filter || Array.isArray(filter)) return undefined
+  const keys = Object.keys(filter)
+  if (keys.length !== 1 || keys[0] !== field) return undefined
+  const value = (filter as Record<string, unknown>)[field]
+  if (value !== null && typeof value === 'object') {
+    throw new Error(`filter.${field} takes a value, not an operator object`)
+  }
+  return value as F[K]
+}
+```
+
+Supporting AND/OR or operators means walking the tree properly — recurse into the array and
+the multi-key object, and map each leaf operator to its Kysely equivalent. Do that when the
+UI needs it; until then, throwing on the shapes you do not handle is what stops a filter
+from being quietly dropped.