@pikku/skills 0.12.57 → 0.12.59

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

@@ -0,0 +1,117 @@
+# Functions and schemas
+
+## Functions
+
+Three main function types:
+
+```typescript
+// Requires authentication — receives session in wire context.
+// input/output are Zod schemas; the data + return types are inferred from them.
+const updateTodo = pikkuFunc({
+  input: UpdateTodoInput,
+  output: TodoOutput,
+  func: async (services, data, wire) => {
+    const { session } = wire
+    return services.todoStore.update(data.id, data)
+  },
+})
+
+// No authentication required
+const listTodos = pikkuSessionlessFunc({
+  input: ListTodosInput,
+  output: TodoListOutput,
+  func: async (services, data) => {
+    return { todos: services.todoStore.list(data.filters) }
+  },
+})
+
+// No input or output (for scheduled tasks, lifecycle hooks)
+const cleanup = pikkuVoidFunc(async (services) => {
+  services.todoStore.cleanOldItems()
+})
+```
+
+Services can be destructured inline in the `func` signature (e.g. `async ({ logger, todoStore }, { title }) => ...`). Full config options:
+
+```typescript
+pikkuFunc({
+  // Identity and documentation — prose, so it follows `metaLocale` in
+  // pikku.config.json (default `en`). The identifier does not; see
+  // "What Language You Write In".
+  title?: string,           // Human-readable name
+  description?: string,     // What the function does
+  version?: number,         // Contract version (see pikku-meta)
+  override?: string,        // Logical name override, so several exports share a versioned base
+  tags?: string[],          // For grouping and middleware targeting
+
+  // Contract
+  input?: ZodSchema,        // Input validation schema
+  output?: ZodSchema,       // Output validation schema
+  errors?: Array<typeof PikkuError>,  // Errors this function may throw
+
+  // Reachability
+  expose?: boolean,         // Allow external RPC calls (see pikku-wiring)
+  remote?: boolean,         // Allow remote RPC calls
+  mcp?: boolean,            // Expose as MCP tool (see pikku-wiring)
+  readonly?: boolean,       // Declares the function performs no writes
+  deploy?: 'serverless' | 'server' | 'auto',
+
+  // Authorization — see pikku-auth
+  auth?: boolean,           // Override default auth requirement
+  scopes?: ScopeId[],       // AND-ed, checked before permissions; session required
+  permissions?: PermissionGroup,  // OR-ed pool
+  permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
+  middleware?: PikkuMiddleware[], // See pikku-middleware
+
+  // Agent tooling — see pikku-agent
+  approvalRequired?: boolean,
+  approvalDescription?: (services, data) => Promise<string>,
+
+  // Workflow step behavior — see pikku-workflow
+  workflowQueued?: boolean, // Dispatch via queue instead of inline
+  workflowRetries?: number,
+  workflowTimeout?: string, // e.g. '30s', '5m'
+
+  audit?: boolean | { durability?: 'best-effort' | 'transactional' },
+
+  func: async (services, data, wire) => { ... },
+})
+```
+
+`scopes` is the one option `pikkuSessionlessFunc` does not accept, and the
+omission is deliberate: scopes are AND-ed and fail closed, so an anonymous
+caller holds none and satisfies none — a sessionless function with scopes would
+reject every caller it exists to serve. Gate those with `permissions`, which
+receive the optional session and may pass anonymous.
+
+**Generics XOR `input`/`output` — never both.** A function's data and return
+types come from _one_ source: either the `input`/`output` schemas (preferred —
+they double as runtime validation and OpenAPI) or type generics
+(`pikkuFunc<In, Out>({ ... })`). Passing both makes the two disagree and forces
+`as any` casts. Do not annotate the `func` return type inline either — let the
+`output` schema (or the generic) be the single source of truth for the type.
+
+```typescript
+// Correct — schema-based (no generics, no inline return type)
+pikkuFunc({ input: MyInput, output: MyOutput, func: async (s, d) => { ... } })
+// Correct — generic-based (no input/output)
+pikkuFunc<MyIn, MyOut>({ func: async (s, d) => { ... } })
+// WRONG — mixing the two
+pikkuFunc<MyIn, MyOut>({ input: MyInput as any, func: async (s, d) => { ... } })
+```
+
+## Schemas (Validation)
+
+Pikku uses Standard Schema — works with Zod, Valibot, ArkType:
+
+```typescript
+import { z } from 'zod'
+
+const CreateTodoInputSchema = z.object({
+  title: z.string().min(1).max(200),
+  priority: z.enum(['low', 'medium', 'high']).optional(),
+  tags: z.array(z.string()).optional(),
+})
+```
+
+Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI documentation.

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

