@pikku/skills 0.12.2 → 0.12.6

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

@@ -55,15 +55,37 @@ await appServer.start()
 
 **Methods:**
 
-- `init(httpOptions?): Promise<void>` — Register middleware and routes
+- `init(httpOptions?: RunHTTPWiringOptions): Promise<void>` — installs the body parsers, the cookie parser and the Pikku middleware
 - `start(): Promise<void>` — Start listening
-- `stop(): Promise<void>` — Graceful shutdown
-- `enableExitOnSigInt(): Promise<void>` — SIGINT handler
+- `stop(): Promise<void>` — Graceful shutdown; throws if the server was never started
+- `enableExitOnSigInt(): Promise<void>` — SIGINT handler: stops the singleton services, then the server, then exits 0
 - `enableCors(options): void` — Enable CORS
-- `enableStaticAssets(): void` — Serve static files (requires `content` config)
+- `enableStaticAssets(): void` — serve `content.localFileUploadPath` under `content.assetUrlPrefix`
+- `enableReaper(): void` — a `PUT /reaper/*path` upload sink for local development, path-traversal checked and bounded by `content.sizeLimit` (default `1mb`)
+- `getHttpServer(): Server` — the underlying `http.Server`, e.g. to attach a WebSocket server; throws before `start()`
+
+`enableStaticAssets` and `enableReaper` both throw when `content` is unset.
 
 **Property:** `app: Express` — Direct access to Express instance for custom middleware.
 
+### Ordering, and what `init` installs for you
+
+The health check is registered in the **constructor**, so it answers before any
+middleware you add and cannot be wrapped in auth. It defaults to
+`/health-check`; override with `healthCheckPath`.
+
+Everything else is installed by `init()`: `express.json`, `express.text` (for
+`text/xml`), `express.urlencoded`, `cookie-parser`, then the Pikku middleware.
+Call `enableCors` **before** `init` if you want CORS applied to Pikku's routes.
+
+Express buffers the body before Pikku sees it, so the parser limit is the only
+place an oversized request can actually be stopped. `httpOptions.maxBodySize`
+therefore feeds those parser limits, with an explicit `config.limits` entry
+(`json` / `xml` / `urlencoded`) still winning. Everything defaults to `1mb`.
+
+`init` passes `logRoutes: true` and `loadSchemas: true` by default; your
+`httpOptions` spread over them, so you can turn either off.
+
 ## Middleware (existing Express app)
 
 ```bash
@@ -76,11 +98,25 @@ import { pikkuExpressMiddleware } from '@pikku/express-middleware'
 import './.pikku/pikku-bootstrap.gen.js'
 
 const app = express()
+app.use(express.json())
+app.use(cookieParser())
 app.use(
   pikkuExpressMiddleware({
     logger: singletonServices.logger,
     logRoutes: true,
     loadSchemas: true,
+    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, coerceDataFromSchema
   })
 )
 ```
+
+Options beyond `logger` are all optional: `logRoutes` logs the wiring table once
+at startup, `loadSchemas` compiles every schema up front, and the rest are
+`RunHTTPWiringOptions` passed through per request.
+
+On your own app **you** own the parser stack — the middleware reads
+`req.body`, so a body parser and `cookie-parser` must be registered before it,
+and `maxBodySize` alone will not stop an oversized request that your parser
+already accepted. Unmatched requests fall through to `next()` (unless
+`respondWith404` is set), so Pikku's routes coexist with your existing ones;
+a streaming response is the exception and does not call `next()`.

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

@@ -47,10 +47,19 @@ 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: FastifyInstance` — Direct access to Fastify instance.
 
+`enableCors` exists on the class but **throws `Method not implemented.`** — unlike
+the Express server. Register `@fastify/cors` on `app` yourself before `init()`.
+
+Unlike the Express server, the health check is registered by `init()`, not the
+constructor, so nothing answers before `init` runs. `init` also passes
+`logRoutes: true` and `loadSchemas: true`, which your `httpOptions` can override.
+The Fastify instance is constructed with no options; reach for the plugin package
+if you need `Fastify({ … })` of your own.
+
 ## Plugin (existing Fastify app)
 
 ```bash
