@pikku/skills 0.12.52 → 0.12.54

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

@@ -1,5 +1,15 @@
 # Build an app on Pikku, fast
 
+## Contents
+
+- Agent Operating Procedure
+- 1. One question, then build
+- 2. Personas — 60 seconds, not optional
+- 3. Build
+- 4. Look at it — actually
+- 5. One smoke scenario
+- 6. Hand it over honestly
+
 You have a scaffolded project with skills installed. Get it to working, seeded,
 signed-in screens in as few steps as possible.
 
@@ -42,7 +52,7 @@ Identifiers are English in every project, whatever the product's market;
 `template`, which the Console renders) stays `en` unless the user already told
 you otherwise. If the request says the app's UI is not English, that is the
 message catalogue only: add the locale and set `defaultLocale`, and leave
-`baseLocale` at `en`. `references/app.md` §1a has the three axes in full; getting
+`baseLocale` at `en`. the app workflow's §1a has the three axes in full; getting
 them confused is how a project ends up unable to add a second language.
 
 ## 2. Personas — 60 seconds, not optional
@@ -186,7 +196,7 @@ taller than the viewport. It is the most likely width your demo gets opened at.
 If you have five spare minutes, `npx impeccable install` (Node 22.18+) scores
 each screen against interaction heuristics and names what is wrong. Feed it
 screenshots, not source. It will polish the default look; it will not give the
-app a look — that is `references/app.md` §8a.
+app a look — that is the app workflow's §8a.
 
 ## 5. One smoke scenario
 
@@ -230,7 +240,7 @@ it is seeded with, and that this is a quick build — no knowledge base, no
 changesets, no design pass, access control clicked-through rather than proven.
 
 **Upgrading to a real build is additive, not a rewrite.** If they want it, switch
-to `references/app.md` and do this, in order:
+to the app workflow (the app reference, see SKILL.md) and do this, in order:
 
 1. Write `knowledge/` for what already exists — `entities/` for what you built,
    `decisions/` for what you chose silently, `questions/` for what you guessed
@@ -239,7 +249,7 @@ to `references/app.md` and do this, in order:
    gaps` has something to measure against.
 3. Write the refusal scenarios — the ones proving one persona cannot reach
    another's rows. This is the gap that matters most.
-4. Then pick up `references/app.md` at its §4 (apps) or §5 (changes) for
+4. Then pick up the app workflow at its §4 (apps) or §5 (changes) for
    anything new.
 
 Nothing built here has to be thrown away to do that — which is the whole reason

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

@@ -1,5 +1,16 @@
 # Scenarios — writing journeys that stay proven
 
+## Contents
+
+- The shape of a scenario
+- Extraction: what survives, and what silently does not
+- What to assert
+- There is no state reset
+- Steps rot as the app grows
+- Browser scenarios
+- Running them
+- Coverage — which functions have actually been run
+
 A scenario is a user journey run as one of your personas, over the real transport, with that
 persona's session. It is the only kind of test worth writing here, because a passing one proves the
 app works the way a signed-in person experiences it.
@@ -59,7 +70,7 @@ export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
 (server-side by default, plus a `browser` one that drives the page). Reaching for an RPC name in a
 `then` will not resolve.
 
-**`SCENARIO_ACTOR_SECRET` must be in `.env`** (app.md §6, before the first run). Without it
+**`SCENARIO_ACTOR_SECRET` must be in `.env`** (the app workflow's §6, before the first run). Without it
 `/api/auth/sign-in/actor` is disabled — every scenario then fails at sign-in, before its first step,
 for a reason that reads like an auth bug. `pikku scenario run` reads it from the environment, so
 source `.env` first (`set -a && . ./.env && set +a`) when you run outside `bun run dev`.

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

@@ -1,5 +1,10 @@
 # Shipping, and staying Fabric-ready
 
+## Contents
+
+- Ship it — open source, no platform
+- Staying Fabric-ready
+
 Read this when the changes queue is empty and the scenarios are green — it is
 the last phase, and nothing in it is needed before then.
 
@@ -114,7 +119,7 @@ one hostname, first-party cookies — give its `frontends` entry `"serve": {}`
 and a standalone deploy then mount its built `dist`. Pikku never builds it, so
 build the frontend first. Only one entry may set `serve`.
 
-To ship an app as a desktop or Android app, read `references/native-app.md`.
+To ship an app as a desktop or Android app, read the native-app reference (see SKILL.md).
 
 Before shipping, run the full gate:
 

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

@@ -1,5 +1,12 @@
 # Authoring the theme
 
+## Contents
+
+- Where the look lives
+- The colours the theme has no token for
+- Choose the neutrals; do not inherit them
+- If the user gave you no direction
+
 Read this at the design step, once you have a direction to turn into a theme —
 whether the user described one in words, handed you a reference, or ran their own
 design step whose output you are implementing.
@@ -11,180 +18,122 @@ job done in JSON.
 ## Where the look lives
 
 ```