@@ -31,10 +31,10 @@ identifier is a migration, not an edit.
 { "metaLocale": "de" }
 ```
 
-Meta is the one part of a project the **Pikku Console** renders back to a human.
-A team reviewing their own functions, features and scenario reports in the
-Console is reading meta and nothing else, so a team whose working language is
-German should be able to read their Console in German. That is the entire reason
+Meta is the one part of a project that is read back to a human. A team
+reviewing their own functions, features and scenario reports is reading meta
+and nothing else, so a team whose working language is German should be able to
+read it in German. That is the entire reason
 the field exists.
 
 Read it before you author meta, and write descriptions, titles and templates in
@@ -79,7 +79,7 @@ settings, each on its own axis:
 // apps/app/src/i18n/active.json — what a first-time visitor opens in
 { "defaultLocale": "de" }
 
-// pikku.config.json — the language the team reads their Console in
+// pikku.config.json — the language the team reads their meta in
 { "metaLocale": "de" }
 ```
 

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

@@ -4,14 +4,16 @@
 
 | Package                       | Use Case                              |
 | ----------------------------- | ------------------------------------- |
-| `@pikku/express-server`       | Express standalone server             |
+| `@pikku/express`              | Express standalone server             |
 | `@pikku/express-middleware`   | Express as middleware in existing app |
-| `@pikku/fastify-server`       | Fastify standalone                    |
+| `@pikku/fastify`              | Fastify standalone                    |
 | `@pikku/fastify-plugin`       | Fastify plugin                        |
 | `@pikku/next`                 | Next.js API routes                    |
-| `@pikku/aws-lambda`           | AWS Lambda handlers                   |
+| `@pikku/lambda`               | AWS Lambda handlers                   |
 | `@pikku/cloudflare`           | Cloudflare Workers                    |
-| `@pikku/uws-server`           | uWebSockets.js (high perf)            |
+| `@pikku/uws`                  | uWebSockets.js (high perf)            |
+| `@pikku/ws`                   | `ws` WebSocket server                 |
+| `@pikku/azure-functions`      | Azure Functions                       |
 | `@pikku/modelcontextprotocol` | MCP server                            |
 
 ## Service Packages

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

@@ -0,0 +1,14 @@
+# Testing
+
+Functions are easily testable because they're pure:
+
+```typescript
+const mockServices = {
+  logger: new MockLogger(),
+  todoStore: new MockTodoStore(),
+}
+
+// Call function directly — no HTTP, no framework
+const result = await listTodos.func(mockServices, { userId: 'test' })
+expect(result.todos).toHaveLength(3)
+```

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

@@ -1,6 +1,12 @@
 ---
 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.
+description: >-
+  Rebuild an old screen, page or feature (from an old console, another repo, screenshots or a
+  description) in the current app: extract what it does as plain business logic, no layout or code
+  detail, then design 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 restyling a
+  screen already in the app.
 installGroups: [core]
 ---
 

package/skills/pikku-deploy/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: pikku-deploy
 description: >-
