@pikku/skills 0.12.35 → 0.12.37

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
 
@@ -437,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-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-n8n-import/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pikku-n8n-import
 description: 'Use to import an n8n workflow JSON export into a runnable Pikku workflow. Triggers when the user says "import this n8n workflow", "convert this n8n export to pikku", points at an n8n `.json` export or a directory of them, or picks up after `pikku import n8n` left throwing stub functions (`STUB — generated from n8n …`, `— implement me`) or a `<workflow>.integrations.json` manifest. Owns the whole flow: run the importer, triage what it could not map, fill each stub, report any missing `@pikku/addon-*` integrations, and verify the result compiles and runs with no surviving stubs. DO NOT TRIGGER for hand-written addon wiring unrelated to an n8n import (use pikku-addon), or for authoring workflows from scratch (use pikku-workflow).'
+installGroups: [core]
 metadata:
   version: 1.0.0
 ---
@@ -19,14 +20,14 @@ missing dependency).
 
 ## Agent Operating Procedure
 
-1. Discover before editing. Prefer `pikku-meta`/`pikku meta ... --json` when
+1. Discover before editing. Prefer `pikku meta ... --json` when
    available; inspect only the focused output you need.
 2. Identify the source file that owns the behavior. Do not start from generated
    output, `.pikku`, `node_modules`, or vendored packages.
 3. Make the smallest source change that satisfies the task. Keep generated files
    generated.
-4. Validate with the narrowest relevant command first, then `pikku all` /
-   `pikku-verify` when functions, wirings, or schemas changed.
+4. Validate with the narrowest relevant command first, then `pikku all` when
+   functions, wirings, or schemas changed.
 5. If validation fails, fix the source cause and rerun. Never edit generated
    files to hide an error.
 

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

@@ -1,6 +1,18 @@
 # Pikku React
 
 