-packages/mantine-theme/
+packages/theme/
   themes/
     default.json     # "Neutral" — the shipped scaffold
-    index.ts         # registers each theme JSON by id
   active.json        # { "id": "default" } — which one is live
-  index.ts
+  theme.css          # generated from the active spec — do not edit
 ```
 
 Each theme JSON has two halves — `brand` (colours, fonts) and `structure`
-(radius, shadows, spacing, per-component `defaultProps`). To give the product an
-identity, add `themes/<name>.json`, register it in `themes/index.ts`, and point
-`active.json` at its id.
-
-`themes/index.ts` carries a `Generated by the fabric-theme tool — do not edit by
-hand` banner. **That instruction is about Fabric's generator, not about you.**
-Without that tool, hand-authoring is the only route, and the file is a three-line
-registry. Edit it, and replace the banner with a line saying the themes here are
-hand-authored — otherwise the next agent reads the warning and leaves the app on
-Neutral.
+(radius, density, default colour scheme). To give the product an identity, add
+`themes/<name>.json`, point `active.json` at its id, and regenerate theme.css.
+That regenerates `theme.css`, which defines the shadcn tokens (`--background`,
+`--card`, `--border`, `--primary`, `--chart-1` to `--chart-5`, `--radius`) for
+both the light scheme and the `.dark` class.
 
 Turning §1's answer into a theme:
 
-- **Colour before anything else.** `brand.colors.primary` plus
-  `structure.primaryShade` and `autoContrast` carry most of the identity;
-  `@mantine/colors-generator` (already a dependency) expands one hex into a full
-  scale.
+- **Colour before anything else.** `brand.colors.primary` carries most of the
+  identity; the neutrals, borders and chart colours are derived from its hue.
 - **Fonts are the other half of the register**, and the half people skip. A serif
   heading font against a neutral body is a different product from the system
   stack, and it is one field.
-- **`structure.radius` and `structure.shadows` set the temperature.** Sharp
-  corners and flat surfaces read technical; large radii and soft shadows read
-  consumer. Neutral's `md: 10px` is the middle of the road on purpose.
-- **`structure.components` defaultProps is where a design decision becomes
-  automatic** — `Card` with `withBorder` everywhere, `NavLink` as `light`. Put
-  the repeated decision here rather than on every instance.
-- **`defaultColorScheme` and `darkColors` are a real choice**, not a toggle to
-  leave alone. A tool people live in all day is often better dark by default.
+- **`structure.radius` sets the temperature.** Sharp corners read technical;
+  large radii read consumer. Neutral's `md` is the middle of the road on purpose.
+- **`defaultColorScheme` is a real choice**, not a toggle to leave alone. A tool
+  people live in all day is often better dark by default.
 
 Then **write the direction into `knowledge/decisions/design/`** — the words the
 user gave you, what you chose, and what it rules out. The JSON records what the
 theme is; only the note records why.
 
-## The colours the theme has no field for
+## The colours the theme has no token for
 
 `brand` is the product's accent. It is not the only colour a screen needs, and
 the missing ones are why "don't hardcode colours per component" gets broken by
 the same agent that wrote it down.
 
-A screen has to say *covered* and *still open*, *fine* and *needs attention* —
+A screen has to say _covered_ and _still open_, _fine_ and _needs attention_ —
 and those are not the accent. Using the accent for them is worse than a stray
 hex: the brand colour stops meaning "this product" and starts meaning "good", so
 it means nothing. But there is no `brand.covered` field, so the value lands
 inline as `#3f7d5c`, once per component, slightly different each time.
 