-  Use when deploying a Pikku app to a runtime — Express, Fastify, uWebSockets.js, the `ws` library,
-  Next.js, AWS Lambda, Cloudflare Workers or Azure Functions. Covers the bootstrap every runtime
-  shares, choosing between them, and the behaviour that differs: which accept
-  `RunHTTPWiringOptions`, how each one runs scheduled tasks, and where CORS and health checks live.
-  TRIGGER when: writing or debugging `start.ts` / a worker entry / a Lambda handler, code imports
-  `@pikku/express`, `@pikku/fastify`, `@pikku/uws`, `@pikku/ws`, `@pikku/next`, `@pikku/lambda`,
-  `@pikku/cloudflare` or `@pikku/azure-functions`, or the user asks how to serve, host or deploy a
-  Pikku app. DO NOT TRIGGER when: defining functions or wirings with no runtime-specific code.
+  Deploying a Pikku app to a runtime: Express, Fastify, uWebSockets.js, `ws`, Next.js, AWS Lambda,
+  Cloudflare Workers, Azure Functions. Covers the shared bootstrap, choosing a runtime, which accept
+  RunHTTPWiringOptions, scheduled tasks per runtime, CORS and health checks. TRIGGER when: writing
+  or debugging `start.ts`, a worker entry or Lambda handler, importing
+  @pikku/express|fastify|uws|ws|next|lambda|cloudflare|azure-functions, or asked how to serve, host
+  or deploy a Pikku app. DO NOT TRIGGER when: defining functions or wirings with no runtime-specific
+  code.
 installGroups: [core]
 ---
 
@@ -35,23 +34,23 @@ Two families, and the difference decides how you write the entry file.
 **Long-running servers** own a process. Services are built once at startup and
 live in module scope for the life of the server.
 
-| Runtime | Package | Reach for it when |
-| --- | --- | --- |
-| Express | `@pikku/express` | An existing Express app, or you want static assets and upload handling |
-| Fastify | `@pikku/fastify` | An existing Fastify app, or you want its stricter defaults |
-| uWebSockets.js | `@pikku/uws` | Highest throughput, HTTP and WebSocket on one port |
-| ws | `@pikku/ws` | WebSocket only, attached to an `http.Server` you own |
+| Runtime        | Package          | Reach for it when                                                      |
+| -------------- | ---------------- | ---------------------------------------------------------------------- |
+| Express        | `@pikku/express` | An existing Express app, or you want static assets and upload handling |
+| Fastify        | `@pikku/fastify` | An existing Fastify app, or you want its stricter defaults             |
+| uWebSockets.js | `@pikku/uws`     | Highest throughput, HTTP and WebSocket on one port                     |
+| ws             | `@pikku/ws`      | WebSocket only, attached to an `http.Server` you own                   |
 
 **Per-invocation runtimes** are handed a request and torn down. Services are
 cached in module scope across warm invocations, and the deploy codegen writes
 that caching for you.
 
-| Runtime | Package | Reach for it when |
-| --- | --- | --- |
-| AWS Lambda | `@pikku/lambda` | API Gateway, EventBridge, SQS |
-| Cloudflare Workers | `@pikku/cloudflare` | Edge, Durable Objects for channels |
-| Azure Functions | `@pikku/azure-functions` | Azure hosting — note channels are not implemented |
-| Next.js | `@pikku/next` | Pikku behind Next routes, or RPC from Server Components |
+| Runtime            | Package                  | Reach for it when                                       |
+| ------------------ | ------------------------ | ------------------------------------------------------- |
+| AWS Lambda         | `@pikku/lambda`          | API Gateway, EventBridge, SQS                           |
+| Cloudflare Workers | `@pikku/cloudflare`      | Edge, Durable Objects for channels                      |
+| Azure Functions    | `@pikku/azure-functions` | Azure hosting — note channels are not implemented       |
+| Next.js            | `@pikku/next`            | Pikku behind Next routes, or RPC from Server Components |
 
 Then read the reference for the one you picked: `references/express.md`,
 `references/fastify.md`, `references/uws.md`, `references/ws.md`,