@@ -68,6 +77,18 @@ app.register(pikkuFastifyPlugin, {
     logger: singletonServices.logger,
     logRoutes: true,
     loadSchemas: true,
+    // plus any RunHTTPWiringOptions: maxBodySize, respondWith404, …
   },
 })
 ```
+
+Every option other than `logger` is optional, and the rest of the `pikku` object
+is `RunHTTPWiringOptions` passed straight through.
+
+The plugin registers a catch-all `fastify.all('/*')`, so mount it on a
+[Fastify prefix](https://fastify.dev/docs/latest/Reference/Plugins/) if the app
+has routes of its own to keep.
+
+Fastify buffers the body itself, so its `bodyLimit` is where an oversized request
+is stopped. `maxBodySize` sets it — and left unset, Fastify's stricter 1MB default
+stands rather than being loosened to Pikku's 10MB fallback.

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

@@ -44,30 +44,75 @@ export const coldStart = async () => {
 }
 ```
 
+If the deploy codegen generated your handlers, this caching is already done for
+you by the factories in `@pikku/lambda` — `createLambdaHandler(factories,
+handlerTypes)`, `createLambdaWorkerHandler(factories)` and
+`createLambdaWebSocketHandler(factories)`. They build `variables`/`secrets` from
+`process.env`, cache the singleton services in module scope, and return the
+named exports (`handler`, `queue`, `scheduled`, or `connect`/`disconnect`/
+`default`) that `serverless.yml` references. Hand-written handlers are for cases
+the codegen does not cover.
+
 ## HTTP Handler
 
+Pick the entry point that matches the API Gateway payload version — they take
+different event types and are not interchangeable:
+
 ```typescript
-import type { APIGatewayProxyEvent } from 'aws-lambda'
-import { runFetch } from '@pikku/lambda/http'
+import type { APIGatewayEvent } from 'aws-lambda'
+import { runFetch } from '@pikku/lambda/http' // REST API / payload v1
 
-export const httpRoute = async (event: APIGatewayProxyEvent) => {
+export const httpRoute = async (event: APIGatewayEvent) => {
   await coldStart()
   return await runFetch(event)
 }
 ```
 
+```typescript
+import type { APIGatewayProxyEventV2 } from 'aws-lambda'
+import { runFetchV2 } from '@pikku/lambda/http' // HTTP API / payload v2
+
+export const httpRoute = async (event: APIGatewayProxyEventV2) => {
+  await coldStart()
+  return await runFetchV2(event)
+}
+```
+
+Both answer `OPTIONS` themselves before Pikku's wirings run, so a preflight
+never reaches your middleware. Only `runFetchV2` echoes the request `Origin`
+into `Access-Control-Allow-Origin`; `runFetch` sets allowed headers and methods
+but **no origin header at all**, so v1 preflights fail in the browser unless
+API Gateway or a CloudFront layer adds one.
+
+They also differ on failure: `runFetchV2` logs and returns a JSON `500`, while
+`runFetch` swallows the error and returns whatever status the response already
+carried.
+
+Neither takes `RunHTTPWiringOptions` — there is no `maxBodySize` or
+`respondWith404` knob here; API Gateway's own payload limit is the bound.
+
 ## Scheduled Tasks
 
 ```typescript
 import type { ScheduledHandler } from 'aws-lambda'
-import { runScheduledTask } from '@pikku/core/scheduler'
+import { runLambdaScheduled } from '@pikku/lambda/scheduled'
 
-export const myScheduledTask: ScheduledHandler = async () => {
+export const scheduled: ScheduledHandler = async (event) => {
   await coldStart()
-  await runScheduledTask({ name: 'myScheduledTask' })
+  await runLambdaScheduled(event)
 }
 ```
 
+`runLambdaScheduled` runs **every** scheduled task registered in the bundle,
+each with its own `cron-<uuid>` traceId, and logs rather than rethrows a task
+failure — so one bad task cannot fail the invocation or stop the others. The
+event itself is ignored; which tasks run is decided by what the unit bundled,
+not by which EventBridge rule fired.
+
+Reach for `runScheduledTask({ name })` from `@pikku/core/scheduler` directly
+only when one Lambda genuinely bundles several tasks that must fire on separate
+schedules.
+
 ## SQS Queue Worker
 
 ```typescript
@@ -80,6 +125,25 @@ export const mySQSWorker: SQSHandler = async (event) => {
 }
 ```
 