-Give them a home. A small stylesheet of custom properties, imported once beside
-the Mantine styles, is enough:
+Give them a home. A small stylesheet of custom properties, imported once after
+`theme.css`, exposed to Tailwind through `@theme inline`, is enough:
 
 ```css
-:root:root:root {
-  --app-covered: #3f7d5c;  --app-covered-bg: #e6f1ea;
-  --app-open:    #a8701a;  --app-open-bg:    #fbeedb;
-  --app-sunk:    #fdf7f4;   /* a recessed surface, for forms and asides */
-  --app-hairline: #ecdfd9;  /* NOT var(--mantine-color-gray-2) — see below */
+:root {
+  --covered: #3f7d5c;
+  --covered-bg: #e6f1ea;
+  --open: #a8701a;
+  --open-bg: #fbeedb;
+  --sunk: #fdf7f4;
 }
-:root:root[data-mantine-color-scheme='dark'] {
-  --app-covered: #7fc09a;  --app-covered-bg: #1e2f26;
-  --app-open:    #e0ab5c;  --app-open-bg:    #33271a;
-  --app-sunk:    #241b18;
-  --app-hairline: #392b26;
+.dark {
+  --covered: #7fc09a;
+  --covered-bg: #1e2f26;
+  --open: #e0ab5c;
+  --open-bg: #33271a;
+  --sunk: #241b18;
+}
+@theme inline {
+  --color-covered: var(--covered);
+  --color-covered-bg: var(--covered-bg);
+  --color-open: var(--open);
+  --color-open-bg: var(--open-bg);
+  --color-sunk: var(--sunk);
 }
 ```
 
 Those values are one app's warm direction, not a palette to copy — derive your
-own from yours.
+own from yours. Components then say `bg-covered-bg text-covered`.
 
 ## Choose the neutrals; do not inherit them
 
-The two details in that snippet that look like typos are the two things most
-likely to make your app look like every other app.
-
-**The hairline is a literal, not `var(--mantine-color-gray-2)`.** Mantine's grey
-ramp is blue-biased — `#f8f9fa`, `#dee2e6`, `#868e96` are all cool — and it is
-what draws card borders, dividers, the shell's edges and every disabled control.
-The theme JSON has `brand` and `structure` and **no neutral field at all**, so
-unless you choose otherwise, every app built from this skill runs its accent on
-somebody else's greys.
-
-If the accent is not itself blue, that mismatch lands on every screen at once:
-warm content ruled off in cold lines, off everywhere and wrong nowhere in
-particular, which is the hardest kind of wrong to find. It survives a careful
-critique because no single screen is broken.
-
-So bias the whole ramp toward the accent — not just the tokens with obvious
-names. Keep Mantine's lightness steps so contrast behaviour and every component
-that picks a step by number are unchanged; move only the hue:
-
-```css
-/* The ramps: hue only. Mantine picks a step by number in either scheme, so
-   these are scheme-independent and belong in the unscoped block. */
-:root:root:root {
-  --mantine-color-gray-0: #faf7f5;  --mantine-color-gray-5: #b8a49d;
-  --mantine-color-gray-1: #f5efec;  --mantine-color-gray-6: #93807a;
-  --mantine-color-gray-2: #efe6e2;  --mantine-color-gray-7: #574a45;
-  --mantine-color-gray-3: #e6dad5;  --mantine-color-gray-8: #3d332f;
-  --mantine-color-gray-4: #d8c8c2;  --mantine-color-gray-9: #2a1f1b;
-  --mantine-color-dark-0: #f3e9e4;  --mantine-color-dark-5: #4a3a34;
-  --mantine-color-dark-1: #cdbdb6;  --mantine-color-dark-6: #392b26;
-  --mantine-color-dark-2: #a8938c;  --mantine-color-dark-7: #241b18;
-  --mantine-color-dark-3: #7a655e;  --mantine-color-dark-8: #1b1512;
-  --mantine-color-dark-4: #5c4a44;  --mantine-color-dark-9: #120d0b;
-}
-
-/* Ground, text and border are a different colour in each scheme, so each one
-   is set in the scheme it belongs to. A scheme-dependent token left in the
-   block above is the classic unreadable-in-dark bug. */
-:root:root:root[data-mantine-color-scheme='light'] {
-  --mantine-color-body: #fdfaf8;
-  --mantine-color-text: #2a1f1b;
-  --mantine-color-default-border: #ecdfd9;
-  --mantine-color-dimmed: #7a625c;      /* keep AA: ~5.4:1 on the body above */
-  --mantine-color-placeholder: #826a64; /* ~4.8:1 */
-}
-:root:root:root[data-mantine-color-scheme='dark'] {
-  --mantine-color-body: #1b1512;
-  --mantine-color-text: #f3e9e4;
-  --mantine-color-default-border: #392b26;
-  --mantine-color-dimmed: #a8938c;      /* ~5.6:1 on the body above */
-  --mantine-color-placeholder: #8c7a74; /* ~4.7:1 */
-}
-```
-
-Check the four text tokens against your own grounds rather than copying these —
-`dimmed` is the most-used text colour in the app and the easiest to drop below
-4.5:1 while making it prettier, and it has to clear the bar on *both* grounds.
-
-**The selector is tripled on purpose.** Mantine's `cssVariablesResolver` injects
-its own `:root` block into `<head>` at runtime, which lands *after* your
-stylesheet and wins on source order at equal specificity. A plain `:root` here is
-silently reverted: the file reads correct, the app renders Mantine's defaults,
-and nothing errors. Repeating the pseudo-class raises specificity without adding
-an element to the selector.
-
-This one costs a whole pass if you meet it without knowing: you diagnose the
-colours correctly, write the right values, reload, and see no change — so you
-assume the diagnosis was wrong. **The only thing that catches it is looking at a
-screenshot and disbelieving the CSS.**
-
-Name them for what they *mean* in this product, never for the colour — `covered`,
-not `green`. The name is the whole value: it survives a change of palette, and it
-is the thing that makes the second use agree with the first. Define both colour
-schemes at once; a token defined only in light is the classic unreadable-in-dark
-bug, and Mantine will happily render it.
+The theme generator derives the neutrals from the primary's hue, so the greys
+already lean toward the accent. That only holds if the primary is chosen first:
+change `brand.colors.primary`, regenerate theme.css, and look at a card
+border against the page, because it is the neutrals that draw card borders,
+dividers, the shell's edges and every disabled control.
+
+If the accent is not blue and the greys still read cold, the mismatch lands on
+every screen at once: warm content ruled off in cold lines, off everywhere and
+wrong nowhere in particular, which is the hardest kind of wrong to find. It
+survives a careful critique because no single screen is broken. Fix it in
+`theme.css` inputs, not by overriding `border-gray-200` per component.
+
+Check the text tokens against your own grounds rather than trusting them —
+`--muted-foreground` is the most-used secondary text colour in the app and the
+easiest to drop below 4.5:1 while making it prettier, and it has to clear the bar
+on _both_ the light and `.dark` grounds.
+
+Name the extra tokens for what they _mean_ in this product, never for the colour
+— `covered`, not `green`. The name is the whole value: it survives a change of
+palette, and it is the thing that makes the second use agree with the first.
+Define both colour schemes at once; a token defined only in light is the classic
+unreadable-in-dark bug.
 
 The same file is where a couple of other things belong that the theme JSON has no