@@ -84,16 +83,16 @@ hand-written handlers are for the cases the deploy codegen does not cover.
 `maxBodySize`, `respondWith404`, `coerceDataFromSchema` and `bubbleErrors` reach
 the request only on the runtimes that thread them through.
 
-| Runtime | Accepts options | Where an oversized body is actually stopped |
-| --- | --- | --- |
-| Express | `init(httpOptions)` | The `express.json` parser limit, fed by `maxBodySize` |
-| Fastify | `init(httpOptions)` | Fastify's own `bodyLimit`, set from `maxBodySize` |
-| uWS | HTTP handler only | The handler counts bytes itself and answers `413` |
-| ws | Yes, on the handler | `maxPayload` on the `WebSocketServer` |
-| Next.js | Only via your own `PikkuNextJS` handler | Next's own limits |
-| Lambda | **No** | API Gateway's payload limit |
-| Cloudflare | Partially — `runFetch(request, hibernation, options)` | The platform's limit |
-| Azure | **No** | Azure's request limits |
+| Runtime    | Accepts options                                       | Where an oversized body is actually stopped           |
+| ---------- | ----------------------------------------------------- | ----------------------------------------------------- |
+| Express    | `init(httpOptions)`                                   | The `express.json` parser limit, fed by `maxBodySize` |
+| Fastify    | `init(httpOptions)`                                   | Fastify's own `bodyLimit`, set from `maxBodySize`     |
+| uWS        | HTTP handler only                                     | The handler counts bytes itself and answers `413`     |
+| ws         | Yes, on the handler                                   | `maxPayload` on the `WebSocketServer`                 |
+| Next.js    | Only via your own `PikkuNextJS` handler               | Next's own limits                                     |
+| Lambda     | **No**                                                | API Gateway's payload limit                           |
+| Cloudflare | Partially — `runFetch(request, hibernation, options)` | The platform's limit                                  |
+| Azure      | **No**                                                | Azure's request limits                                |
 
 On Fastify, leaving `maxBodySize` unset keeps Fastify's stricter 1MB default
 rather than loosening it to Pikku's 10MB fallback. On uWS the chunks are dropped

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