+The worker returns an `SQSBatchResponse` listing the failed messages in
+`batchItemFailures`, which SQS only honours when the event source mapping has
+**`ReportBatchItemFailures`** enabled. Without it the whole batch is retried
+when any one message fails, so successfully processed jobs run twice.
+
+Records are processed in parallel, and the queue name is taken from the last
+segment of `eventSourceARN` — it must match the name the worker was wired under.
+A `QueueJobDiscardedError` counts as success (no retry); anything else is
+reported as a failed item.
+
+`waitForCompletion` throws on an SQS job: the transport is fire-and-forget.
+
+On the producer side, `SQSQueueService` resolves each queue URL from the
+constructor's `queueUrlMap` first, then from
+`SQS_QUEUE_URL_<SCREAMING_SNAKE_NAME>`, and throws naming the missing variable
+if neither has it. `supportsResults` is `false` and `getJob()` always throws —
+use BullMQ or PgBoss if you need results. `delay` is milliseconds, rounded up to
+whole seconds and capped at SQS's 900s ceiling.
+
 ## WebSocket (API Gateway v2)
 
 ```typescript
@@ -90,21 +154,37 @@ import {
   LambdaEventHubService,
 } from '@pikku/lambda/websocket'
 
-export const connectHandler = async (event) => {
-  const params = await getParams(event)
-  await connectWebsocket(event, params)
-  return { statusCode: 200, body: '' }
+const params = async (event) => {
+  const { channelStore } = await coldStart()
+  return { channelStore }
 }
 
-export const disconnectHandler = async (event) => {
-  const params = await getParams(event)
-  return await disconnectWebsocket(event, params)
-}
+export const connectHandler = async (event) =>
+  await connectWebsocket(event, await params(event))
 
-export const defaultHandler = async (event) => {
-  const params = await getParams(event)
-  return await processWebsocketMessage(event, params)
-}
+export const disconnectHandler = async (event) =>
+  await disconnectWebsocket(event, await params(event))
+
+export const defaultHandler = async (event) =>
+  await processWebsocketMessage(event, await params(event))
 ```
 
-WebSocket requires a `ChannelStore` (e.g., `PgChannelStore`) and `LambdaEventHubService` for cross-connection messaging.
+All three take the same `{ channelStore }` and **return a complete
+`APIGatewayProxyResult`** — return it. Discarding `connectWebsocket`'s result
+and answering a hardcoded `200` accepts every connection, including the ones
+your channel's auth rejected.
+
+`channelStore` (e.g. `PgChannelStore`) must be a real shared store: each route
+is a separate invocation, so nothing survives in memory between `$connect` and
+`$default`.
+
+`LambdaEventHubService` handles cross-connection messaging and takes
+`(logger, event, channelStore, eventHubStore)` — the `event` is needed to derive
+the API Gateway Management endpoint, so it is constructed per invocation, not
+once at cold start. It also needs an `EventHubStore` alongside the channel
+store.
+
+Two behaviours to design around: **binary payloads throw** (`Binary data is not
+supported on serverless lambdas`), and any `PostToConnection` failure removes
+the connection from the channel store — a transient error drops a live client,
+not just a stale one.

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

@@ -38,6 +38,17 @@ export const PATCH = pikkuAPIRequest
 export const DELETE = pikkuAPIRequest
 ```
 
+`pikkuAPIRequest` strips a leading `/api` from the pathname before routing, so
+wirings are declared as `/todos`, not `/api/todos`, even though the route file
+lives under `app/api`. Turn that off with `removeAPIPrefix(false)` from the same
+generated file if your wirings really do carry the prefix.
+
+It takes `(req, context)` to match Next's handler signature but ignores the
+context — Pikku routes from the URL, so the catch-all segment name is yours to
+choose. It also passes no `RunHTTPWiringOptions`: to set `maxBodySize` or
+`respondWith404` you need your own handler over `new PikkuNextJS(...)` calling
+`apiRequest(req, options)`.
+
 ## Server-Side Data Fetching
 
 Use the generated `pikku()` helper in Server Components or Server Actions:
@@ -45,7 +56,7 @@ Use the generated `pikku()` helper in Server Components or Server Actions:
 ```typescript
 import { pikku } from '@/pikku-nextjs.gen.js'
 
-const { get, post, del, rpc, staticGet, staticPost, staticRPC } = pikku()
+const { get, post, patch, del, rpc, staticGet, staticPost, staticRPC } = pikku()
 
 // Dynamic (reads headers/cookies — requires request context)
 const todos = await get('/todos')