-field for and every screen otherwise re-invents: the hairline that separates rows
-in a list, the recessed surface a form sits on so it does not carry the same
-weight as the content it adds to, and the one animation the product is allowed
-(behind `prefers-reduced-motion`). Two or three rules, not a framework.
+field for and every screen otherwise re-invents: the recessed surface a form sits
+on so it does not carry the same weight as the content it adds to, and the one
+animation the product is allowed (behind `prefers-reduced-motion`). Two or three
+rules, not a framework.
 
 If the app ships template screens you did not write — the error and not-found
-pages usually — read them before you call the palette done. They arrive with the
-scaffold's colours hardcoded, and a stock blue accent on an app whose direction
-says warm is the single loudest contradiction in the build.
+pages usually — read them before you call the palette done. A stock accent on an
+app whose direction says warm is the single loudest contradiction in the build.
 
 **Set the theme once, don't hardcode colours per component.** A screen full of
-inline `color="blue"` and one-off hex values is why apps look templated. Change
-the theme, not the components — and keep it theme-aware for light and dark.
+inline hex values and `bg-blue-500` is why apps look templated. Change the theme,
+not the components — and keep it theme-aware for light and dark.
 
 With two apps, **share the theme package and vary the register, not the
 palette.** A back-office can be denser and more tabular; a customer-facing app
 can be roomier and warmer — that is `structure` and layout, not a second `brand`.
 Two unrelated colour schemes read as two products from two companies.
 
-
 ## If the user gave you no direction
 
 Neutral is a legitimate answer for an internal tool. But say so out loud when you