@@ -16,7 +16,7 @@ the upgrade and message plumbing to them.
 
 ```typescript
 import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
-import { stopSingletonServices } from '@pikku/core'
+import { stopSingletonServices } from '@pikku/core/utils'
 import { Server } from 'http'
 import { WebSocketServer } from 'ws'
 

package/skills/pikku-emails/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: pikku-emails
 description: >-
-  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).
+  Pikku's file-based email templates: html/subject/text templates, locales, partials, theme, `pikku
+  emails generate`, rendering and sending via EmailService. TRIGGER when: code uses
+  renderEmailTemplate, EmailTemplateName, EmailService, SendTemplateEmailInput, LocalEmailService or
+  imports .pikku/email/pikku-emails.gen; the project has an emails/ directory or emailTemplatesDir
+  in pikku.config.json; or the user adds, edits or translates a transactional email (verification,
+  reset, invitation, receipt). DO NOT TRIGGER for app UI i18n (use pikku-i18n) or sign-in flows in
+  general (use pikku-auth).
 installGroups: [core]
 ---
 

package/skills/pikku-guide/SKILL.md

@@ -1,16 +1,13 @@
 ---
 name: pikku-guide
 description: >-
-  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).
+  Write, rewrite or regenerate a project's end-user guide from the scenario suite (`pikku scenario
+  guide`): hand-written markdown with `pikku:guide` markers that pull in scenario screenshots and
+  recordings. Covers planning, markers, capture, seed data, `.guide.lock`, `document: false`, and
+  traps that leave a guide empty, refused or all videos. TRIGGER when: asked for a user guide, help
+  pages, docs with screenshots, "document the app", or the /docs pages are bad, thin or all videos.
+  DO NOT TRIGGER for API reference, READMEs, the Pikku framework's own docs, or writing scenarios
+  (use pikku-scenario).
 installGroups: [core]
 ---
 

package/skills/pikku-i18n/SKILL.md

@@ -1,13 +1,12 @@
 ---
 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 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.
+  Writing user-facing text in a Pikku frontend or making it speak another language: Paraglide JS
+  message functions from per-locale JSON, adding a language, generated enum-label maps
+  (@pikku/paraglide), and RTL support (Arabic, Hebrew, Farsi, Urdu). TRIGGER when: writing display
+  text in a frontend, making copy translatable, adding a language, labelling an enum/status/role
+  value, or supporting RTL. DO NOT TRIGGER for backend functions, error messages thrown from
+  functions, or log output.
 installGroups: [client]
 ---
 
@@ -22,11 +21,11 @@ type-checks them, so an i18n mistake blocks the build rather than the release.
 
 ## Pick the reference
 
-| You are… | Read |
-| --- | --- |
-| Writing copy, wiring Paraglide, or adding a language | `references/messages.md` |
-| Labelling an enum, status, kind or role value | `references/enum-labels.md` |
-| Adding Arabic (or Hebrew, Farsi, Urdu), or writing layout styles | `references/rtl.md` |
+| You are…                                                         | Read                        |
+| ---------------------------------------------------------------- | --------------------------- |
+| Writing copy, wiring Paraglide, or adding a language             | `references/messages.md`    |
+| Labelling an enum, status, kind or role value                    | `references/enum-labels.md` |
+| Adding Arabic (or Hebrew, Farsi, Urdu), or writing layout styles | `references/rtl.md`         |
 
 ## Three axes, and a brief usually means only one
 
@@ -34,14 +33,14 @@ type-checks them, so an i18n mistake blocks the build rather than the release.
 codebase. Reading it as one about the codebase is the most expensive mistake
 available here.
 
-| Axis | What it covers | What sets it |
-| --- | --- | --- |
-| **Identifiers** | Function, component, type and file names; tables and columns | Nothing — always English |
-| **Meta** | `description` / `name` / `title` authored in code, rendered by the console | `metaLocale` in `pikku.config.json` |
-| **Product UI** | Every string the app shows a user | `messages/<locale>.json` + `defaultLocale` |
+| Axis            | What it covers                                                           | What sets it                               |
+| --------------- | ------------------------------------------------------------------------ | ------------------------------------------ |
+| **Identifiers** | Function, component, type and file names; tables and columns             | Nothing — always English                   |
+| **Meta**        | `description` / `name` / `title` authored in code, read back to the team | `metaLocale` in `pikku.config.json`        |
+| **Product UI**  | Every string the app shows a user                                        | `messages/<locale>.json` + `defaultLocale` |
 
 `baseLocale` stays `en` whatever language the product speaks — it names the
-message *source* catalogue every other locale is derived from, not the language
+message _source_ catalogue every other locale is derived from, not the language
 the app is in. Set `defaultLocale` instead.
 
 ## Direction is one setting, not per-component work
@@ -59,7 +58,7 @@ is what makes an RTL language just another locale file.
   `m['enum__' + x]()`, no key-string resolver. A computed key cannot be
   type-checked or tree-shaken, so a renamed message degrades to silent runtime
   text. Where the key is genuinely dynamic, map the discriminant to a message
-  *function* — the map is checked, a string is not.
+  _function_ — the map is checked, a string is not.
 - **Do not `asI18n()` a hardcoded English string.** `asI18n` exists to pass
   opaque server data (a name, a slug, an id) through the i18n gate. An enum value
   goes through its generated label map.

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

@@ -29,11 +29,11 @@ is a statement about **one** of three separate things, and reading it as a
 statement about the codebase is the single most expensive mistake available in
 this skill. Three axes:
 
-| Axis            | What it covers                                                                                          | What sets it                                                    |
-| --------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| **Identifiers** | Function, component, type and file names; database tables and columns                                   | Nothing — always English, no setting                            |
-| **Meta**        | `description` / `name` / `title` / `template` authored inside the code, which the Pikku Console renders | `metaLocale` in `pikku.config.json`, default `en`                   |
-| **Product UI**  | Every string the app shows a user                                                                       | `messages/<locale>.json` + `defaultLocale` — **this axis only** |
+| Axis            | What it covers                                                                                | What sets it                                                    |
+| --------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; database tables and columns                         | Nothing — always English, no setting                            |
+| **Meta**        | `description` / `name` / `title` / `template` authored inside the code, read back to the team | `metaLocale` in `pikku.config.json`, default `en`               |
+| **Product UI**  | Every string the app shows a user                                                             | `messages/<locale>.json` + `defaultLocale` — **this axis only** |
 
 A non-English product moves the third row and nothing else.
 
@@ -63,7 +63,7 @@ So a German medical portal is **three** settings, not one:
 // apps/app/src/i18n/active.json — what a visitor opens in
 { "defaultLocale": "de" }
 
-// pikku.config.json — the language the team reads their Console in
+// pikku.config.json — the language the team reads their meta in
 { "metaLocale": "de" }
 ```
 
