@pikku/skills 0.12.52 → 0.12.55

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]
 ---
 

package/skills/pikku-guide/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: pikku-guide
 description: >-
-  Use when writing, rewriting 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, one section per task, each followed by a `<!-- pikku:guide feature=… scenario=… -->`
-  marker that pulls in the screenshot and recording that scenario filed. Covers planning pages
-  from the suite, writing task prose in the app's language, per-section markers, the capture step,
-  seed data that appears on camera, `.guide.lock` staleness, `document: false`, and the traps that
-  make a guide come out empty, refused, or as a wall of videos. TRIGGER when: user asks for a user
-  guide, help pages, docs with screenshots, "document the app", or complains that the /docs pages
-  are bad, thin, or all videos. DO NOT TRIGGER when: user asks about API reference docs, README
-  files, or writing the scenarios themselves (use pikku-scenario).
+  Use when writing, rewriting or regenerating a Pikku project's end-user guide, built from the
+  scenario suite with `pikku scenario guide`. Pages are hand-written markdown, one section per
+  task, each followed by a `pikku:guide` HTML-comment marker (feature and scenario attributes) that
+  pulls in the screenshot and recording that scenario filed. Covers planning pages from the suite,
+  writing task prose in the app's language, per-section markers, the capture step, seed data that
+  appears on camera, `.guide.lock` staleness, `document: false`, and the traps that make a guide
+  come out empty, refused, or as a wall of videos. TRIGGER when: user asks for a user guide, help
+  pages, docs with screenshots, "document the app", or complains that the /docs pages are bad,
+  thin, or all videos. DO NOT TRIGGER when: user asks about API reference docs, README files, the
+  Pikku framework's own documentation site, or writing the scenarios themselves (use pikku-scenario).
 installGroups: [core]
 ---
 
@@ -20,11 +20,11 @@ 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.
 
-| 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** | you |
+| 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** | you       |
 
 **The run contributes pictures, never words.** Step sentences, scenario
 descriptions and feature names are written to prove a test; none of them
@@ -108,7 +108,7 @@ mechanical, and skipping it is how sections end up with no figure or with a
 figure of something else.
 
 1. **Inventory.** List every `pikkuFeature` and, under each, its scenarios with
-   their actor and the screen each one ends on. Read the scenario files, not
+   their virtual user and the screen each one ends on. Read the scenario files, not
    just the names.
 2. **Outline.** Group the scenarios into reader jobs (pages) and tasks
    (sections). A section is usually one scenario; two scenarios that show the
@@ -161,10 +161,10 @@ covers, or mark it `document: false`.
 
 Two strings from the suite reach the page as captions:
 
-| Figure | Caption |
-|---|---|
-| Screenshot | the `name` it was taken under |
-| Recording | the scenario's `title` (plus ` — ` and the actor, when there are several) |
+| Figure     | Caption                                                                        |
+| ---------- | ------------------------------------------------------------------------------ |
+| Screenshot | the `name` it was taken under                                                  |
+| Recording  | the scenario's `title` (plus `—` and the virtual user, when there are several) |
 
 Write both as a reader-facing caption in the app's language: "Die Buchung mit
 Status, Eckdaten und Reitern", "the course list, with places left on each
@@ -179,6 +179,7 @@ Every scenario a section cites should take one showcase screenshot of the state
 the section describes. Add the capture step once:
 
 ```ts snippet:guideCaptureStep
+
 ```
 
 - Without `path` it photographs the screen the flow is on. Call it **after the
@@ -194,11 +195,11 @@ the section describes. Add the capture step once:
 
 ### The camera sees your seed data
 
-Every figure shows whatever the scenario's personas and seed rows contain, so
+Every figure shows whatever the scenario's virtual users and seed rows contain, so
 they are part of the documentation:
 