package/skills/pikku-changes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-changes
-description: 'Work a project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku changes wait|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against <stage>", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
+description: 'Work a project''s changes queue — the todo list someone filed by circling things on a deployed stage. Covers `pikku changes wait|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the pikkufabric changes", "run the changes against a stage", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
 installGroups: [fabric]
 ---
 
@@ -11,8 +11,7 @@ screenshot of what they saw, and the elements the circle enclosed. You have the
 Empty the queue without making them regret filing.
 
 Run every command from the checkout. The queue lives in it (`.git/pikku-changes.json`, shared by every
-worktree).
-`--json` works on all of them. Items are addressed as `2`, `#2` or their uuid.
+worktree). `--json` works on all of them. Items are addressed as `2`, `#2` or their uuid.
 
 **Launched by `pikku changes next`?** `pikku changes next` picks one agent: a merge conflict or a changeset with no plan
 goes back to a changes agent; open changes go to a changes agent; a pikku version bump goes to an
@@ -104,8 +103,8 @@ changeset declared no `--creates`/`--alters`.
 
 When other agents are working changesets at the same time (your work says so), claim with
 `--worktree`: it creates `changeset/<slug>` in its own checkout beside the repo and prints the path.
-Build and commit there and run `done` there; the merge removes the worktree. If the claim is refused because of a running changeset, claim one that does not
-clash, or stop.
+Build and commit there and run `done` there; the merge removes the worktree. If the claim is refused
+because of a running changeset, claim one that does not clash, or stop.
 
 ## Reading an item
 
@@ -184,7 +183,8 @@ Scope names the screen they were looking at, not the file you edited.
 pikku changes done --change-id 7 --note "What you did, for whoever reads the thread"
 ```
 
-Branch and commit default to the checkout you are in — run it there, never type a sha. `done` finds the item's commit by its `Change-Id` trailer, so close items in any order.
+Branch and commit default to the checkout you are in — run it there, never type a sha. `done` finds
+the item's commit by its `Change-Id` trailer, so close items in any order.
 An item you decided not to do is not `done`: `reply` with why and leave it for a
 human to dismiss.
 

package/skills/pikku-concepts/SKILL.md

@@ -13,9 +13,7 @@ installGroups: [core]
 
 # Pikku Framework Concepts
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
+## Operating procedure
 
 1. Discover before editing. Run `pikku doc --ai` for the installed API surface, and the relevant `pikku meta ... --json` for what this project has wired.
 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.
@@ -43,7 +41,7 @@ that will work anyway.
 pikku doc --ai
 ```
 
-≈480 tokens, giving the 20 `#pikku/*` doors grouped by the job they do, and beside each the
+Prints the `#pikku/*` doors, grouped by the job they do, and beside each the
 skill that teaches it. Read that routing table as the index to every other pikku skill — it is
 generated from the installed version, so it never names a skill for a door that no longer exists.
 
@@ -148,7 +146,7 @@ pikkuFunc (pure business logic)
     ├── wireChannel     → WebSocket (real-time)
     ├── wireQueueWorker → BullMQ, PgBoss (async jobs)
     ├── wireScheduler   → Cron (scheduled tasks)
-    ├── wireMCPTool     → Model Context Protocol (AI tools)
+    ├── mcp: true       → Model Context Protocol (AI tools; an option on the function, no wire call)
     ├── wireCLI         → CLI commands
     ├── wireTrigger     → Event-driven (Redis pub/sub, PG LISTEN/NOTIFY)
     ├── pikkuAgent    → AI agents / chatbots
@@ -162,6 +160,8 @@ A `pikkuFunc` receives three things:
 2. **Data** — input from any source (HTTP body/query/params, WS message, queue payload, CLI args)
 3. **Wire** — transport context (session, channel, rpc, mcp, http, queue)
 
+**MCP tools:** always set `mcp: true` on the normal function; HTTP, RPC and agents can still call it. The one exception is wrapping an EXISTING function as an AI tool purely to reshape its data: use `pikkuMCPToolFunc` (calls the original via `rpc.invoke`), which makes the wrapper MCP-only. The alternative is a second normal function with `mcp: true`. See `pikku-wiring`.
+
 The function never imports Express, never reads `req.body`, never touches `ws.send()`. It just works with typed data and services.
 
 ## Concept Mapping: Generic Backend → Pikku
@@ -353,7 +353,7 @@ src/
 ## 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 has already shipped in a real product:
