@pikku/skills 0.12.34 → 0.12.37

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

@@ -0,0 +1,58 @@
+# Server bootstrap
+
+There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+
+**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+
+`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+
+```typescript
+// src/lifecycle.ts
+import { pikkuServerLifecycle } from '@pikku/core'
+import type { SingletonServices } from '../types/application-types.js'
+
+export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+  beforeStart: async ({ kysely }) => {
+    await runMigrations(kysely)
+  },
+  afterStart: async ({ logger }) => {
+    logger.info('accepting traffic')
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain()
+  },
+})
+```
+
+Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
+
+**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
+
+**2. Bootstrap it yourself (required for a specific runtime)**
+
+Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
+
+```typescript
+import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+// Pick your runtime:
+const server = new PikkuFastifyServer(
+  config,
+  singletonServices,
+  createWireServices
+)
+// or: new PikkuExpressServer(config, singletonServices, createWireServices)
+// or: pikkuAWSLambdaHandler(singletonServices)
+// or: PikkuCloudflareHandler(singletonServices)
+// or: pikkuNextHandler(singletonServices)
+
+await server.init()
+await server.start()
+```
+
+**Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
+
+`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.

package/skills/pikku-concepts/references/concept-mapping.md

@@ -2,6 +2,22 @@
 
 Authoritative mapping table plus side-by-side code examples showing how common backend patterns translate to Pikku.
 