@@ -221,8 +221,6 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 - 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 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.
-
   The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message _function_ and call it — the map is type-checked, a string is not.
 
 - Don't re-resolve messages by string key or re-implement `{param}` interpolation. A key-string resolver turns a missing key back into silent runtime text, surrendering the type safety that is the entire reason to use Paraglide.

package/skills/pikku-knowledge/SKILL.md

@@ -1,16 +1,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, 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).
+  Write, read, reorganise or validate a project's knowledge/ directory: Open Knowledge Format notes
+  (path-as-identity markdown, only `type` required), sections (entities, decisions, questions,
+  wishlist), notes becoming changes (`pikku knowledge gaps`), the `resource:` URI scheme, `pikku
+  knowledge validate|index|gaps`. TRIGGER when: asked to record a decision, requirement, entity or
+  open question, what the app does or is, a knowledge note/diagram/callout, or a product brief. DO
+  NOT TRIGGER for what functions/routes/tables exist (`pikku meta`/`pikku info`), scenarios (use
+  pikku-scenario), changeset plans (use pikku-architect) or legacy blueprint extraction (use
+  pikku-software-archaeology).
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -21,7 +19,6 @@ agent:
     verify:
       - id: knowledge-consistent
         command: pikku knowledge validate
-
 ---
 
 # Pikku Knowledge
@@ -72,14 +69,14 @@ worse than one of them losing access mid-session.
 
 Frontmatter fields:
 
-| Field         | Meaning                                                                                                                 |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Field         | Meaning                                                                                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `type`        | **The only required field.** One of `entity`, `decision`, `note`, `overview`. Lowercase — every gate compares it literally, so a near-miss is a note no command can see. |
-| `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
-| `description` | One line, used as the note's subtitle in a section index.                                                               |
-| `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
-| `tags`        | Flow list (`[a, b]`) or a `- item` block; both are read.                                                                |
-| `timestamp`   | When it was written, if it matters.                                                                                     |
+| `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                                                                  |
+| `description` | One line, used as the note's subtitle in a section index.                                                                                                                |
+| `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                                                                             |
+| `tags`        | Flow list (`[a, b]`) or a `- item` block; both are read.                                                                                                                 |
+| `timestamp`   | When it was written, if it matters.                                                                                                                                      |
 
 `index.md` and `log.md` are **reserved**: an `index.md` maps a directory, a `log.md` is an append-only record. Neither is ever listed as a note by an index.
 
@@ -109,13 +106,13 @@ knowledge/
 
 Each section answers exactly one question, which is what lets a reader find a note without an index of indexes:
 