+language. Collapsing them is the common mistake:
 
 | Axis            | Covers                                                                        | Decided by                                     |
 | --------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- |
@@ -370,8 +370,8 @@ language is cloned from.
 
 **When a brief tells you the product speaks a language, it is telling you about the third axis and
 nothing else.** `references/language.md` has the three settings that satisfy such a brief, and the
-build that read one sentence about a product's users as an instruction about its codebase — German
-RPC names, German tables, and no English catalogue to ever translate from.
+failure to avoid: reading one sentence about a product's users as an instruction about its codebase
+(German RPC names, German tables, no English catalogue to translate from).
 
 ## Environment Variables
 
@@ -408,12 +408,3 @@ expect(result.todos).toHaveLength(3)
 ## Available Packages
 
 Pikku ships runtime adapters (`@pikku/express-server`, `@pikku/fastify-server`, `@pikku/next`, `@pikku/aws-lambda`, `@pikku/cloudflare`, `@pikku/uws-server`, `@pikku/modelcontextprotocol`, ...) and service packages (`@pikku/jose`, `@pikku/schema-ajv`, `@pikku/pino`, `@pikku/kysely`, `@pikku/redis`, `@pikku/queue-bullmq`, `@pikku/queue-pg-boss`, ...). For the full list with use cases, read `references/packages.md`.
-
-## Key Differences from Traditional Frameworks
-
-1. **No decorators** — plain functions + explicit wiring, not `@Get()` or `@Injectable()`
-2. **No classes required** — everything is functions and objects
-3. **Transport is configuration, not code** — business logic doesn't know about HTTP/WS/etc.
-4. **One function, many transports** — same function can serve HTTP, WebSocket, queue, and MCP simultaneously
-5. **Generated type safety** — clients are auto-generated with full types, not manually maintained
-6. **Schema-first validation** — Standard Schema (Zod/Valibot) replaces class-validator decorators

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

@@ -1,5 +1,23 @@
 # Concept Mapping: Generic Backend → Pikku
 