+What is here:
+
+- [What ships](#what-ships)
+- [Resolving the server URL](#resolving-the-server-url)
+- [Setup at the app root](#setup-at-the-app-root)
+- [Calling an RPC directly (no React Query)](#calling-an-rpc-directly-no-react-query)
+- [Calling fetch directly](#calling-fetch-directly)
+- [Realtime subscriptions](#realtime-subscriptions)
+- [When to reach for what](#when-to-reach-for-what)
+- [Authentication](#authentication)
+- [What NOT to do](#what-not-to-do)
+
 ## What ships
 
 ```tsx

package/skills/pikku-realtime/SKILL.md

@@ -3,17 +3,17 @@ 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).
+  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 (see `pikku-wiring`'s scheduler and queue references, or `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.
+There is NOTHING to hand-roll and NOTHING to "find". `pikku enable events` wires
+the event-hub SSE transport and generates the typed client, 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)
 

package/skills/pikku-report/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: pikku-report
+description: >-
+  Use when pikku itself cost you time — wrong generated types, a check that passes when it
+  should not, output that is quietly wrong, a skill that misled you — or when the user asks you
+  to report a framework bug, file a finding, or look at what is queued. Owns `pikku fabric
+  report` (a finding is about pikku, not the app), the product-vs-harness kinds, the
+  workaround-first ladder, and the local findings spool. TRIGGER when: the framework fought you,
+  codegen produced something broken, a skill told you to run something that does not exist, the
+  user says "report this to pikku" / "file a finding" / "check the findings queue", or a finding
+  was queued and never sent. DO NOT TRIGGER when: the bug is in the app you are building (fix it
+  there), or you are tempted to patch pikku's source (never do that from an app).
+installGroups: [core]
+---
+
+# Report a finding to Fabric
+
+A finding is about **pikku**, not about the app you are building. It is how the
+framework learns what cost its users time — the bug, the misleading skill, the
+silence where a check should have complained.
+
+Nothing is written to the repository. The terminal receipt shows exactly what
+left your machine, and the command is spelled `pikku fabric report` — there is
+no top-level report command.
+
+## Report at the moment it happens
+
+Not at the end from memory: a run that falls over never reaches its end, and the
+mechanism is already loaded while you are in it. One finding per thing that
+fought you.
+
+The ladder decides how much to spend:
+
+1. **Find the quicker workaround.** The user is paying for their feature, not
+   for pikku's health.
+2. **Investigate** only when there is no workaround, or when the user asks why
+   something is slow or wrong.
+3. **Report at the depth you already reached.** Never spend extra effort to
+   file; never throw away effort you already spent. If the investigation took
+   you to the mechanism, the finding says so — named file, named function, what
+   is actually happening, and what pikku should do instead.
+
+## What counts
+
+Anything that cost you time and would cost the next person the same. Most of
+these never produce an error: output that is quietly wrong, a generated type
+that disagrees with the runtime, a check that passes when it should not, a
+narrowing you had to write by hand because the framework should have written
+it. **Having to write code the framework should have written for you is a
+finding.**
+
+Also anything that only shows up in one place — invisible locally, fatal
+deployed, or the reverse. Say which with `--surface local|deployed|both`.
+
+Not a finding: a preference, a thing you would have designed differently, or
+baseline noise that was already failing before you started.
+
+## Two kinds
+
+- `--kind product` — pikku behaved wrongly. Fixing it is a change to the
+  framework.
+- `--kind harness` — a skill misled you: it told you to run something that does
+  not exist, described a flag that is spelled differently, or contradicted what
+  the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
+  section>"`. This is the most useful kind to file, because it is fixable
+  immediately — so file it even when the cost was small.
+
+## The command
+
+Send it as JSON on stdin. Most of a finding is prose, and prose carries
+apostrophes, quotes, backticks and newlines — each one a shell metacharacter
+before it is a character in your sentence. A stack trace passed to `--error`
+breaks the command at its first newline; a backtick in `--actual` runs whatever
+follows it. Quote the heredoc delimiter (`<<'EOF'`, never `<<EOF`) so the shell
+leaves the body alone.
+
+```bash
+pikku fabric report --stdin <<'EOF'
+{
+  "title": "<one-line title>",
+  "kind": "product",
+  "model": "<the model you are>",
+  "expected": "<what you expected pikku to do>",
+  "actual": "<what it did instead>",
+  "command": "<the command you ran>",
+  "workaround": "<what you did instead, inside the app>"
+}
+EOF
+```
+
+The same fields exist as flags for a finding short enough to type; `pikku fabric
+report --help` lists them. Whichever path you use, the rules below are checked
+before anything is sent:
+
+- `kind` is `product` or `harness`, and a `harness` finding names the skill that
+  misled you.
+- A resolved finding carries the `workaround` you used (or a `proposal`).
+- `--unresolved` means **no workaround was found** — it requires `--tried` with
+  what you attempted and how each attempt failed, and it forbids `--workaround`.
+  It does not mean the workaround was unpleasant.
+
+Add whichever of these you actually have: `error` (the error's message line,
+verbatim), `repro` (the shortest way to reach it again), `proposal`, `area`,
+`surface`, `cost` (measured if you measured it — "98s vs 20s steady" ranks;
+"slow" does not), `run` (an id shared by every finding from this build),
+`deployTarget`.
+
+Versions, platform and package manager are read off the installed tree for you.
+Do not pass them and do not ask the user for them.
+
+## When it cannot send
+
+Reporting never fails a build. A finding that cannot be sent — logged out, or
+fabric unreachable — is held on the machine and goes out with the next report
+that succeeds, so nothing you file is lost:
+
+- `pikku fabric findings list` shows what is queued.
+- `pikku fabric findings flush` sends everything queued.
+- `pikku fabric findings clear` discards it.
+
+If the terminal says the finding was queued, carry on with what you were doing.
+Do not try to fix the send, and do not file the same thing again.
+
+## Never fix pikku itself
+
+Not a patch in `node_modules`, not a linked checkout, not a branch in the
+framework repo. Many agents each patching pikku to unblock themselves is many
+divergent copies and a merge problem nobody signed up for. Work around it in the
+app, report it, and let the fix happen once.
+
+## What NOT to do
+
+- **Do not report a bug in the app as a pikku finding.** If the app's own code
+  is wrong, fix it; a finding that turns out to be the caller's mistake costs
+  the maintainers more than it cost you.
+- **Do not batch findings at the end of a build.** You will have lost the
+  mechanism and the command, and the report wins nothing.
+- **Do not file without a workaround or an `--unresolved --tried`.** A finding
+  that cannot be acted on is noise.
+- **Do not paste a secret, token or customer data into a finding.** The payload
+  leaves your machine; keep it to the mechanism.
+- **Do not ask the user for versions or platform.** They are collected
+  automatically.