@@ -60,8 +71,19 @@ const result = await rpc('calculateTax', { amount: 100, region: 'US' })
 
 **Dynamic vs Static:**
 
-- `get`, `post`, `del`, `rpc` — access headers/cookies, use in dynamic Server Components
-- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for precompile/ISR
+- `get`, `post`, `patch`, `del`, `rpc` — read `next/headers` cookies and headers,
+  so they force the component dynamic
+- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for
+  precompile/ISR
+
+The static variants pass `skipUserSession: true`, so a wiring that expects a
+session sees none. That is the real difference — not just where they can run.
+There is no `staticPatch` or `staticDel`; a mutation at build time is not a
+thing the generated client offers.
+
+Both paths run with `bubbleErrors: true`, so a failing wiring **throws** in your
+Server Component rather than resolving to an error status. Wrap the call, or let
+the Next.js error boundary take it.
 
 ## How It Works
 
@@ -73,6 +95,28 @@ import { PikkuNextJS } from '@pikku/next'
 const pikku = new PikkuNextJS(createConfig, createSingletonServices)
 ```
 
-**Constructor:** `new PikkuNextJS(createConfig?, createSingletonServices)`
+**Constructor:** `new PikkuNextJS(createConfig | undefined, createSingletonServices)`
+
+Both arguments are positional and `createConfig` is only optional in the sense
+that passing `undefined` substitutes an empty config —
+`createSingletonServices` is required.
+
+Initialization is memoized on a promise, so concurrent first requests share one
+setup; a failed setup clears the promise, so the next request retries rather
+than caching the failure forever.
+
+The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your
+route definitions.
+
+## Related exports
 
-The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your route definitions.
+- **`PikkuNextJSWorkerRPC({ fetcher })`** — same surface as `PikkuNextJS`, but
+  every call is dispatched through a `Fetcher` (a Cloudflare service binding, a
+  local HTTP client, a fabric dispatcher) instead of loading function code
+  in-process. Use it to keep functions out of the SSR bundle. A non-2xx
+  response throws with the status and body text.
+- **`toNextJsAuthHandler(auth)`** — wraps a better-auth instance or handler
+  function for an auth route. The three-argument form
+  `(pikkuAuthFactory, createConfig, createSingletonServices)` resolves a Pikku
+  better-auth factory lazily; it throws if you pass `createConfig` without
+  `createSingletonServices`. `nextCookies` is re-exported alongside it.

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)
 ```
@@ -183,12 +203,17 @@ Links the repo to a Fabric project and declares its frontends:
 ```
 
 - `projectId`: written by `pikku fabric init` / `link`. Templates ship the
-  `__PROJECT_ID__` placeholder — that is *not* a link, and the CLI treats it as
+  `__PROJECT_ID__` placeholder — that is _not_ a link, and the CLI treats it as
   unlinked.
 - `production.domain`: optional custom domain. Production always maps to `main`;
   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.
@@ -290,7 +315,7 @@ The output card shows whether any breaking changes were detected.
 
 These apply in every Fabric app:
 
-- **No `process.env`** — use `variables.get('NAME')` and `secrets.getSecret('NAME')`. Declare with `wireVariable` / `wireSecret`.
+- **No `process.env`** — use `variables.get('NAME')` and `secrets.getSecret('NAME')`. Declare with `defineVariable` / `defineSecret`.
 - **No `as any`** — fix types properly.
 - **No generic `Error`** — throw `NotFoundError`, `ConflictError`, `BadRequestError`, `UnauthorizedError` from `@pikku/core/errors`.
 - **No auth checks in function bodies** — use `permissions:` field on the function config with a `pikkuPermission` factory.
@@ -311,8 +336,8 @@ Fix every `error` and `warn` in the output before continuing. Then:
 1. **Replace the database layer**: swap PostgreSQL/MySQL queries for Kysely + libSQL. Convert schema to SQLite-compatible SQL migrations in `db/sqlite/`.
 2. **Replace route handlers with pikkuFuncs**: extract business logic into `pikkuFunc`/`pikkuSessionlessFunc`, add `wireHTTP` or `expose: true` for transport.
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
-4. **Replace `process.env` calls** with `wireVariable`/`wireSecret` + `variables.get()`.
+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.