+- [Quick Reference Table](#quick-reference-table)
+- [Route Handler / Controller → pikkuFunc](#route-handler--controller--pikkufunc)
+- [Route Parameters → Merged into Data](#route-parameters--merged-into-data)
+- [Middleware → pikkuMiddleware](#middleware--pikkumiddleware)
+- [Auth Guard → Built-in Auth Middleware](#auth-guard--built-in-auth-middleware)
+- [Authorization / Role Checks → pikkuPermission](#authorization--role-checks--pikkupermission)
+- [DTO / Request Validation → Standard Schema](#dto--request-validation--standard-schema)
+- [Dependency Injection → Service Factories](#dependency-injection--service-factories)
+- [WebSocket Handlers → wireChannel](#websocket-handlers--wirechannel)
+- [Job Queue Workers → wireQueueWorker](#job-queue-workers--wirequeueworker)
+- [Cron / Scheduled Tasks → wireScheduler](#cron--scheduled-tasks--wirescheduler)
+- [Module / Feature Grouping → Tags + File Organization](#module--feature-grouping--tags--file-organization)
+- [Error Handling → Typed Errors](#error-handling--typed-errors)
+- [Session Management](#session-management)
+- [API Client Generation](#api-client-generation)
+
 ## Quick Reference Table
 
 | Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |

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

@@ -0,0 +1,87 @@
+# What language you write in
+
+Three different things in a Pikku project have a human language, and they are
+**not** the same language. Collapsing them is the mistake this section exists to
+prevent, and it has already shipped in a real product — the failure is at the
+bottom.
+
+| Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
+| **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
+
+## Identifiers are English, and nothing changes that
+
+Not the product's market, not the team's working language, and **not `metaLocale`**.
+A German medical practice, an Arabic marketplace and a Japanese logistics tool
+all get `getOverview`, `AttentionStripe`, `case`, `event`.
+
+This is not linguistic preference, it is mechanics. Identifiers are the surface
+every other tool binds to: the generated `#pikku/*` clients, `pikku info` and
+`pikku meta`, the RPC map a scenario's `actor.invoke` is typed over, the
+generated SQL types, every skill and every agent that ever picks the project up.
+A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone who
+did not name it, and unlike a string it cannot be translated later — renaming an
+identifier is a migration, not an edit.
+
+## Meta follows `metaLocale`, and that is what the field is for
+
+```json
+{ "metaLocale": "de" }
+```
+
+Meta is the one part of a project the **Pikku Console** renders back to a human.
+A team reviewing their own functions, features and scenario reports in the
+Console is reading meta and nothing else, so a team whose working language is
+German should be able to read their Console in German. That is the entire reason
+the field exists.
+
+Read it before you author meta, and write descriptions, titles and templates in
+it. Absent, it is `en`. It is a BCP-47 tag (`en`, `de`, `pt-BR` — a hyphen, not
+an underscore), and the CLI rejects anything else by name.
+
+`metaLocale` is **not** licence to rename anything. `metaLocale: "de"` buys a German
+`description: 'Zeigt die Arbeitsliste'` on a function still called
+`getWorklist`.
+
+## Product UI language lives in the catalogue, and only there
+
+What the app says to its users is a translation concern, not a code concern. It
+belongs in `messages/<locale>.json`; `pikku-i18n` owns the details. The one rule
+worth repeating here: **`baseLocale` in `project.inlang/settings.json` stays
+`en`.** It names the message _source_ — the catalogue every other language is
+cloned from and translated against — so a project that sets it to anything else
+has no English catalogue to translate from and can never gain a second language
+without re-authoring every key.
+
+## The failure this comes from
+
+An agent was asked to build a doctor's portal for a German practice. The brief
+said "the entire UI is German, no English strings visible anywhere". The agent
+read one sentence about the product's users as an instruction about the
+codebase, and produced:
+
+- `project.inlang/settings.json` with `baseLocale: "de"` and `locales: ["de"]`,
+  no `en.json` at all — which silently broke `--add-locale` forever
+- RPC functions `getUebersicht` and `getPatientendetail`
+- React components `Zeitstrahl` and `AufmerksamkeitStreifen`
+- database tables `vorgang` and `ereignis`, with German columns
+
+Every one of those is wrong, and the brief was satisfied by none of them: a
+German UI needs German _messages_. What that project actually wanted was three
+settings, each on its own axis:
+
+```jsonc
+// project.inlang/settings.json — the message source stays English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a first-time visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "metaLocale": "de" }
+```
+
+Identifiers stay English throughout. When a brief tells you the product speaks a
+language, it is telling you about axis three and nothing else.

package/skills/pikku-deploy/SKILL.md

@@ -21,7 +21,7 @@ Use this skill as an execution checklist, not reference material.
 1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+4. Validate with the narrowest relevant command first, then run `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
 Signatures and option keys come from `pikku doc` — run `pikku doc --ai` for the

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, `fabric.config.json`, the pikku-verify workflow, 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, `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.'
 installGroups: [fabric]
 ---
 
@@ -18,7 +18,7 @@ Use this skill as an execution checklist, not reference material.
 2. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 3. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 4. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-5. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+5. Validate with the narrowest relevant command first, then run `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 6. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
 Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-wiring`, `pikku-services`, etc.
@@ -31,20 +31,20 @@ Always run project discovery first:
 yarn pikku meta context --json
 ```
 
-Call the `pikku-meta` tool before grepping or editing a Fabric app.
+Run `pikku meta` before grepping or editing a Fabric app.
 
-- Use `section: "context"` for the project map: functions, wires, workflows, capabilities, and source files.
-- Use `section: "clients"` before frontend/RPC work.
-- Use `section: "functions"` to list function ids, then `section: "function", id: "<functionId>"` for one function.
-- Use `section: "schemas"` to list schema names. Only request full JSON Schema bodies with `schemas: ["SchemaName"]` for the specific schemas needed.
+- `pikku meta context --json` for the project map: functions, wires, workflows, capabilities, and source files.
+- `pikku meta clients --json` before frontend/RPC work.
+- `pikku meta functions --json` to list function ids, then `pikku meta functions get <id> --json` for one function.
+- `pikku meta schemas --json` to list schema names. Only request a full schema body with `pikku meta schemas get <name> --json` when you need it.
 
 Do not load every schema body by default; that wastes context and usually makes the model worse.
 
 For database work:
 
-- Use `pikku-db` for the actual attached Fabric database state: tables, columns, foreign keys, and applied migrations.
-- Use `pikku-meta` `section: "schemas"` for code-level JSON Schema contracts, not database introspection.
-- Do not inspect database credentials or connect to the database directly; Fabric Control already exposes the safe introspection surface.
+- Use `pikku fabric db schema [--branch <branch>]` for the actual attached Fabric database state: tables and columns.
+- Use `pikku meta schemas` for code-level JSON Schema contracts, not database introspection.
+- Do not inspect database credentials or connect to the database directly; Fabric already exposes the safe introspection surface.
 
 ## Database: SQLite via libSQL
 
@@ -327,6 +327,19 @@ pikku fabric validate           # must pass clean
 pikku fabric deploy apply --production -y
 ```
 
+`init` and `link` import into whichever organization your session is in. When
+you belong to several — a personal one and a company one, say — name the target
+with `--organization`, taking a slug, a display name or an id:
+
+```bash
+pikku fabric link --organization vlandor
+```
+
+You have to be a member of the organization you name, and its GitHub account
+has to be connected already: importing a `github.com/<owner>/<repo>` repo needs
+the Fabric GitHub App installed on `<owner>` _and_ linked to that organization,
+or the import refuses by name.
+
 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:
 
@@ -424,16 +437,16 @@ the deploy with "local HEAD … ≠ remote …" even though your code is pushed.
 
 Functions with `expose: true` are versioned via `versions.pikku.json`. When you change a function's input or output schema, you must bump its version number — otherwise `pikku all` will report a breaking change and callers' generated clients become stale.
 
-The `pikku-verify` tool catches this automatically.
+`pikku all` catches this automatically.
 
 ## After every code change
 
-Always call the `pikku-verify` tool after modifying functions, wirings, or schemas. It runs:
+Run `pikku all` after modifying functions, wirings, or schemas, then `tsc --noEmit`:
 
 1. `pikku all` — regenerates all codegen, checks version compliance
 2. `tsc --noEmit` — validates TypeScript types
 
-The output card shows whether any breaking changes were detected.
+Breaking changes are reported by the version check in step 1.
 
 ### `app-missing-actor-quick-login-<app>`
 

package/skills/pikku-guide/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: pikku-guide
+description: >-
+  Use when writing or regenerating a Pikku project's user guide — the end-user documentation
+  built from the scenario suite with `pikku scenario guide`. Pages are hand-written markdown that
+  cite features (pikkuFeature); the recordings and screenshots a passing `--screenshots` run
+  filed for each cited feature are merged in as figures. Covers writing the prose, the
+  `<!-- pikku:guide feature=… -->` markers, the capture step, `.guide.lock` staleness,
+  `document: false`, `--allow-undocumented`, `--artifact-base`, and the traps that make a guide
+  come out empty or refused. TRIGGER when: user asks for a user guide, help pages, docs with
+  screenshots, or "document the app". DO NOT TRIGGER when: user asks about API reference docs,
+  README files, or writing the scenarios themselves (use pikku-scenario).
+installGroups: [core]
+---
+
+# Pikku Guide
+
+A guide is the app explained to the people who use it, with the scenario suite
+as its evidence. The suite proves what the product does and photographs it
+doing it; the pages say what that means for the reader and how to do it.
+
+Three inputs, one output:
+
+| Input | Comes from | Owned by |
+|---|---|---|
+| Structure | `pikkuFeature` meta — which features exist, and that every one is cited | the suite |
+| Evidence | the latest passing run under `.pikku/scenario-runs/` — recordings and screenshots | the run |
+| Prose | markdown pages under `docs/` (or `--docs <dir>`) — **every word the reader reads** | a human, or you |
+
+**The run contributes pictures, never words.** Step sentences, scenario
+descriptions and feature names are written to prove a test, and none of them
+reaches the page. A page that is a two-line intro and a marker publishes as a
+wall of videos with no instructions — the most common way a guide comes out
+bad. The writing in §2 is the job; the rest of this skill is plumbing.
+
+`pikku scenario guide` writes one markdown file per source page into
+`.pikku/guide/` (or `--output`). It renders no HTML, resolves no asset URLs and
+calls no model. Images are ordinary relative `![caption](path)` references into
+the run directory; whoever hosts the markdown rewrites them, or you pass
+`--artifact-base /docs/_media/` for a host that serves them at a fixed address.
+
+Read **pikku-scenario** first if the project has no features or browser steps
+yet — the guide cannot be better than the suite under it.
+
+## 1. A page cites a feature
+
+A page is a markdown file with frontmatter and a marker pair where the block
+belongs:
+
+```markdown
+---
+title: Booking a course
+description: Finding a course, taking a place, and what happens after.
+---
+
+Courses run one evening a week for eight weeks. Book when you know which
+evening suits you; Intro to Improv is the place to start if you have never
+done improv before.
+
+1. Open **Courses**. Each course shows its evening and how many places are left.
+2. Choose a course, then **Book a place**.
+3. Confirm your details and choose **Book**.
+
+Your place appears under **My bookings**, and a confirmation email follows.
+
+<!-- pikku:guide feature=bookingsFeature -->
+<!-- /pikku:guide -->
+
+## The course says it is full
+
+A full course keeps a waiting list. Choose **Join the waiting list** and we
+email you the moment a place frees up — you are not charged until then.
+
+## Can I switch to another evening?
+
+Email us before the second week and we will move you if there is a place.
+```
+
+- `feature=` is the **exported identifier id** of the `pikkuFeature`, not its
+  display name.
+- A rebuild rewrites only the region between the markers. Everything around
+  them is yours and survives every run.
+- One page may cite several features; one feature may be cited by several
+  pages. The mapping is the union of every marker in the tree.
+- Frontmatter the compiler does not own (`slug`, `sidebar_position`, `draft`)
+  passes through untouched.
+
+The generated block is the feature's **figures and nothing else**: for each
+scenario, its recordings first (one per actor), then its screenshots, deduped
+across data-driven rows. Two strings from the suite do reach the page, as
+captions:
+
+| Figure | Caption |
+|---|---|
+| Recording | the scenario's `title`, then ` — ` and the actor's name |
+| Screenshot | the `name` it was taken under |
+
+So those two are user-facing copy: "Take a place on a course", "the course list,
+with places left on each ticket" — not "mira books c-intro-1024" or
+"courses /app/courses at 1440px". The scenario `description` and the steps are
+never rendered.
+
+A block is indivisible: all of a feature's figures land together, where the
+marker sits. Place the marker after the steps it illustrates, not before them.
+If one page needs figures beside two separate steps, those steps are two
+features.
+
+Organise pages by who reads them, not by feature: `docs/using/`,
+`docs/teaching/`, `docs/organising/`. Use the project's own vocabulary, the one
+on its screens — not internal table names.
+
+## 2. Writing the page
+
+Write it so a reader can do the task **with every figure removed**. The figures
+confirm; they do not instruct. A reader skims for the step they are stuck on,
+and cannot search a video.
+
+Before writing, read the screen's component and its copy, then the feature's
+scenarios. The screen is what renders; the scenario is what is proven, and its
+steps are the user's journey already in order. Write only what you have seen
+in one of them — a fluent page describing a flow that does not exist is worse
+than no page.
+
+Each task page carries, in the reader's language (the app's, not English by
+default):
+
+- **Why and when** — one short paragraph: what this is for, and when the reader
+  would reach for it. Never "This page documents…".
+- **The steps** — a numbered list, each one an action in the words on the
+  screen: "Open **Patienten** and choose **Patient anlegen**." Name buttons and
+  fields exactly as they read.
+- **What you see afterwards** — the state that means it worked.
+- **What goes wrong** — the refusal, the empty state, the thing that looks
+  broken but is not. Every empty state a scenario lands in and every
+  `expectError` in the feature is a candidate; this is usually the paragraph
+  readers came for.
+- **Where next** — links to the pages a reader goes to from here.
+
+Then the marker, after the steps it shows.
+
+A page that exists only to cite a feature — "every page loads", "acceptance",
+a smoke suite — is not a page. Cite that feature from the page whose screens it
+covers, or mark it `document: false`.
+
+Reassurance is content: "Codes held in reserve cost nothing until a patient
+uses one" is what stops a reader hesitating over the button. Explain the
+confusing thing, not the impressive one.
+
+## 3. Every feature is accounted for
+
+Every registered feature must be cited by some page. An uncited feature fails
+the command by name:
+
+```
+Feature 'barFeature' is cited by no page. Place `<!-- pikku:guide feature=barFeature -->` …
+```
+
+Two ways out, both deliberate:
+
+- Write the page. This is the normal answer.
+- The feature is plumbing nobody reads about (a session-health check, an
+  internal sync): `pikkuFeature({ …, document: false })`. Citing a
+  `document: false` feature is itself an error.
+
+`--allow-undocumented` downgrades the uncited-feature error to a warning, for a
+guide that is mid-way through being written. Do not hand one over with it on.
+
+A page citing an id that is not a registered feature is always an error — it
+describes something that no longer exists.
+
+## 4. Screenshots come from a capture step
+
+The run only files screenshots a step asks for. Add one browser step that opens
+a page and takes a shot, and call it from a scenario each feature owns:
+
+```ts snippet:guideCaptureStep
+```
+
+- The screenshot `name` is the figure caption. Write it as a caption: "the
+  course list, with places left on each ticket".
+- `{ showcase: true }` marks a shot fit to publish outside the run. `{ fullPage:
+  true }` photographs the whole scrollable page.
+- Contexts open at a pinned 1440×900 viewport with animations off, so two runs
+  photograph the same thing. Override with `E2E_VIEWPORT_WIDTH` /
+  `E2E_VIEWPORT_HEIGHT` or the playwright config, or call
+  `page.setViewportSize` inside the step for a phone-width shot.
+- Prefer a shot at the end of a real flow step (after the booking succeeds) over
+  a standalone "open and photograph" scenario — the figure then shows the state
+  the section describes.
+
+### Traps that make a block come out empty
+
+- **A feature whose scenarios are RPC-only files no screenshot.** The command
+  warns `whose run filed no screenshot — the block renders empty`. Fold that
+  scenario into a feature that has browser coverage, or add a browser capture
+  to it; do not invent a page just to photograph.
+- **A capture loop must iterate a named const.** `for (const s of [ … ])` with
+  an inline array literal cannot be extracted (PKU679) and the scenario becomes
+  silently empty. `const screens = [ … ] as const` then `for (const s of screens)`.
+- **A closing assertion runs wherever the last capture left the browser.**
+  Captures appended to the end of a scenario move the page out from under a
+  `then` that follows them. Capture after the last assertion, or re-navigate.
+- **Locale.** Playwright reports `navigator.language` as `en-US`. An app that
+  picks its locale from the browser renders English, and every copy assertion
+  in another language fails. Set the app's own stored locale with
+  `page.addInitScript` in **every** step that navigates, not only the first.
+
+## 5. Build it
+
+```sh
+# 1. a full, passing browser run that writes the shots to disk
+bunx --bun pikku scenario run local --run browser --screenshots
+
+# 2. merge prose + evidence → .pikku/guide/
+bunx --bun pikku scenario guide --docs docs
+```
+
+- `--screenshots` is what writes files. Without it `browser.screenshot()`
+  still returns bytes and nothing lands on disk, so every block is empty.
+- The run must have **passed**. A failed or killed run is refused — a page is a
+  claim that the product does what it says.
+- The run must be **the whole suite**. A run narrowed with `--flows`,
+  `--features`, `--tags` or `--exclude-tags` is refused, because pages built
+  from it would describe missing flows as though they did not exist. An
+  exclusion that matches nothing still counts — keep every narrowing flag out
+  of a CI invocation whose run feeds the guide. `--run-id <id>` picks an older
+  full run.
+
+## 6. `.guide.lock` — keeping prose honest
+
+`docs/.guide.lock` records, per feature, a hash of its scenarios' **step
+sentences and artifact ids** — deliberately not the image bytes. Restyling the
+UI changes every screenshot and no sentence, so it does not stale a page.
+Inserting, renaming or reordering a step changes what the prose around the
+block was describing, and the page is reported:
+
+```
+docs/using/booking.md was written against 'bookingsFeature' at 3f1a…, which is now 9c0e… — the flow moved, so re-read the prose around that block.
+```
+
+Re-read that page's hand-written text, fix what the flow change made untrue,
+and rebuild. The lock is rewritten on every successful build.
+
+- **Commit the lock.** It is generated, never hand-edited, never hand-merged. A
+  tree whose lock is untracked reports every page as current forever.
+- The first build after adding pages prints stale warnings for every feature
+  (there was no lock); they clear on the second build.
+
+## 7. Hand-over checklist
+
+- [ ] Every feature is cited, or declares `document: false` with a reason.
+- [ ] No `--allow-undocumented` in the command you report as done.
+- [ ] Built from a full, passing `--run browser --screenshots` run.
+- [ ] No "block renders empty" warnings.
+- [ ] No stale warnings left after the second build.
+- [ ] `docs/` pages and `docs/.guide.lock` committed; `.pikku/guide/` is output.
+- [ ] Every page reads as instructions with its figures removed: why and when,
+      numbered steps naming the controls as they read on screen, what goes
+      wrong.
+- [ ] No page exists only to cite a smoke or acceptance feature.
+- [ ] Scenario titles and screenshot names read as captions — no routes,
+      viewport sizes or test ids.
+- [ ] Open two generated pages and look at them: the figures are the screens the
+      text describes, in the app's language.

package/skills/pikku-knowledge/SKILL.md

@@ -14,6 +14,16 @@ description: >-
   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]
+agent:
+  tools: read, write, edit, bash, grep
+  timeoutMs: 1800000
+  acceptance:
+    level: verified
+    evidence: [changed-files, validation-output]
+    verify:
+      - id: knowledge-consistent
+        command: pikku knowledge validate
+
 ---
 
 # Pikku Knowledge

package/skills/pikku-kysely/SKILL.md

@@ -24,7 +24,7 @@ Use this skill as an execution checklist, not reference material.
 1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+4. Validate with the narrowest relevant command first, then run `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
 ## Writing Queries — the Kysely query builder

package/skills/pikku-mantine/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pikku-mantine
+description: >-
+  Use when building a Mantine UI on top of a Pikku backend — rendering dates that came back from a
+  generated client, keeping layout flow-relative so the app survives an RTL locale, and branching on
+  colour scheme without hardcoding a shade. TRIGGER when: putting a value from usePikkuQuery or an
+  RPC response on screen, writing margins/padding/alignment in Mantine props or CSS, choosing a date
+  input, or handling light/dark. DO NOT TRIGGER when: the data does not come from a Pikku client
+  (this is only about what the generated clients hand you), or for user-facing copy (use pikku-i18n).
+installGroups: [client]
+---
+
+# Mantine on a Pikku client
+
+## Dates — always format before rendering
+
+The generated clients run `transformDates`, which revives **fully-zoned ISO-8601 instants** —
+`2026-03-14T08:12:00Z`, `2026-03-14T08:12:00.000+01:00` — into `Date` objects and touches nothing
+else. A bare `2026-03-14`, a zoneless `2026-03-14T08:12:00` and an impossible `2026-02-31T00:00:00Z`
+all stay the strings the server sent. So a field's runtime type follows the VALUE, not the schema:
+one column can arrive as a `Date` from one row and a string from the next.
+
+Two consequences, and both compile:
+
+- **A string method on one white-screens the page.** `row.createdAt.split('T')[0]` type-checks
+  against nothing useful and blows up at runtime. There is no string to slice.
+- **A raw `Date` dropped into JSX crashes the route.** `<Text>{row.createdAt}</Text>`, a table cell,
+  a `<Badge>` — React throws `Objects are not valid as a React child (found: [object Date])` and the
+  page falls into its error boundary. Nothing catches it before the screen is white, which makes it
+  the most common broken page in a build.
+
+**Format with dayjs.** It is Mantine's own date library, already shipped alongside `@mantine/dates`,
+and it takes either a `Date` or a string. Never `toLocaleDateString`, `date-fns` or `luxon`.
+
+```tsx
+import dayjs from 'dayjs'
+
+<Text>{dayjs(row.dueOn).format('D MMM YYYY')}</Text>        // 15 Jun 2026
+<Text>{dayjs(row.createdAt).format('D MMM YYYY, HH:mm')}</Text>
+```
+
+A relative "2 days ago" via dayjs `relativeTime` is fine. Coercing instead of formatting
+(`` `${d}` ``, `String(d)`, `d + ''`) does not crash but prints
+`Mon Jun 15 2026 02:00:00 GMT+0200` — a different bug, equally wrong.
+
+Date **inputs** are `@mantine/dates` — `DatePickerInput`, `DatePicker`, `Calendar` — never a raw
+`<TextInput type="date">`. Those are pickers and they are not a schedule: Mantine ships no
+week/time-grid component, so a diary, rota, timetable or booking week is a grid you build, not a
+`Calendar` with the time-of-day left out. `Calendar` with `renderDay` IS right for "a few things on
+each day of a month", like a content calendar or a holiday planner.
+
+All of this applies to stub and fixture dates exactly as it does to real data.
+
+## RTL-safe styles
+
+Write layout styles flow-relative so the UI works in both LTR and RTL languages. Pikku's i18n ships
+Arabic, Hebrew, Farsi and Urdu support, and a physical margin is what breaks under it.
+
+| Avoid                         | Use instead                                |
+| ----------------------------- | ------------------------------------------ |
+| `ml`, `mr`, `pl`, `pr`        | `ms`, `me`, `ps`, `pe`                     |
+| `text-align: left/right`      | `text-align: start/end`                    |
+| `margin-left`, `margin-right` | `margin-inline-start`, `margin-inline-end` |
+| `flex-direction: row-reverse` | `dir` attribute or logical properties      |
+
+Mantine shorthand: `ms` = margin-inline-start, `me` = margin-inline-end, `ps` = padding-inline-start,
+`pe` = padding-inline-end.
+
+## Dark mode
+
+Use Mantine's `light-dark()` utility or `useMantineColorScheme`, and only with colours that already
+come from the theme — never introduce a literal colour or a shade string for one scheme.
+
+```tsx
+// Correct
+<Box bg="var(--mantine-color-body)">
+
+// Wrong — scheme branch with hardcoded Mantine shades
+<Box bg={theme.colorScheme === 'dark' ? 'dark.6' : 'gray.0'}>
+```