@pikku/skills 0.12.52 → 0.12.55

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

@@ -1,190 +1,139 @@
 # 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.
 
-Nothing in the open-source toolchain authors a theme for you. Fabric has the
-`fabric-theme` tool; without it, hand-authoring is the route, and it is a small
+Nothing in the open-source toolchain authors a theme for you. A hosting
+platform may offer a theme tool; without it, hand-authoring is the route, and it is a small
 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,7 +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.'
-installGroups: [fabric]
+description: 'Work a project''s changes queue — the todo list someone filed by circling things in the running app. 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 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.'
 ---
 
 # Working a changes queue
@@ -11,8 +10,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
@@ -45,7 +43,7 @@ something changed. `wait` does the waiting and exits only when there is work.
    | ---- | ------------------------------------------------------ | ----------------------------------------------- |
    | 0    | work printed (claimed, and/or `Answered`)              | work it, then step 3                            |
    | 2    | `--timeout`/`--once` found nothing                     | stop, or restart `wait`                         |
-   | 3    | session refused                                        | tell the user to run `pikku fabric login`; stop |
+   | 3    | auth refused                                           | relay the CLI's message; stop                   |
    | 1    | anything else                                          | report the message; stop                        |
 
 3. For each item: `show` → fix → commit → `done`; or `ask` and move on; or `reply`
@@ -104,8 +102,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,8 +182,7 @@ 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.
-
-Registering writes with Fabric needs the `changes:project:write` scope.

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.
 
@@ -67,7 +65,7 @@ which is what decides whether a thrown error becomes a 409 or a 500.
 
 - **Worked examples are sparse.** Most exports show a signature and keys, not usage.
 - **`pikkuFunc` lists keys that belong elsewhere.** `before`, `after`, `skip`, `surfaces` and
-  `requiresActor` apply only to scenarios; `workflowQueued`, `workflowRetries` and
+  `requiresVirtualUser` apply only to scenarios; `workflowQueued`, `workflowRetries` and
   `workflowTimeout` only to a workflow step. One shared config type offers all of them to
   every function — each key says which it belongs to.
 
@@ -98,35 +96,34 @@ flags; the "Read" column is the skill that teaches the thing, where one does.
 
 **Running**
 
-| Command                      | What it does                                                                   | Read                                    |
-| ---------------------------- | ------------------------------------------------------------------------------ | --------------------------------------- |
-| `dev`                        | Local dev server, all services wired, watch + HMR                              | `pikku-build`                           |
-| `serve`                      | Bundled bun/node runner — no watch, no codegen                                 | `pikku-deploy`                          |
-| `watch`                      | Regenerate on file change, without a server                                    | —                                       |
-| `scenario list\|run`         | Scenarios as e2e tests and health checks                                       | `pikku-scenario`                        |
-| `persona run`                | A declared persona as a model-driven virtual user against a stage              | `pikku-scenario`, persona-run reference |
-| `persona list\|sync\|secret` | Who is declared; what an environment will provision; minting their credentials | `pikku-scenario`, persona-run reference |
-| `db`                         | Local development database                                                     | `pikku-kysely`                          |
+| Command                           | What it does                                                                   | Read                                         |
+| --------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------- |
+| `dev`                             | Local dev server, all services wired, watch + HMR                              | `pikku-build`                                |
+| `serve`                           | Bundled bun/node runner — no watch, no codegen                                 | `pikku-deploy`                               |
+| `watch`                           | Regenerate on file change, without a server                                    | —                                            |
+| `scenario list\|run`              | Scenarios as e2e tests and health checks                                       | `pikku-scenario`                             |
+| `virtual-user run`                | A declared virtual user, model-driven, against a stage                         | `pikku-scenario`, virtual-user-run reference |
+| `virtual-user list\|sync\|secret` | Who is declared; what an environment will provision; minting their credentials | `pikku-scenario`, virtual-user-run reference |
+| `db`                              | Local development database                                                     | `pikku-kysely`                               |
 
 **Inspecting and evolving**
 
-| Command               | What it does                                                            | Read                         |
-| --------------------- | ----------------------------------------------------------------------- | ---------------------------- |
-| `doc`                 | The installed API surface                                               | this skill                   |
-| `meta` / `info`       | What the project declares, machine- and human-readable                  | `pikku-meta`                 |
-| `validate`            | Every check that applies — app structure, an addon's published file set | `pikku-build`, `pikku-addon` |
-| `versions` / `release` | Contract hashes, breaking-change detection, versioned releases        | `pikku-meta`                 |
-| `audit` / `update`    | Advisories; which `@pikku/*` can move and what peers that needs         | `pikku-meta`                 |
-| `scopes` / `roles`    | Declared authorization scopes; roles from `defineSystemRole`            | `pikku-auth`                 |
-| `knowledge`           | The knowledge base — what this app is, in its users' language           | `pikku-knowledge`            |
-| `emails`              | Email template generation                                               | `pikku-emails`               |
+| Command                | What it does                                                            | Read                         |
+| ---------------------- | ----------------------------------------------------------------------- | ---------------------------- |
+| `doc`                  | The installed API surface                                               | this skill                   |
+| `meta` / `info`        | What the project declares, machine- and human-readable                  | `pikku-meta`                 |
+| `validate`             | Every check that applies — app structure, an addon's published file set | `pikku-build`, `pikku-addon` |
+| `versions` / `release` | Contract hashes, breaking-change detection, versioned releases          | `pikku-meta`                 |
+| `audit` / `update`     | Advisories; which `@pikku/*` can move and what peers that needs         | `pikku-meta`                 |
+| `scopes` / `roles`     | Declared authorization scopes; roles from `defineSystemRole`            | `pikku-auth`                 |
+| `knowledge`            | The knowledge base — what this app is, in its users' language           | `pikku-knowledge`            |
+| `emails`               | Email template generation                                               | `pikku-emails`               |
 
 **Shipping, and the CLI itself**
 
 | Command                       | What it does                                                                                                                                   | Read           |
 | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
 | `deploy`                      | Deploy to cloud infrastructure                                                                                                                 | `pikku-deploy` |
-| `fabric`                      | PikkuFabric: login, link, deploy, domains, secrets, logs                                                                                       | `pikku-fabric` |
 | `binary`                      | Compile an entrypoint to a native binary (`bun build --compile`)                                                                               | —              |
 | `dist`                        | Copy what `tsc` cannot emit — `.gen.json` meta, hand-authored `.d.ts` — into the build output. Run it after `tsc`, as a package's build script | —              |
 | `login` / `logout` / `whoami` | The CLI's session against a pikku server                                                                                                       | —              |
@@ -148,7 +145,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 +159,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
@@ -298,7 +297,7 @@ a Workers or serverless stage needs done belongs on the request path that needs
 where Pikku is embedded in a server you own. Lifecycle hooks do not run on this path; do the
 startup work in the entrypoint.
 
-`pikku validate` warns when a project starts a server by hand *and* depends on no runtime adapter,
+`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter,
 because that means the first path was available and unused.
 
 **`references/bootstrap.md`** has both entrypoints in full.
@@ -353,25 +352,25 @@ 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                                     |
-| --------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- |
-| **Identifiers** | Function, component, type and file names; tables and columns; commit messages | Nothing. **Always English.** There is no setting |
-| **Meta**        | Prose authored inside the code — `description`, `title`, step `template`      | `metaLocale` in `pikku.config.json` (default `en`) |
+| Axis            | Covers                                                                        | Decided by                                                    |
+| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; tables and columns; commit messages | Nothing. **Always English.** There is no setting              |
+| **Meta**        | Prose authored inside the code — `description`, `title`, step `template`      | `metaLocale` in `pikku.config.json` (default `en`)            |
 | **Product UI**  | Every string the app shows a user                                             | `messages/<locale>.json`, and `active.json`'s `defaultLocale` |
 
 Identifiers are the surface every other tool binds to — the generated clients, the RPC map a
 scenario is typed over, the SQL types — and unlike a string an identifier cannot be translated
 later: renaming one is a migration. `metaLocale` exists so a team can read their own Console in
 their own language; it is not licence to rename anything. And `baseLocale` in
-`project.inlang/settings.json` stays `en`, because it names the message *source* every other
+`project.inlang/settings.json` stays `en`, because it names the message _source_ every other
 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 +407,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-concepts/references/language.md

@@ -5,11 +5,11 @@ Three different things in a Pikku project have a human language, and they are
 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. |
+| 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/virtual-user 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
 
@@ -19,7 +19,7 @@ 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
+`pikku meta`, the RPC map a scenario's `virtualUser.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

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/nextjs.md

@@ -88,7 +88,7 @@ route definitions.
 
 - **`PikkuNextJSWorkerRPC({ fetcher })`** — same surface as `PikkuNextJS`, but
   every call is dispatched through a `Fetcher` (a Cloudflare service binding, a
-  local HTTP client, a fabric dispatcher) instead of loading function code
+  local HTTP client, a dispatcher worker) instead of loading function code
   in-process. Use it to keep functions out of the SSR bundle. A non-2xx response
   throws with the status and body text.
 - **`toNextJsAuthHandler(auth)`** — wraps a better-auth instance or handler