-- A persona's display name is in the header of every shot. "Scenario Admin" or
-  "test-user-3" is on every page of the guide; give personas plausible names
+- A virtual user's display name is in the header of every shot. "Scenario Admin" or
+  "test-user-3" is on every page of the guide; give virtual users plausible names
   and roles.
 - Seed rows are the example data a reader sees: in the app's language, the
   shape real data takes — no lorem ipsum, no English description inside a
@@ -208,14 +209,14 @@ they are part of the documentation:
 ### Traps that make a figure missing or wrong
 
 - **RPC-only scenarios file no screenshot.** The command warns `whose run filed
-  no screenshot — the block renders empty`. Add a browser capture, or do not
+no screenshot — the block renders empty`. Add a browser capture, or do not
   cite that scenario.
 - **A capture loop must iterate a named const.** `for (const s of [ … ])` with
   an inline array literal cannot be extracted (PKU679) and the scenario is
   silently empty. `const screens = [ … ] as const`, then `for (const s of screens)`.
 - **A capture before an assertion moves the page from under it.** Capture last,
   or re-navigate.
-- **A redirect photographs the wrong screen.** A first-time actor bounced to
+- **A redirect photographs the wrong screen.** A first-time virtual user bounced to
   onboarding, a consent dialog, a login — the shot is named "the map" and shows
   something else. Finish the redirecting flow in the scenario first, and look
   at the image.
@@ -284,8 +285,8 @@ the second is clean. Commit the lock; never hand-edit or hand-merge it.
       language: why and when, numbered steps naming controls as they read,
       what you see, what goes wrong.
 - [ ] Captions (screenshot names, scenario titles) are reader copy — no routes,
-      sizes, test ids or actor names.
-- [ ] Personas and seed data on camera look like real use, in the app's
+      sizes, test ids or virtual user names.
+- [ ] Virtual users and seed data on camera look like real use, in the app's
       language.
 - [ ] Every feature is cited or `document: false`; no `--allow-undocumented`.
 - [ ] Built from a full, passing `--run browser --screenshots` run; no "block

package/skills/pikku-i18n/SKILL.md

@@ -2,9 +2,9 @@
 name: pikku-i18n
 description: >-
   Use when writing user-facing text in a Pikku frontend, or making one speak another language.
-  Covers Paraglide JS message functions compiled from messages/<locale>.json, adding a second
-  language, generated enum-label maps with @pikku/paraglide, and right-to-left support for Arabic,
-  Hebrew, Farsi and Urdu. TRIGGER when: scaffolding or editing a frontend and writing display
+  Covers Paraglide JS message functions compiled from per-locale messages JSON files, adding a second
+  language, generated enum-label maps with @pikku/paraglide, and right-to-left support (document direction, flow-relative
+  styles) for Arabic, Hebrew, Farsi and Urdu. TRIGGER when: scaffolding or editing a frontend and writing display
   text, asked to make copy translatable, adding a language, labelling an enum/status/role value,
   or asked to support RTL / mirror the layout. DO NOT TRIGGER for backend functions, error
   messages thrown from functions, or log output — none of those are display strings.
@@ -46,10 +46,10 @@ the app is in. Set `defaultLocale` instead.
 
 ## Direction is one setting, not per-component work
 
-Set `dir` once at the document root from the active locale and the browser (and
-Mantine) mirror everything — provided every custom style is flow-relative
-(`margin-inline-start`, `text-align: start`, Mantine `ms`/`me`) rather than
-physical (`margin-left`, `text-align: left`, `ml`/`me`'s physical twins). Write
+Set `dir` once at the document root from the active locale and the browser
+mirror everything — provided every custom style is flow-relative
+(`margin-inline-start`, `text-align: start`, Tailwind `ms-*`/`me-*`) rather than
+physical (`margin-left`, `text-align: left`, `ml-*`/`mr-*`). Write
 logical properties from the start even in an English-only app; that discipline
 is what makes an RTL language just another locale file.
 

package/skills/pikku-i18n/references/enum-labels.md

@@ -1,5 +1,14 @@
 # Pikku Paraglide enum labels
 
+## Contents
+
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [The rules that don't change](#the-rules-that-dont-change)
+- [The generated module](#the-generated-module)
+- [Reconciliation against the database](#reconciliation-against-the-database)
+- [Wiring](#wiring)
+- [What NOT to do](#what-not-to-do)
+
 ## Agent Operating Procedure
 
 Use this as an execution checklist, not reference material.

package/skills/pikku-i18n/references/messages.md

@@ -1,5 +1,18 @@
 # Pikku i18n (Paraglide JS)
 
+## Contents
+
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [The product's language is not the code's language](#the-products-language-is-not-the-codes-language)
+- [The moving parts (starter-template layout)](#the-moving-parts-starter-template-layout)
+- [Using messages in components](#using-messages-in-components)
+- [Keys only known at runtime (enum labels, status maps)](#keys-only-known-at-runtime-enum-labels-status-maps)
+- [Type safety — and why deploys block on i18n](#type-safety--and-why-deploys-block-on-i18n)
+- [Compile step](#compile-step)
+- [Adding a second language](#adding-a-second-language)
+- [i18n debug mode (find inlined strings)](#i18n-debug-mode-find-inlined-strings)
+- [What NOT to do](#what-not-to-do)
+
 ## Agent Operating Procedure
 
 Use this skill as an execution checklist, not reference material.
@@ -36,7 +49,7 @@ like it works, because the app does come up in that language, and then:
 - a message missing from a locale falls back to a catalogue nobody wrote
 
 The setting that actually decides what a first-time visitor sees is
-`defaultLocale`, held in `apps/app/src/i18n/active.json` in the Fabric app
+`defaultLocale`, held in `apps/app/src/i18n/active.json` in the app
 template and read by `src/i18n/config.ts`. It is deliberately a separate file
 from `settings.json` for exactly this reason — the source language and the
 served language are different questions.
@@ -54,12 +67,11 @@ So a German medical portal is **three** settings, not one:
 { "metaLocale": "de" }
 ```
 