-| Section               | The question it answers                                            |
-| --------------------- | ------------------------------------------------------------------ |
-| `entities/`           | What is this thing, in the words users use for it?                 |
-| `decisions/`          | What was chosen, and what does that rule out?                      |
-| `decisions/security/` | Who may do what?                                                   |
-| `questions/`          | What has been asked and not yet answered?                          |
-| `wishlist/`           | What does somebody want that nobody has asked to be built?         |
+| Section               | The question it answers                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `entities/`           | What is this thing, in the words users use for it?         |
+| `decisions/`          | What was chosen, and what does that rule out?              |
+| `decisions/security/` | Who may do what?                                           |
+| `questions/`          | What has been asked and not yet answered?                  |
+| `wishlist/`           | What does somebody want that nobody has asked to be built? |
 
 **Create a section the turn you have a note for it** — never a scaffold of empty directories, and never a section without its own `index.md`. A section index says in one line what belongs in it; that sentence is the reason the file exists, so `pikku knowledge index` writes only the note listing and leaves your prose alone.
 
@@ -193,19 +190,19 @@ It is a **summary, not the note** — the argument continues in prose underneath
 
 **Every kind resolves.** That is the whole design: a kind that cannot be checked lets notes accumulate references nothing validates, and the graph rots into fiction exactly where it looks most authoritative.
 
-| Kind        | An id is                                           | Where it resolves                                                                          |
-| ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `func:`     | a function id                                      | generated function meta                                                                    |
-| `workflow:` | a workflow name                                    | generated workflow meta                                                                    |
-| `schema:`   | a schema name                                      | generated schemas                                                                          |
-| `http:`     | a route, `method:route`, or the function behind it | generated http wirings                                                                     |
-| `queue:`    | a queue name                                       | generated queue wirings                                                                    |
-| `cron:`     | a scheduled task name                              | generated scheduler wirings                                                                |
-| `channel:`  | a channel name                                     | generated channel meta                                                                     |
-| `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 |
-| `virtualUser:`  | a virtual user name                                     | `defineVirtualUsers()`                                                                         |
+| Kind           | An id is                                           | Where it resolves                                                                          |
+| -------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `func:`        | a function id                                      | generated function meta                                                                    |
+| `workflow:`    | a workflow name                                    | generated workflow meta                                                                    |
+| `schema:`      | a schema name                                      | generated schemas                                                                          |
+| `http:`        | a route, `method:route`, or the function behind it | generated http wirings                                                                     |
+| `queue:`       | a queue name                                       | generated queue wirings                                                                    |
+| `cron:`        | a scheduled task name                              | generated scheduler wirings                                                                |
+| `channel:`     | a channel name                                     | generated channel meta                                                                     |
+| `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 |
+| `virtualUser:` | a virtual user name                                | `defineVirtualUsers()`                                                                     |
 
 Ids are case-sensitive: `createEntry` is not `createentry`.
 
@@ -217,14 +214,14 @@ There is no kind for a service, a middleware or a component. Say it in prose ins
 
 These are all things that exist somewhere better, so a note is always the copy that drifts:
 
-| Do not write                        | Because it lives in                                        |
-| ----------------------------------- | ---------------------------------------------------------- |
-| a `virtual users/` section               | `defineVirtualUsers()` in the project's own code               |
+| Do not write                        | Because it lives in                                          |
+| ----------------------------------- | ------------------------------------------------------------ |
+| 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        |
-| a changelog                         | `CHANGELOG.md` at the repo root                            |
-| **secrets or credentials**          | a secrets service. Never here — `knowledge/` is committed. |
+| a `permissions/` section            | a decision note under `decisions/security/`                  |
+| a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema          |
+| a changelog                         | `CHANGELOG.md` at the repo root                              |
+| **secrets or credentials**          | a secrets service. Never here — `knowledge/` is committed.   |
 
 And two shapes that look like a knowledge base but are not: