@pikku/skills 0.12.4 → 0.12.8

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

@@ -47,10 +47,52 @@ await appServer.start()
 
 **Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
 
-**Methods:** `init(httpOptions?)`, `start()`, `stop()`, `enableExitOnSigInt()`
+**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
 
 **Property:** `app: uWS.App` — Direct access to uWebSockets app instance.
 
+### What the server does and does not give you
+
+`init()` registers three things in order: the health check (`healthCheckPath`,
+default `/health-check`), a catch-all `app.any('/*')` HTTP handler, and a
+catch-all `app.ws('/*')` websocket handler. Nothing is registered by the
+constructor, so nothing answers before `init` runs.
+
+**There is no `enableCors`, no static assets and no `content` support** — unlike
+the Express server. The class is explicitly a prototyping convenience; for
+anything that needs extra handlers, use `@pikku/uws-handler` directly and treat
+`pikku-uws-server.ts` as the template (that is what its own JSDoc says).
+
+`httpOptions` reaches the HTTP handler only. The websocket handler is
+constructed with a fixed `{ logger, logRoutes: true }`, so per-request options
+do not apply to the upgrade path. `loadSchemas` is also never passed by the
+server, so schemas compile lazily on first use rather than at startup — pass
+`loadSchemas: true` in `httpOptions` if you want the startup cost paid up front.
+
+`stop()` closes the listen socket and then waits a fixed 2 seconds for
+connections to drain. Called before `start()`, it throws a bare **string**, not
+an `Error`, so `catch (e) { e.message }` reads `undefined`.
+
+### Body limits
+
+uWS hands over raw chunks with no limit of its own, so the handler counts the
+bytes itself. A request over `maxBodySize` (default `DEFAULT_MAX_BODY_SIZE`) is
+answered `413` with a `PayloadTooLargeError` body, and the chunks are dropped
+rather than concatenated — an oversized request never accumulates in memory. A
+`content-length` header that already exceeds the limit short-circuits before any
+data arrives.
+
+### Handlers directly (own uWS app)
+
+```typescript
+import { pikkuHTTPHandler, pikkuWebsocketHandler } from '@pikku/uws-handler'
+
+app.any('/*', pikkuHTTPHandler({ logger, logRoutes: true, loadSchemas: true }))
+app.ws('/*', pikkuWebsocketHandler({ logger, logRoutes: true }))
+```
+
+Both take `{ logger, logRoutes?, loadSchemas? } & RunHTTPWiringOptions`.
+
 ## WebSocket Standalone (ws library)
 
 For WebSocket-only servers using the `ws` library:
@@ -86,3 +128,14 @@ process.on('SIGINT', async () => {
   process.exit(0)
 })
 ```
+
+`pikkuWebsocketHandler` takes `{ server, wss, logger, logRoutes?, loadSchemas? }`
+plus `RunHTTPWiringOptions`, and there is no server class in `@pikku/ws` — the
+handler attaches to a `Server` you own.
+
+`noServer: true` is required, not stylistic: the handler listens for the HTTP
+server's own `upgrade` event, opens the channel (running middleware and auth
+first), and only then calls `wss.handleUpgrade`. A `WebSocketServer` bound to
+the server would take the socket before any of that ran. An upgrade the channel
+rejects gets the socket destroyed, and an auth failure is written as a real HTTP
+response on the raw socket rather than a silent drop.

package/skills/pikku-deps/SKILL.md

@@ -36,19 +36,29 @@ installGroups: [core]
 
 - `pikku audit` — reports **security advisories** only.
 - `pikku audit --outdated` — also reports **available dependency updates**.
-- Package-manager detection is by **lockfile** (walks up: `bun.lock`/`bun.lockb`,
-  then `yarn.lock`). Only **bun** runs a real audit (`bun audit --json` +
+- Package-manager detection is by **lockfile**, walking up to 12 levels to the
+  workspace root, checking in this order: `bun.lock`/`bun.lockb`,
+  `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`. A project with several
+  lockfiles resolves as bun. Only **bun** runs a real audit (`bun audit --json` +
   `bun outdated`, normalised into one `SecurityAuditReport` with per-severity /
   per-update-level counts). Other PMs are detected but **stubbed** with a `note`
   field until their shapes are normalised — issues/updates come back empty.
-- `bun audit` exits non-zero when it *finds* advisories but still writes a valid
-  report — treat any non-zero exit as data, not failure.
+- `bun audit` exits non-zero when it *finds* advisories but still writes the
+  payload to stdout, so a non-zero exit **with output** is data. A non-zero exit
+  with **no** output — or a launch failure, timeout, or a blown 32MB buffer —
+  throws, precisely so a failed run can't masquerade as "0 advisories".
 
 ## Console integration (@pikku/addon-console)
 
 Three RPCs, all reading/writing the same artifact via the meta service. Shared
 spawn/read helpers live in `lib/audit-exec.ts` (`readAuditReport`,
-`runPikkuAudit`, `spawnProcess`, `findBin`) — reuse them, don't re-implement.
+`runPikkuAudit`, `spawnProcess`, `findBin`), alongside `lib/find-project-root.ts`
+and `lib/resolve-package-manager.ts` (`resolvePackageManager`, `installArgs`,
+`execPrefix`) — reuse them, don't re-implement. `resolvePackageManager` reads
+package.json's corepack `packageManager` field first and only falls back to
+lockfiles, because that field states intent before a lockfile exists and a
+project can carry a stale one from another tool. Guessing wrong is not a soft
+failure: the spawn dies with `Executable not found in $PATH`.
 Like every console RPC these require an **authenticated session** (the console
 is admin-only), so the host must have Better Auth wired — see `pikku-better-auth`.
 
@@ -84,15 +94,26 @@ is admin-only), so the host must have Better Auth wired — see `pikku-better-au
 
 ```ts
 {
+  schemaVersion: number
   tool: string                 // e.g. 'bun'
+  generatedAt: string          // ISO timestamp
   note?: string                // set when the audit could NOT run (unsupported PM);
                                // render ONLY the note — never a reassuring "no vulnerabilities"
-  summary: { critical, high, moderate, low, info: number }
-  issues: SecurityAuditIssue[] // package, severity, title, advisoryId, cwe[], cvssScore?,
-                               // url?, vulnerableVersions, recommendedVersion?
+  summary: {
+    totalIssues, critical, high, moderate, low: number   // no `info` bucket
+    totalUpdates, major, minor, patch: number
+  }
+  issues: SecurityAuditIssue[] // package, severity, title, advisoryId, url,
+                               // vulnerableVersions, cwe[], cvssScore, recommendedVersion
   updates: SecurityAuditUpdate[] // package, current, latest, level (major|minor|patch|unknown)
 }
 ```
 
+`severity` is one of `critical | high | moderate | low | info`, but `summary`
+has no `info` count — an informational advisory raises `totalIssues` without
+landing in a severity bucket, so don't sum the four to get the total. On an
+issue, `url`, `cvssScore` and `recommendedVersion` are always present and
+**nullable** rather than optional: check for `null`, not `undefined`.
+
 When `note` is present the audit did not run — show only the note (an "Audit not
 run" state), never the "no known vulnerabilities / up to date" copy.

package/skills/pikku-emails/SKILL.md

@@ -23,7 +23,8 @@ generated output is never edited by hand.
 
 ## Agent Operating Procedure
 
-1. Edit source files under `emailTemplatesDir` only. Never edit `.pikku/email/*`.
+1. Edit source files under `emailTemplatesDir` only. Never edit `.pikku/email/*`. If the
+   directory does not exist yet, run `pikku emails init` rather than creating it by hand.
 2. After any change run `pikku emails generate` (it is also part of `prebuild`, usually
    `pikku bootstrap; pikku all; pikku emails generate`).
 3. Validate by importing `renderEmailTemplate` and rendering with sample data, or run the
@@ -40,7 +41,14 @@ generated output is never edited by hand.
 }
 ```
 
-If `emailTemplatesDir` is unset the command is a no-op.
+If `emailTemplatesDir` is unset the command is a no-op — it logs
+`Skipping emails (set emailTemplatesDir in pikku.config.json to enable).` and exits
+cleanly, so a silent generate is a config problem, not a template problem.
+
+`pikku emails init` scaffolds the directory (starter locales, theme, partials and a
+hello-world template) **and** writes `emailTemplatesDir` into `pikku.config.json` for
+you. Use it rather than hand-creating the tree; `--force` overwrites an existing
+scaffold.
 
 ## Directory layout
 
@@ -97,8 +105,17 @@ import {
 //   { appName?: ...; inviteUrl?: ...; inviterName?: ...; organizationName?: ... }
 ```
 
-To make a variable required-and-typed, reference it directly in the template body (not
-only in a locale string), so it shows up as that template's variable.
+Every extracted variable is emitted **optional** and typed `EmailTemplateValue`
+(`string | number | boolean | null | undefined | object | array`). The type tells you
+which variables a template can consume, not which ones it needs — there is no way to
+mark one required, and a template that references none types as `Record<string, never>`.
+Referencing a variable in the template body (rather than only in a locale string) is
+what gets it into the type at all.
+
+That matters because a placeholder with nothing behind it renders as the **empty
+string** — no error, no leftover `{{…}}`. A typo'd variable name, a missing `data` key
+and a value that isn't a string or number all produce the same silently blank output, so
+render with sample data and read the result rather than trusting that it compiled.
 
 ## Rendering
 
@@ -111,7 +128,17 @@ const rendered = renderEmailTemplate({
 // rendered: { name, locale, subject, html, text?, variables, hash }
 ```
 
+It is synchronous, and it throws on an unknown template name or an unknown locale —
+those are the only two failure modes; everything else degrades to blank output.
+
 `hash` is a stable content hash (useful as an idempotency / dedupe key on outgoing mail).
+The meta file also carries per-locale `htmlHash` / `subjectHash` / `textHash` if you need
+to tell which part changed.
+
+`{{locale}}` is in scope alongside `{{appName}}`, and placeholders are resolved by
+repeated passes so a locale string containing `{{verifyUrl}}` expands. The loop stops
+after 5 passes, which only becomes visible with placeholders nested more deeply than
+that — a shape worth avoiding rather than working around.
 
 ## Sending through an EmailService
 
@@ -160,4 +187,8 @@ async send(input: SendEmailInput) {
   reference it in this template to scope it in.
 - Editing a locale string changes that template's content hash — expected; the hash covers
   the strings the template uses.
-- `layout.html` must contain `{{content}}` or the body is dropped.
+- `layout.html` must contain `{{content}}` or the body is dropped. It is matched by the
+  partial name `layout`, so renaming the file opts every template out of the wrapper.
+- A blank spot where a value should be is an unresolved placeholder, not a render
+  failure — check the key's spelling and that the value is a string or number (objects
+  and arrays resolve to empty).

package/skills/pikku-fabric/SKILL.md

@@ -96,6 +96,25 @@ Run migrations: `pikku db migrate`. It also regenerates `.pikku/db/schema.gen.ts
 
 **NEVER hand-edit the generated schema** — write a migration and re-run.
 
+### Dev seed data
+
+Alongside the migrations sits `db/<engine>-dev-seed.sql` — `db/sqlite-dev-seed.sql`
+or `db/postgres-dev-seed.sql`. There is no seed command. `pikku db reset` is the
+only thing that applies it: wipe, migrate, seed. `--no-seed` stops after the
+migration, for working on an empty-state or onboarding flow the test data hides.
+
+Because reset always arrives at a database it has just wiped, **the seed file is
+plain `INSERT`s** — no `INSERT OR IGNORE`, no `ON CONFLICT DO NOTHING`, no
+`IF NOT EXISTS`. Nothing applies it twice, so it never has to defend itself. If
+you find yourself reaching for an idempotent form, that's a sign the data wants
+to be a migration instead.
+
+This is **test data only**: enough rows that a fresh dev database isn't an empty
+app. It never reaches staging or production — reset refuses `NODE_ENV=production`
+and refuses a database outside the runtime directory. Anything a real environment
+needs — accounts, role grants — is provisioning, not seeding, and belongs in
+`pikku persona sync` or a migration.
+
 A Better Auth app has a second constraint: the plugins you enable (`admin()`,
 `actor()`, …) each declare columns, and `pikku db migrate` refuses to run while
 the applied schema is missing any of them. `pikku db generate` writes the
@@ -143,7 +162,7 @@ packages/functions/
       *.channel.ts     # wireChannel
       *.queue.ts       # wireQueueWorker
       *.schedule.ts    # wireScheduler
-      *.mcp.ts         # wireMCPTool
+      *.mcp.ts         # wireMCPResource / wireMCPPrompt (an MCP tool is just a function with `mcp: true`)
       *.cli.ts         # wireCLI
     services.ts        # pikkuServices factory (singleton)
     middleware.ts      # Shared middleware
@@ -152,6 +171,7 @@ packages/functions/
     db/schema.gen.ts   # Kysely types, written by `pikku db migrate` — NEVER hand-edit
 apps/app/              # Frontend(s)
 db/sqlite/             # Plain .sql migrations, numbered, gap-free (project root)
+db/sqlite-dev-seed.sql # Dev-only test data, applied by `pikku db reset`
 pikku.config.json      # Pikku + deploy config (project root)
 pikkufabric.config.json # Fabric project link + frontends (project root)
 ```
@@ -189,6 +209,11 @@ Links the repo to a Fabric project and declares its frontends:
   without a domain it lives on the platform `*.pikkufabric.app` hostnames.
 - `frontends`: each entry declares a frontend app with its dev command and port
 
+Several CLI messages call this file `fabric.config.json` — `fabric init --force`,
+`fabric link --apiUrl`, and the `domains` commands' "No fabric.config.json found".
+The file the CLI actually reads and writes is `pikkufabric.config.json`; don't
+create the shorter name to satisfy an error message.
+
 ## RPC is the default transport
 
 In Fabric apps, most features don't need HTTP wirings. Just write the function with `expose: true` — Pikku generates an RPC client and React Query hooks automatically.
@@ -313,6 +338,6 @@ Fix every `error` and `warn` in the output before continuing. Then:
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
 4. **Replace `process.env` calls**: plain config becomes `defineVariable` + `variables.get()`, anything sensitive becomes `defineSecret` + `secrets.getSecret()`.
 5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles`.
-6. **Add `fabric.config.json`** at project root with `projectId`, `production.branch`, and `frontends`.
+6. **Add `pikkufabric.config.json`** at project root with `projectId`, `production.domain`, and `frontends` (production is always `main`, so there is no `production.branch`).
 7. **Run `pikku all`** — verify codegen succeeds and there are no type errors.
 8. **Run `pikku fabric validate`** once more to confirm no structural issues remain.

package/skills/pikku-fabric-debug/SKILL.md

@@ -63,6 +63,8 @@ pikku fabric metrics -b main                       # last 24h
 pikku fabric metrics -b main --hours 2 --function createOrder
 ```
 
+`--branch` is **required** here too; `--hours` defaults to 24.
+
 Rows are `reqs= err= (rate%) avg= min= max=` per bucket. A single bad request
 with a healthy error rate is a data problem; a climbing error rate is a
 deployment or dependency problem. `--json` additionally returns a `wireTypes`
@@ -95,7 +97,9 @@ deploy stuck in flight, explains a whole class of "my fix did nothing".
   `--since 15m` silently returns the same default window as no flag at all. Do
   not conclude "nothing happened in the last 15 minutes" from it. Narrow by
   `--level`, or by `--function` via `errors`, instead.
-- **`--follow` is a 2-second client-side poll, not a server stream.** It
+- **`--follow` is a 2-second client-side poll, not a server stream** — despite
+  its own help text reading "Stream new logs (SSE)". Server-side SSE is planned;
+  the backend doesn't push natively today. It
   dedups against what it already printed, so it behaves like `tail -f`, but new
   entries can appear up to ~2s late and it holds the process open until killed.
 

package/skills/pikku-feature/SKILL.md

@@ -218,10 +218,15 @@ branch.
 ## Stage 6 — Commit
 
 ```bash
-git add -A
+git add <the files you changed>
 git commit -m "feat: <short title>"
 ```
 
+Stage the files you actually touched, by path. `git add -A` / `git add .` also
+sweeps up regenerated artifacts you didn't mean to commit and, where more than
+one agent shares the checkout, another agent's in-progress work — which lands in
+your branch and silently breaks theirs.
+
 ## Stage 7 — Hand off
 
 Tell the user the branch name and how to review. Two options:

package/skills/pikku-gateway-slack/SKILL.md

@@ -35,24 +35,67 @@ yarn add @pikku/gateway-slack @slack/web-api
 ```typescript
 import { SlackGatewayAdapter } from '@pikku/gateway-slack'
 
-const adapter = new SlackGatewayAdapter(options: SlackGatewayAdapterOptions)
+const adapter = new SlackGatewayAdapter({
+  signingSecret: string,
+  tokenResolver: (teamId: string) => Promise<string | null>,
+})
 ```
 
 Bridges Slack Events API webhooks with Pikku's gateway system for processing Slack events as Pikku functions.
 
+**There is no `botToken` option.** One adapter serves every workspace, and the
+bot token is resolved per `team_id` through `tokenResolver` — normally a lookup
+against the row `exchangeSlackOAuthCode` wrote at install time. Returning `null`
+throws for that event. `WebClient`s are cached per team, so call
+`invalidateClient(teamId)` after a token rotation.
+
+**Methods:**
+
+- `verifyWebhook(data, request?)` — asserts the signature, then answers the `url_verification` challenge. It **fails closed**: no request access, missing headers, a stale timestamp, or an HMAC mismatch all throw `UnauthorizedError` before parse or the handler runs
+- `parse(data)` — normalizes an `event_callback` into a `GatewayInboundMessage`, or returns `null` for anything to ignore
+- `createBoundSend(teamId, channelId, threadTs?)` — the real send path
+- `send(senderId, message)` — **a deliberate no-op.** The generic signature carries no channel context, and the gateway runner calls it for auto-send, so it swallows rather than throws. A reply written through it silently never reaches Slack
+- `getClientForTeam(teamId)` / `invalidateClient(teamId)` / `close()`
+
+`parse` returns `null` — meaning the event is dropped — for anything that isn't a
+`message` or `app_mention`, for bot messages (loop prevention), for any subtype
+other than `thread_broadcast`, and for events with no `user` or no `text`.
+`metadata` carries `{ teamId, channelId, threadTs, messageTs, eventType }`, with
+`threadTs` falling back to the message's own `ts` so replies always land
+in-thread.
+
 ### `SlackGatewayHelper`
 
-Helper for handling Slack messages and metadata within gateway functions.
+Wraps a parsed message plus the adapter and binds the channel/thread for you:
+
+```typescript
+const slack = new SlackGatewayHelper(data, adapter)
+await slack.sendText('Thinking…') // sends now
+return slack.reply('Here is the answer') // auto-sent by the runner
+```
+
+Also: `send(message)`, `replyBlocks(blocks)`, and the `channelId` / `threadTs` /
+`teamId` getters.
 
 ### Slash Commands
 
 ```typescript
 import { parseSlashCommand, respondToSlashCommand } from '@pikku/gateway-slack'
 
-const command = parseSlashCommand(request)
-await respondToSlashCommand(responseUrl, { text: 'Done!' })
+const command = parseSlashCommand(data)
+// { raw, subcommand, args, argsList, teamId, userId, channelId, triggerId, responseUrl }
+await respondToSlashCommand(command.responseUrl, { text: 'Done!' })
 ```
 
+The parsed result is camelCase — reach for `command.responseUrl`, not
+`command.response_url`; the underlying snake_case payload is on `command.raw`.
+`text` is split on whitespace: the first word becomes `subcommand`, the rest
+`args`/`argsList`.
+
+`respondToSlashCommand` posts to the `response_url` and **ignores the result** —
+a rejected response is invisible. Use it for the delayed reply when work exceeds
+Slack's 3-second acknowledgement window.
+
 ### OAuth Flow
 
 ```typescript
@@ -81,9 +124,19 @@ const tokens = await exchangeSlackOAuthCode({
 ```typescript
 import { verifySlackSignature } from '@pikku/gateway-slack'
 
-verifySlackSignature(signingSecret, timestamp, body, signature)
+verifySlackSignature(signingSecret, signature, timestamp, body): boolean
 ```
 
+**Signature before timestamp** — the two middle arguments are both strings, so
+swapping them compiles and simply never verifies. `signature` is the raw
+`x-slack-signature` header (`v0=…`), `timestamp` is `x-slack-request-timestamp`
+in Unix seconds, and `body` must be the **raw** request body: any re-serialization
+changes the HMAC.
+
+It returns `false` rather than throwing, including for a timestamp more than 5
+minutes off (replay protection). The adapter already calls this for you — reach
+for it directly only outside the gateway path, e.g. in a slash-command route.
+
 ## Usage Patterns
 
 ### Slack Bot Gateway
@@ -93,22 +146,30 @@ import { SlackGatewayAdapter } from '@pikku/gateway-slack'
 
 const slackGateway = new SlackGatewayAdapter({
   signingSecret: config.slackSigningSecret,
-  botToken: config.slackBotToken,
+  tokenResolver: async (teamId) => {
+    const row = await kysely
+      .selectFrom('slackInstall')
+      .select('botToken')
+      .where('teamId', '=', teamId)
+      .executeTakeFirst()
+    return row?.botToken ?? null
+  },
 })
-
-// Register with your HTTP runner to handle /slack/events endpoint
 ```
 
 ### Slash Command Handler
 
+Slack gives you 3 seconds to acknowledge, so anything slower answers immediately
+and posts the real result to `responseUrl` afterwards:
+
 ```typescript
 const handleSlashCommand = pikkuSessionlessFunc({
   title: 'Handle Slack Command',
   func: async ({ db }, data) => {
     const command = parseSlashCommand(data)
-    // Process command...
-    await respondToSlashCommand(command.response_url, {
-      text: `Processed: ${command.text}`,
+    await respondToSlashCommand(command.responseUrl, {
+      text: `Processed: ${command.args}`,
+      response_type: 'ephemeral',
     })
   },
 })

package/skills/pikku-http/SKILL.md

@@ -38,8 +38,13 @@ Follow existing patterns you find (naming, tag usage, file organization). See `p
 
 ## API Reference
 
-- `wireHTTP(config)` (from `@pikku/core/http`) — wire one function to one endpoint.
-- `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)` (from `.pikku/pikku-types.gen.js`) — group routes with shared config; composable/nestable.
+All three come from `#pikku` (the generated `.pikku/pikku-types.gen.js`), which
+binds them to your project's service, session and middleware types. The
+`@pikku/core/http` versions are the unbound generics — they compile, but you
+lose the typing that makes the wiring worth having.
+
+- `wireHTTP(config)` — wire one function to one endpoint.
+- `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)` — group routes with shared config; composable/nestable.
 
 Function input/output types come from the function's own `input:`/`output:` zod schemas — never declared in the wiring. Route `:params`, query params, and body are merged into the function's `data` arg (see Data Flow).
 
@@ -144,6 +149,9 @@ wireHTTP({
 
 ### SSE (Server-Sent Events)
 
+`sse: true` is only accepted on `method: 'get'` — the wiring union offers it on
+no other verb.
+
 ```typescript
 wireHTTP({
   method: 'get',
@@ -154,7 +162,7 @@ wireHTTP({
 
 const getTodos = pikkuFunc({
   title: 'Get Todos',
-  func: async ({ db, channel }, {}) => {
+  func: async ({ db }, {}, { channel }) => {
     const todos = await db.getTodos()
 
     if (channel) {
@@ -170,12 +178,17 @@ const getTodos = pikkuFunc({
 })
 ```
 
+`channel` is on the **wire** — the func's third argument — not on services, and
+it is optional because the same function can be reached over plain HTTP or RPC,
+where there is no stream to send on. The `if (channel)` guard is what lets one
+function serve both; the return value is the non-streaming answer.
+
 ### Generated Fetch Client
 
 After `npx pikku all`, a type-safe client is generated:
 
 ```typescript
-import { pikkuFetch } from '.pikku/pikku-fetch.gen.js'
+import { pikkuFetch } from '#pikku/pikku-fetch.gen.js'
 
 pikkuFetch.setServerUrl('http://localhost:4002')
 
@@ -213,7 +226,7 @@ export const getBook = pikkuFunc({
 })
 
 // wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
-import { addHTTPMiddleware } from '@pikku/core/http'
+import { addHTTPMiddleware } from '#pikku'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])

package/skills/pikku-http/references/http-options.md

@@ -2,25 +2,30 @@
 
 ## `wireHTTP(config)`
 
-Wire a single function to an HTTP endpoint. Import from `@pikku/core/http`.
+Wire a single function to an HTTP endpoint. Import from `#pikku`.
 
 | Option | Type | Notes |
 | --- | --- | --- |
-| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head'` | HTTP verb |
+| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head' \| 'options'` | HTTP verb |
 | `route` | `string` | e.g. `/books/:bookId` — `:params` become `data` fields |
 | `func` | `PikkuFunc` | The function to call |
 | `auth?` | `boolean` | Override default auth (`true` = require session) |
 | `tags?` | `string[]` | For grouping, middleware targeting |
 | `middleware?` | `PikkuMiddleware[]` | Per-route middleware |
-| `sse?` | `boolean` | Enable Server-Sent Events |
+| `sse?` | `boolean` | Enable Server-Sent Events — **`method: 'get'` only** |
+| `query?` | `Array<keyof In>` | **`method: 'post'` only** — input fields also read from the query string |
 | `contentType?` | `'xml' \| 'json'` | Response content type |
 | `timeout?` | `number` | Request timeout in ms |
 | `headers?` | `HTTPHeadersSchema` | Expected headers schema |
-| `docs?` | `HTTPRouteDocsConfig` | OpenAPI docs config |
+
+`sse` and `query` are constrained by the config union rather than by a runtime
+check, so a `sse: true` on a `post` fails to typecheck rather than silently
+serving a normal response. OpenAPI metadata is not declared here — it is derived
+from the function's `description`/`summary` and its input/output schemas.
 
 ## `defineHTTPRoutes(config)` + `wireHTTPRoutes(config)`
 
-Group routes with shared configuration. Groups are composable and nestable. Import from `.pikku/pikku-types.gen.js`.
+Group routes with shared configuration. Groups are composable and nestable. Import from `#pikku`.
 
 ```typescript
 const routes = defineHTTPRoutes({

package/skills/pikku-i18n/SKILL.md

@@ -56,18 +56,18 @@ function LoginPage() {
 
 ## Keys only known at runtime (enum labels, status maps)
 
-A DB value picking a label (`enums__document_status__${status}`) is the one case a
-generated message can't express. Paraglide's README (§ "What about dynamic or
-CMS-driven keys?") is explicit: use an **explicit mapping from value to message
-function**. Key it on the enum type, never `string`:
+A DB value picking a label is the one case a generated message can't express.
+Paraglide's README (§ "What about dynamic or CMS-driven keys?") is explicit: use
+an **explicit mapping from value to message function**. Key it on the enum type,
+never `string`:
 
 ```ts
 import { m } from '../paraglide/messages.js'
 
 const DOCUMENT_STATUS_LABEL: Record<DocumentStatus, () => string> = {
-  completed: m.enums__document_status__completed,
-  in_progress: m.enums__document_status__in_progress,
-  required: m.enums__document_status__required,
+  completed: m.enum__document_status__completed,
+  in_progress: m.enum__document_status__in_progress,
+  required: m.enum__document_status__required,
 }
 
 // call site — no fallback, because there is no missing case
@@ -77,6 +77,13 @@ DOCUMENT_STATUS_LABEL[status]()
 `Record<DocumentStatus, …>` is exhaustive: add a value to the enum without a
 label and the build fails. That is the entire point.
 
+**Don't write these maps by hand.** `@pikku/paraglide` generates them from the
+`enum__<group>__<member>` keys in the catalog and types each one against the DB
+enum it mirrors, so a migration adding a status is a compile error rather than a
+map someone forgot. Use the namespace above (singular `enum`, `__` between
+segments) so the generator picks the group up, and read `pikku-paraglide` before
+adding one.
+
 Do NOT write `Record<string, () => string>` with a `?? status` fallback, and do
 NOT index the namespace with a computed key (`m[\`enums__${name}__${value}\`]`).
 Both compile, both render the raw identifier to users when a label is missing,
@@ -132,6 +139,10 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 - Don't hardcode display strings "just for now" — the message is the work.
 - 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.
+
+  `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.
 - Don't reach for i18next/react-i18next or a runtime-fetch translation loader — Paraglide's compiled functions are the whole delivery mechanism.
 - Don't tokenize backend error messages or logs here — those are not frontend display strings.

package/skills/pikku-info/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: pikku-info
 description: >-
-  Discover what exists in a Pikku project — functions, tags, middleware, permissions, HTTP routes,
-  channels, schedulers, queues, and more. Use when you need to understand the project structure,
-  find existing functions, or check what middleware and permissions are defined. TRIGGER when:
-  user asks "what functions exist?", "show me the project structure", "list
+  Discover what exists in a Pikku project — functions (with their transport, middleware and
+  permissions), tags, middleware and permission definitions. Use when you need to understand the
+  project structure, find existing functions, or check what middleware and permissions are
+  defined. TRIGGER when: user asks "what functions exist?", "show me the project structure", "list
   routes/middleware/permissions", or needs to understand an existing Pikku codebase. DO NOT
   TRIGGER when: user is writing new code (use the specific wiring skill) or asking about Pikku
   concepts (use pikku-concepts).
@@ -27,9 +27,19 @@ Use this skill as an execution checklist, not reference material.
 
 Use the `pikku info` CLI commands to inspect this Pikku project. Run the commands below and present the results to the user in a clear summary.
 
+There are exactly four subcommands — `functions`, `tags`, `middleware`,
+`permissions`. Routes, channels, schedulers and queues are not separate
+subcommands; they show up as the *transport* column of `info functions --verbose`.
+
 ## Available Commands
 
-Always use `--silent` to suppress the banner and inspector logs.
+`--silent` suppresses the banner and the inspector's diagnostics, which is what
+you want when parsing the table. It is read by the CLI but not declared as an
+option, so every run also prints `Warning: Unknown option: --silent (ignored)` —
+the warning is wrong, the flag works. Ignore that one line.
+
+For anything you intend to parse rather than read, prefer `--json` (alias
+`-j`, or `--output json`), which emits NDJSON instead of a formatted table.
 
 ### Functions
 
@@ -91,9 +101,9 @@ yarn pikku info permissions --verbose --silent
 
 1. If the user specifies a subcommand (e.g., `/pikku-info functions`), run only that command.
 2. If no subcommand is specified, run all four commands to give a complete project overview.
-3. Always use `--silent` to suppress the Pikku banner and inspector logs.
-4. Use `--verbose` when the user asks for details, file paths, or "more info".
-5. Use `--limit N` to control output size (default is 50 rows).
+3. Always use `--silent` to suppress the Pikku banner and inspector logs, and disregard the spurious "Unknown option" warning it prints.
+4. Use `--verbose` when the user asks for details, file paths, or "more info". On `tags` it swaps counts for names; elsewhere it adds columns.
+5. Use `--limit N` to control output size (default is 50 rows) — the footer tells you how many were withheld.
 6. After running the commands, summarize the findings concisely:
    - Total count of functions, tags, middleware, and permissions
    - Notable patterns (e.g., which transport types are in use, which tags group the most functions)