-In the Fabric template both of the first two have a command, so you rarely edit
-them by hand:
+Edit the first two by hand:
 
 ```sh
-fabric i18n --add-locale de       # adds "de" to locales, seeds messages/de.json from en.json
-fabric i18n --default-locale de   # writes active.json — the app now OPENS in German
+# add "de" to locales and seed messages/de.json from en.json
+# set defaultLocale to "de" in active.json — the app now OPENS in German
 ```
 
 ### The failure this is written from
@@ -160,7 +172,7 @@ helper, stop — that helper IS the bug.
 
 A message IS a function: a typo'd or deleted key (`m.auth__login__titel()`) is a missing export — a **TypeScript error**, not a silent runtime fallback string. Params are typed too. The deploy pipeline compiles Paraglide then runs each frontend's `tsc` (`"tsc": "tsc --noEmit"` script — keep it in every frontend's `package.json`) **before** building; a type error aborts the deploy. `vite build` does not type-check on its own, so this gate is the only thing standing between a broken message and production.
 
-The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/mantine` `I18nNode` prop typing catches those: a raw string literal fails to compile on a gated prop, because `I18nString` is a branded type a bare `string` can't satisfy. Between the two, `tsc` is the whole safety net — there is no runtime fallback to inspect, by design.
+The gate catches _invalid_ messages but not _inlined_ strings. The starter template's `I18nNode` prop typing catches those: a raw string literal fails to compile on a gated prop, because `I18nString` is a branded type a bare `string` can't satisfy. Between the two, `tsc` is the whole safety net — there is no runtime fallback to inspect, by design.
 
 ## Compile step
 
@@ -177,11 +189,11 @@ The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/manti
 2. Add `"fr"` to `locales` in `project.inlang/settings.json`. **Leave `baseLocale` at `en`** — step 1 only works because there is an English catalogue to mirror.
 3. Recompile (restart/`vite dev` or the CLI compile). A locale file missing keys falls back to the base locale per message.
 4. Content is reachable via the `/<lang>` URL prefix (`detectLocale` already resolves it); the base locale needs no prefix. Expose the switcher via `useLocale().setLocale`.
-5. Only if the app should **open** in the new language rather than merely offer it: set `defaultLocale` (`active.json` / `fabric i18n --default-locale fr`). Adding a locale and changing the default are different asks — do the second only when asked.
+5. Only if the app should **open** in the new language rather than merely offer it: set `defaultLocale` (`active.json`). Adding a locale and changing the default are different asks — do the second only when asked.
 
 ## i18n debug mode (find inlined strings)
 
-`tsc` catches invalid messages, and the `@pikku/mantine` gate catches raw strings on gated props — but neither sees a hardcoded string in plain JSX, an `aria-label`, `alt`, `document.title`, or anything passed to a non-Mantine component. Debug mode covers that gap: render every message as block glyphs (`█`), and whatever is still readable never went through a message.
+`tsc` catches invalid messages, and the template's `I18nNode` gate catches raw strings on gated props — but neither sees a hardcoded string in plain JSX, an `aria-label`, `alt`, `document.title`, or anything passed to a component that does not gate its text. Debug mode covers that gap: render every message as block glyphs (`█`), and whatever is still readable never went through a message.
 
 **Build it as a generated locale, never as a runtime wrapper.** Masked text is text, and rendering different text per locale is what Paraglide already does:
 
@@ -207,7 +219,7 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 - Don't let a non-English UI reach the identifiers. Functions, components, types, files, tables and columns are English in every project; the product's language lives in `messages/*.json` and nowhere else.
 - Don't translate message **keys**. `auth__login__title` stays English in `de.json`; only the value changes.
 - Don't edit or commit anything under `src/paraglide/` — it's regenerated; change `messages/*.json` instead.
-- **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the `@pikku/mantine` `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
+- **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the template's `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
 
   `packages/console` is the one place in this repo that still wraps it, in `src/i18n/messages.ts`, to keep the debug mask (`█`) it carried over from i18next. That wrapper is a leftover, not a pattern — the generated-locale approach above is how a new app gets the same masking without touching every export. Don't copy it.
 

package/skills/pikku-i18n/references/rtl.md

@@ -1,5 +1,16 @@
 # Pikku RTL (Arabic + English)
 
+## Contents
+
+- [The one idea](#the-one-idea)
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [Flow-relative, not physical — the rules that make it mirror](#flow-relative-not-physical--the-rules-that-make-it-mirror)
+- [Applying direction at the root](#applying-direction-at-the-root)
+- [Directional icons — the manual bit](#directional-icons--the-manual-bit)
+- [Arabic typography niceties](#arabic-typography-niceties)
+- [Adding Arabic to an existing app — checklist](#adding-arabic-to-an-existing-app--checklist)
+- [What NOT to do](#what-not-to-do)
+
 This reference sits **on top of** `references/messages.md`. That one compiles a locale's
 messages into typed `m.*()` functions; this one adds the second axis: a locale
 also has a **direction**. Arabic is not special-cased — it is just another
@@ -9,7 +20,7 @@ being told it is `rtl`.
 ## The one idea
 
 Set `dir` **once at the document root** from the active locale, then let the
-browser and Mantine mirror everything — _provided_ every custom style is written
+browser mirror everything — _provided_ every custom style is written
 **flow-relative** (start/end), never **physical** (left/right). Get those two
 things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
 _layout_ code — directional icons still need one manual step, covered below.
@@ -51,14 +62,14 @@ Use the **inline-axis logical** property; never the physical one:
 | `border-top-left-radius`     | `border-start-start-radius`                  |
 | `float: left/right`          | `float: inline-start / inline-end`           |
 
-In **Mantine**, use the logical style props — they emit the logical CSS above:
+In **Tailwind**, use the logical utilities — they emit the logical CSS above:
 
 | Don't       | Do          |
 | ----------- | ----------- |
-| `ml` / `mr` | `ms` / `me` |
-| `pl` / `pr` | `ps` / `pe` |
+| `ml-*` / `mr-*` | `ms-*` / `me-*` |
+| `pl-*` / `pr-*` | `ps-*` / `pe-*` |
 
-Mantine's own components already use logical properties internally, so once the
+shadcn's own components already use logical properties, so once the
 direction is set they mirror automatically — you only have to be disciplined in
 **your** styles.
 
@@ -70,40 +81,9 @@ logical order; let `dir` handle the visual order.
 
 ## Applying direction at the root
 
-### Mantine app (e.g. environment-template)
-
-Mantine ships first-class RTL: wrap the tree in `DirectionProvider` and set the
-matching `dir` on `<html>`.
-
-```tsx
-import { DirectionProvider, MantineProvider } from '@mantine/core'
-import { detectLocale, localeDir } from './i18n/config'
-
-const locale =
-  typeof window !== 'undefined' ? detectLocale(window.location.pathname) : 'en'
-const dir = localeDir(locale)
-
-if (typeof document !== 'undefined') {
-  document.documentElement.lang = locale
-  document.documentElement.dir = dir // Mantine + browser read this
-}
-
-root.render(
-  <DirectionProvider initialDirection={dir}>
-    <MantineProvider theme={theme} defaultColorScheme="dark">
-      {/* …app… */}
-    </MantineProvider>
-  </DirectionProvider>
-)
-```
-
-To flip direction live (a language switcher) call
-`document.documentElement.setAttribute('dir', localeDir(next))` and Mantine's
-`useDirection().setDirection(dir)`; both read the same value.
-
 ### Plain Vite SPA (kanban, test-harness vite-spa)
 
-No Mantine — just put `dir`/`lang` on `<html>` at bootstrap, after the locale is
+Put `dir`/`lang` on `<html>` at bootstrap, after the locale is
 detected (the same `detectLocale` the i18n config uses):
 
 ```ts