+## Contents
+
+- Quick Reference Table
+- Route Handler / Controller
+- Route Parameters
+- Middleware
+- Auth Guard
+- Authorization / Role Checks
+- DTO / Request Validation
+- Dependency Injection
+- WebSocket Handlers
+- Job Queue Workers
+- Cron / Scheduled Tasks
+- Module / Feature Grouping
+- Error Handling
+- Session Management
+- API Client Generation
+
 Authoritative mapping table plus side-by-side code examples showing how common backend patterns translate to Pikku.
 
 - [Quick Reference Table](#quick-reference-table)

package/skills/pikku-convert-screen/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: pikku-convert-screen
+description: Use when an old screen, page or feature (from an old console, another repo, screenshots, or a description) has to be rebuilt in the current app. Extracts what it does as plain business logic, with no layout or code detail, then designs it fresh in the current design system. TRIGGER on "convert this screen", "port the old console page", "we had this before, bring it back", "redesign X from the old console". DO NOT TRIGGER for whole-repo reverse engineering (use pikku-software-archaeology) or for restyling a screen that already exists in the app.
+installGroups: [core]
+---
+
+# Convert a screen
+
+Keep what the screen does. Drop how it looked and how it was built.
+
+## 1. Read the old thing
+
+Use whatever is given: a path, a repo, screenshots, a recording, a description. For code, read the page, its hooks, the RPCs or endpoints behind it and any tests. For images, read the labels and states, not the styling. Check whether the app already has it under another name before starting.
+
+## 2. Write the spec
+
+Save it as `docs/screens/<name>.md`. Business logic only.
+
+- Who uses it and what they are trying to get done.
+- What they can see, in the words a non-technical owner would use.
+- Every action: what triggers it, what must be true first, what changes, what the person is told afterwards.
+- Rules and limits: who may do it, what is refused and why.
+- States: empty, loading, working, done, failed. For each failure, what the person can do next.
+- Data it needs and which existing RPCs provide it. Mark any that are missing.
+- Things you were unsure of, marked as open questions. Never present a guess as fact.
+
+Leave out: component names, layout, colours, spacing, library names, file structure, modals versus drawers, table versus cards. If a sentence only makes sense by picturing the old UI, rewrite it.
+
+Stop and show the spec. Do not design until it is agreed.
+
+## 3. Build it in the current design system
+
+Design from the spec, not from the old screen. Never copy old markup or styles.
+
+- Read the project design system (`DESIGN.md`, theme tokens) and the nearest existing screens first. Match their header, spacing, buttons and wording.
+- Use the components the project already uses. No modal dialogs: forms go in the side panel or a new page.
+- Plain words. The client's own vocabulary, never internal jargon.
+- Every error says what happened in plain terms and offers a way out, with an AI fix where it makes sense.
+- No static data. The screen reads through RPC hooks only. Data a function does not return yet comes from `.mocks/` through the stub hooks (see the pikku-build skill, mocks reference), with a populated, an empty and an error scenario.
+- The same component serves every data state: real, mocked or stubbed.
+- Add the route and a rail entry only where the spec says people reach it.
+
+## 4. Check against the spec
+
+Walk the spec line by line against the running screen, including the empty and failed states. Say which lines are met, which are not, and which depend on RPCs that do not exist yet. Capture a screenshot from the running screen.

package/skills/pikku-deploy/references/cloudflare.md

@@ -1,5 +1,13 @@
 # Cloudflare Workers
 
+## Contents
+
+- Worker entry
+- Service setup — do not hand-roll this
+- HTTP
+- Scheduled tasks
+- WebSocket (Durable Objects)
+
 ```bash
 yarn add @pikku/cloudflare
 ```

package/skills/pikku-deploy/references/lambda.md

@@ -1,5 +1,13 @@
 # AWS Lambda
 
+## Contents
+
+- Cold start pattern
+- HTTP handler
+- Scheduled tasks
+- SQS queue worker
+- WebSocket (API Gateway v2)
+
 ```bash
 yarn add @pikku/lambda
 ```

package/skills/pikku-deploy/references/uws.md

@@ -69,4 +69,4 @@ app.ws('/*', pikkuWebsocketHandler({ logger, logRoutes: true }))
 
 Both take `{ logger, logRoutes?, loadSchemas? } & RunHTTPWiringOptions`.
 
-For a WebSocket-only server on the `ws` library instead, see `ws.md`.
+For a WebSocket-only server on the `ws` library instead, use the `ws` runtime.

package/skills/pikku-deploy/references/ws.md

@@ -2,9 +2,9 @@
 
 `@pikku/ws` connects Pikku's channel system to a Node.js WebSocket server built
 on the [ws](https://github.com/websockets/ws) library. Use it for a
-WebSocket-only server; for HTTP and WebSocket on one port see `uws.md`, and when
-the WebSocket server shares a port with an existing HTTP app see `express.md` or
-`fastify.md`.
+WebSocket-only server; for HTTP and WebSocket on one port use the uWebSockets.js runtime, and when
+the WebSocket server shares a port with an existing HTTP app use the Express or
+Fastify runtime.
 
 ```bash
 yarn add @pikku/ws ws

package/skills/pikku-emails/SKILL.md

@@ -1,15 +1,9 @@
 ---
 name: pikku-emails
 description: >-
-  Use when working with Pikku's file-based email templates: authoring HTML/subject/text templates,
-  locales, partials and theme, running `pikku emails generate`, and rendering/sending them through
-  an EmailService. TRIGGER when: code uses renderEmailTemplate, EmailTemplateName, EmailService,
-  SendTemplateEmailInput, LocalEmailService, or imports from .pikku/email/pikku-emails.gen.
-  TRIGGER when: the project has an emails/ directory (templates/, locales/, partials/, theme.json)
-  or emailTemplatesDir in pikku.config.json. TRIGGER when: user asks to add/edit a transactional
-  email (verification, password reset, invitation, receipt), wire email sending, or translate an
-  email. DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows
-  in general (use pikku-auth).
+  Use when working with Pikku's file-based email templates: authoring html, subject and text templates, locales, partials and theme, running `pikku emails generate`, and rendering and sending them through an EmailService.
+  TRIGGER when: code uses renderEmailTemplate, EmailTemplateName, EmailService, SendTemplateEmailInput or LocalEmailService, or imports from .pikku/email/pikku-emails.gen; the project has an emails/ directory (templates/, locales/, partials/, theme.json) or emailTemplatesDir in pikku.config.json; or the user asks to add, edit or translate a transactional email (verification, password reset, invitation, receipt) or wire email sending.
+  DO NOT TRIGGER when: the task is i18n for the app UI (use pikku-i18n) or sign-in flows in general (use pikku-auth).
 installGroups: [core]
 ---