@@ -211,7 +191,7 @@ left` with the flow-relative equivalent; revert any manual `row-reverse`.
 - Don't fake RTL with `flex-direction: row-reverse`, reversed DOM order, or
   per-locale `if (rtl)` layout branches. Set `dir` once; let layout follow.
 - Don't set `dir` on individual components — it belongs on `<html>` so the whole
-  document (and Mantine) agrees.
+  document agrees.
 - Don't translate Arabic copy outside the message system; an RTL language is a
   normal locale, governed by `references/messages.md`. There is no `t()` and no i18next in a
   Pikku frontend — the string comes from `m.some__key()`.

package/skills/pikku-knowledge/SKILL.md

@@ -3,15 +3,14 @@ name: pikku-knowledge
 description: >-
   Use when writing, reading, reorganising or validating a project's knowledge/ directory — the
   notes that say what the app is, in the language its users use. Covers the Open Knowledge Format
-  note (path-as-identity markdown, YAML frontmatter, only `type` required), the app-project
-  profile's sections (entities, decisions, questions, wishlist) and what each answers, how notes
-  become changes (`pikku knowledge gaps`), the changeset plan, the `resource:` URI scheme tying a
-  note to its code, what is NOT a knowledge base, and `pikku knowledge validate|index|gaps`. TRIGGER when: user asks to
-  write down a decision, requirement, entity or open question; asks what the app does or is; asks
-  about knowledge/, notes, an index.md, or a diagram, callout or decision block; or
-  hands over a product brief to record. DO NOT TRIGGER when: user asks what functions, routes,
-  tables or permissions exist (that is `pikku meta` / `pikku info`, never a note), or to write a
-  scenario test (use pikku-scenario).
+  note (path-as-identity markdown, only `type` required), the sections (entities, decisions,
+  questions, wishlist), how notes become changes (`pikku knowledge
+  gaps`), the `resource:` URI scheme tying a note to its code, and `pikku knowledge validate|index|gaps`. TRIGGER when: user asks to write down a decision,
+  requirement, entity or open question; asks what the app does or is; asks about knowledge/
+  notes or a diagram, callout or decision block; or hands over a product brief to record. DO NOT TRIGGER when: user asks what functions, routes, tables or permissions exist
+  (`pikku meta` / `pikku info`, never a note), wants a scenario test (use pikku-scenario), writes a
+  changeset plan (use pikku-architect), or extracts a `.knowledge/` blueprint from a legacy repo
+  (use pikku-software-archaeology).
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -31,7 +30,7 @@ The knowledge base is `knowledge/` at the repo root: markdown notes about **what
 
 Not to be confused with `.knowledge/` — the dot-prefixed JSON blueprint that `pikku-software-archaeology` extracts from a legacy repo. Different directory, different format, different purpose.
 
-## Agent Operating Procedure
+## Operating procedure
 
 1. **Read `knowledge/index.md` first**, then the section index for whatever you are about to touch. It is the cheapest way to learn what the app already claims about itself.
 2. Before writing a note, ask whether `pikku meta` already answers it. If it does, do not write the note — see _What never goes in a note_.
@@ -206,7 +205,7 @@ It is a **summary, not the note** — the argument continues in prose underneath
 | `table:`    | a table name                                       | the generated db schema                                                                    |
 | `addon:`    | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                                  |
 | `scope:`    | a scope name                                       | the `scopes:` a function gates itself with, plus the scopes a `defineSystemRole()` confers |
-| `persona:`  | a persona name                                     | `definePersonas()`                                                                         |
+| `virtualUser:`  | a virtual user name                                     | `defineVirtualUsers()`                                                                         |
 
 Ids are case-sensitive: `createEntry` is not `createentry`.
 
@@ -220,7 +219,7 @@ These are all things that exist somewhere better, so a note is always the copy t
 
 | Do not write                        | Because it lives in                                        |
 | ----------------------------------- | ---------------------------------------------------------- |
-| a `personas/` section               | `definePersonas()` in the project's own code               |
+| a `virtual users/` section               | `defineVirtualUsers()` in the project's own code               |
 | a `scenarios/` section              | the `scenarios` of the plan for the changeset that builds it |
 | a `permissions/` section            | a decision note under `decisions/security/`                |
 | a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema        |
@@ -271,4 +270,4 @@ Notes are different: they say what the app is now, so they change whenever it do
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.
 
-Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — and a `screens/` section. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.
+One exists: it adds `decisions/design/` — rules about how the app looks and behaves — and a `screens/` section. Both are the extending tool's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.

package/skills/pikku-kysely/SKILL.md

@@ -1,32 +1,14 @@
 ---
 name: pikku-kysely
 description: >-
-  Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku
-  function body, or when setting up SQL database services with Kysely. Covers the query builder
-  API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if,
-  transactions, jsonArrayFrom relation helpers), HOW MANY ROUND TRIPS a function body costs and how to
-  collapse sequential awaits into one statement, AND @pikku/kysely service setup (channel stores,
-  workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any
-  non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
-  conditional query), the injected `kysely` service is used in a function body, or code uses
-  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, a function body
-  awaits more than one query, or the user asks about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
-  services (use pikku-service-backends).
+  Use when WRITING KYSELY QUERIES (select, join, aggregate, insert, update, delete) inside a Pikku function body, or when setting up SQL database services with Kysely. Covers the query builder API (joins, groupBy/having, returning, sql template, $if, transactions, jsonArrayFrom), how many round trips a function body costs and how to collapse sequential awaits into one statement, and @pikku/kysely service setup (channel stores, workflow, secret, AI storage and deployment services).
+  TRIGGER when: writing any non-trivial kysely query (join, count/sum, groupBy, subquery, transaction, conditional query), a function body awaits more than one query, the injected `kysely` service is used, code uses PikkuKysely, KyselyChannelStore, KyselyWorkflowService or KyselySecretService, or the user asks about SQL setup with Pikku.
+  DO NOT TRIGGER when: the services are MongoDB or Redis backed (use pikku-service-backends), or the task is the pagination contract rather than the query (use pikku-list-query).
 installGroups: [core]
 ---
 
 # Pikku Kysely (SQL Database Services)
 
-## Agent Operating Procedure
-
-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 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
 
 In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Every connection factory below wires the **CamelCasePlugin** by default, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a ` sql` `` literal**. If a project opted out (`createNodeSqliteKysely({ camelCase: false })`), that inverts — check how the instance was built before assuming. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).

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

@@ -1,9 +1,9 @@
 ---
 name: pikku-list-query
 description: >-
-  Use when building a paginated/infinite-scroll list — any RPC that returns rows a user scrolls through (tables, card grids, search results). Covers pikkuListFunc, the ListInput/ListOutput cursor contract, and the generated usePikkuInfiniteQuery hook.
+  Use when building a paginated or infinite-scroll list: any RPC that returns rows a user scrolls through (tables, card grids, search results). Covers the backend pikkuListFunc, the ListInput/ListOutput cursor contract, the filter tree, and the generated usePikkuInfiniteQuery hook.
   TRIGGER when: user asks for infinite scroll, "load more", a paginated table/list/grid, or a list that could grow beyond a single page.
-  DO NOT TRIGGER when: the list is small and fixed (e.g. a settings page with 5 items) — a plain pikkuFunc + usePikkuQuery returning a full array is simpler and correct there.
+  DO NOT TRIGGER when: the list is small and fixed (for example 5 settings items), where a plain pikkuFunc plus usePikkuQuery returning a full array is correct, or when the task is general React provider and hook setup (use pikku-react).
 installGroups: [core, client]
 ---
 

package/skills/pikku-meta/references/audit.md

@@ -1,5 +1,14 @@
 # Pikku Dependency Audit
 
+## Contents
+
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [The `pikku audit` command](#the-pikku-audit-command)
+- [The `pikku update` command](#the-pikku-update-command)
+- [Console integration (@pikku/addon-console)](#console-integration-pikkuaddon-console)
+- [Console UI (@pikku/console)](#console-ui-pikkuconsole)
+- [Report shape (SecurityAuditReport)](#report-shape-securityauditreport)
+
 ## Agent Operating Procedure
 
 1. The audit is a generated artifact, not live state. `pikku audit` writes the
@@ -106,7 +115,7 @@ is admin-only), so the host must have Better Auth wired — see `pikku-auth`.
   **remediation slot**.
 - `renderRemediation({ pkg, version, issue })` — the extension seam. OSS default
   is `UpdateDependencyButton` (the free bump + `bun install`). Downstream
-  consoles (Fabric) pass their own sandbox-verified action here — replace the
+  consoles pass their own sandbox-verified action here — replace the
   action, keep the view.
 - Hooks: `useSecurityAudit` (read), `useRunSecurityAudit` (run),
   `useUpdateDependency` (bump). All are `useMutation`/`useQuery` — surface

package/skills/pikku-meta/references/meta.md

@@ -1,5 +1,11 @@
 # Pikku Project Metadata
 
+## Contents
+
+- [Reading](#reading)
+- [Changing](#changing)
+- [Human-readable tables (`pikku info`)](#human-readable-tables-pikku-info)
+
 `pikku meta` is the machine-readable view of the project and the write path to it.
 `pikku info` is the same ground as human-readable tables. Prefer `meta` when you are
 going to act on the output; prefer `info` when a person is going to read it.

package/skills/pikku-meta/references/versioning.md

@@ -1,5 +1,15 @@
 # Pikku Function Versioning
 
+## Contents
+
+- [Before You Start](#before-you-start)
+- [Function Versioning](#function-versioning)
+- [Version Manifest (`versions.pikku.json`)](#version-manifest-versionspikkujson)
+- [CLI Commands](#cli-commands)
+- [The `pikku release` command](#the-pikku-release-command)
+- [CI Integration](#ci-integration)
+- [Complete Example](#complete-example)
+
 ## Before You Start
 
 ```bash

package/skills/pikku-middleware/SKILL.md

@@ -1,24 +1,15 @@
 ---
 name: pikku-middleware
 description: >-
-  Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware
-  (including service-to-service bearer auth), per-route middleware, session-setting middleware, or
-  understanding middleware execution order and priority. TRIGGER when: user wants middleware on
-  some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global
-  interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about
-  permissions, sessions or auth strategies like authBearer/authCookie (use
-  pikku-auth), or deployment.
+  Use when adding middleware to a Pikku app: global (addGlobalMiddleware), HTTP and prefix (addHTTPMiddleware), tag-scoped (addTagMiddleware), per-wiring, session-setting middleware, and execution order and priority. Covers the pikkuMiddleware factory, where a token is resolved into a session (HTTP middleware, cron tasks), and service-to-service bearer gates.
+  TRIGGER when: user wants middleware on some or all routes, tag-scoped cross-cutting concerns, global interceptors, middleware priority or order questions, or middleware that calls setSession for a machine caller.
+  DO NOT TRIGGER when: the question is choosing or configuring an auth strategy (authBearer, authCookie, Better Auth, API keys, `pikku login`), permissions or scopes (use pikku-permissions), or deployment.
 installGroups: [core]
 ---
 
 # Pikku Middleware
 
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info tags --json` to understand the existing middleware and tag landscape.
-2. Identify the source files that own the behavior — wirings files, not generated output.
-3. Register middleware at module load time — in a `wirings/*.ts` file, never inside a function body.
-4. Validate: run `pikku all --tsc` after adding or changing middleware — it regenerates and then confirms type safety in one pass.
+Register middleware at module load time in a `wirings/*.ts` file, never inside a function body. After a change, run `pikku all --tsc`.
 
 ## The `pikkuMiddleware` Factory
 
@@ -223,7 +214,7 @@ export const reportSomething = pikkuFunc({
 })
 ```
 
-An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-auth`).
+An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-permissions`).
 
 ### It MUST be `addHTTPMiddleware`, never `addTagMiddleware`
 
@@ -255,13 +246,13 @@ Unlike tag middleware over `/rpc`, this works: `runScheduledTask` builds its wir
 
 ### The one sessionless exception: bootstrap
 
-An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-auth`).
+An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-permissions`).
 
 ## Service-to-Service Bearer Auth (gate-only pattern)
 
 Use this when the callee needs to know only THAT the caller is trusted, not WHICH caller it is. If it needs to know which, use the session pattern above.
 
-A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-auth`), never inside `func`.
+A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
 
 **On the server (the service being called):** tag the function, register a `pikkuMiddleware` that reads the `Authorization` header on that tag.
 

package/skills/pikku-n8n-import/SKILL.md

@@ -1,6 +1,14 @@
 ---
 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).'
+description: >-
+  Use when importing an n8n workflow JSON export into a runnable Pikku workflow. Owns the whole
+  flow: run `pikku import n8n`, triage what it could not map, fill each stub, report missing
+  `@pikku/addon-*` integrations, and verify the result compiles with no surviving stubs. TRIGGER
+  when: the user says "import this n8n workflow" or "convert this n8n export to pikku", points at
+  an n8n `.json` export or a directory of them, or continues after `pikku import n8n` left throwing
+  stub functions (`STUB — generated from n8n …`, `— implement me`) or a `*.integrations.json`
+  manifest. 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