@pikku/cli 0.12.91 → 0.12.93

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

@@ -1,73 +0,0 @@
----
-name: pikku-deploy-fastify
-description: >-
-  Use when deploying a Pikku app with Fastify. Covers PikkuFastifyServer standalone and
-  pikkuFastifyPlugin for existing Fastify apps. TRIGGER when: code imports @pikku/fastify or
-  @pikku/fastify-plugin, user mentions Fastify deployment, or start.ts creates a
-  PikkuFastifyServer. DO NOT TRIGGER when: just defining functions/wirings without
-  Fastify-specific code.
----
-
-# Pikku Fastify Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-## Standalone Server
-
-```bash
-yarn add @pikku/fastify
-```
-
-```typescript
-import { PikkuFastifyServer } from '@pikku/fastify'
-import './.pikku/pikku-bootstrap.gen.js'
-import { createConfig, createSingletonServices } from './services.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const appServer = new PikkuFastifyServer(
-  { ...config, hostname: 'localhost', port: 4002 },
-  singletonServices.logger
-)
-appServer.enableExitOnSigInt()
-await appServer.init()
-await appServer.start()
-```
-
-**Constructor:** `new PikkuFastifyServer(config, logger)`
-
-**Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
-
-**Methods:** `init(httpOptions?)`, `start()`, `stop()`, `enableExitOnSigInt()`
-
-**Property:** `app: FastifyInstance` — Direct access to Fastify instance.
-
-## Plugin (existing Fastify app)
-
-```bash
-yarn add @pikku/fastify-plugin
-```
-
-```typescript
-import Fastify from 'fastify'
-import pikkuFastifyPlugin from '@pikku/fastify-plugin'
-import './.pikku/pikku-bootstrap.gen.js'
-
-const app = Fastify()
-app.register(pikkuFastifyPlugin, {
-  pikku: {
-    logger: singletonServices.logger,
-    logRoutes: true,
-    loadSchemas: true,
-  },
-})
-```

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

@@ -1,110 +0,0 @@
----
-name: pikku-deploy-lambda
-description: >-
-  Use when deploying a Pikku app to AWS Lambda. Covers HTTP handlers, scheduled tasks, SQS queue
-  workers, WebSocket via API Gateway, and cold start caching. TRIGGER when: code imports
-  @pikku/lambda, user mentions Lambda/serverless/AWS deployment, or handler files export
-  Lambda-typed functions. DO NOT TRIGGER when: just defining functions/wirings without
-  Lambda-specific code.
----
-
-# Pikku AWS Lambda Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-```bash
-yarn add @pikku/lambda
-```
-
-## Cold Start Pattern
-
-Cache singleton services across Lambda invocations:
-
-```typescript
-// cold-start.ts
-import './.pikku/pikku-bootstrap.gen.js'
-import { createConfig, createSingletonServices } from './services.js'
-
-let singletonServices: SingletonServices | undefined
-
-export const coldStart = async () => {
-  if (!singletonServices) {
-    const config = await createConfig()
-    singletonServices = await createSingletonServices(config)
-  }
-  return singletonServices
-}
-```
-
-## HTTP Handler
-
-```typescript
-import type { APIGatewayProxyEvent } from 'aws-lambda'
-import { runFetch } from '@pikku/lambda/http'
-
-export const httpRoute = async (event: APIGatewayProxyEvent) => {
-  await coldStart()
-  return await runFetch(event)
-}
-```
-
-## Scheduled Tasks
-
-```typescript
-import type { ScheduledHandler } from 'aws-lambda'
-import { runScheduledTask } from '@pikku/core/scheduler'
-
-export const myScheduledTask: ScheduledHandler = async () => {
-  await coldStart()
-  await runScheduledTask({ name: 'myScheduledTask' })
-}
-```
-
-## SQS Queue Worker
-
-```typescript
-import type { SQSHandler } from 'aws-lambda'
-import { runSQSQueueWorker } from '@pikku/lambda/queue'
-
-export const mySQSWorker: SQSHandler = async (event) => {
-  const { logger } = await coldStart()
-  return runSQSQueueWorker(logger, event)
-}
-```
-
-## WebSocket (API Gateway v2)
-
-```typescript
-import {
-  connectWebsocket,
-  disconnectWebsocket,
-  processWebsocketMessage,
-  LambdaEventHubService,
-} from '@pikku/lambda/websocket'
-
-export const connectHandler = async (event) => {
-  const params = await getParams(event)
-  await connectWebsocket(event, params)
-  return { statusCode: 200, body: '' }
-}
-
-export const disconnectHandler = async (event) => {
-  const params = await getParams(event)
-  return await disconnectWebsocket(event, params)
-}
-
-export const defaultHandler = async (event) => {
-  const params = await getParams(event)
-  return await processWebsocketMessage(event, params)
-}
-```
-
-WebSocket requires a `ChannelStore` (e.g., `PgChannelStore`) and `LambdaEventHubService` for cross-connection messaging.

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

@@ -1,78 +0,0 @@
----
-name: pikku-deploy-nextjs
-description: >-
-  Use when deploying a Pikku app with Next.js. Covers API route handlers, server-side data
-  fetching, and RPC calls from Server Components. TRIGGER when: code imports @pikku/next, user
-  mentions Next.js integration, or app/api route files use pikkuAPIRequest. DO NOT TRIGGER when:
-  just defining functions/wirings without Next.js-specific code.
----
-
-# Pikku Next.js Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-```bash
-yarn add @pikku/next
-```
-
-## API Route Handler
-
-The CLI generates a typed wrapper. Use it in a catch-all route:
-
-```typescript
-// app/api/[...route]/route.ts
-import { pikkuAPIRequest } from '@/pikku-nextjs.gen.js'
-
-export const GET = pikkuAPIRequest
-export const POST = pikkuAPIRequest
-export const PUT = pikkuAPIRequest
-export const PATCH = pikkuAPIRequest
-export const DELETE = pikkuAPIRequest
-```
-
-## Server-Side Data Fetching
-
-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()
-
-// Dynamic (reads headers/cookies — requires request context)
-const todos = await get('/todos')
-const created = await post('/todos', { title: 'Buy milk' })
-
-// Static (no request context — suitable for precompile/ISR)
-const config = await staticGet('/config')
-
-// RPC calls
-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
-
-## How It Works
-
-`PikkuNextJS` lazy-initializes on first request:
-
-```typescript
-import { PikkuNextJS } from '@pikku/next'
-
-const pikku = new PikkuNextJS(createConfig, createSingletonServices)
-```
-
-**Constructor:** `new PikkuNextJS(createConfig?, createSingletonServices)`
-
-The generated `pikku-nextjs.gen.ts` wraps this with full type safety from your route definitions.

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

@@ -1,88 +0,0 @@
----
-name: pikku-deploy-uws
-description: >-
-  Use when deploying a Pikku app with uWebSockets.js. Covers PikkuUWSServer with built-in HTTP and
-  WebSocket support, and pikkuWebsocketHandler for standalone ws library. TRIGGER when: code
-  imports @pikku/uws or @pikku/ws, user mentions uWebSockets or high-performance server, or
-  start.ts creates a PikkuUWSServer. DO NOT TRIGGER when: just defining functions/wirings without
-  uWS-specific code.
----
-
-# Pikku uWebSockets.js Deployment
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Highest-throughput option among Pikku's runtimes. Handles both HTTP and WebSocket automatically.
-
-```bash
-yarn add @pikku/uws
-```
-
-```typescript
-import { PikkuUWSServer } from '@pikku/uws'
-import './.pikku/pikku-bootstrap.gen.js'
-import { createConfig, createSingletonServices } from './services.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const appServer = new PikkuUWSServer(
-  { ...config, hostname: 'localhost', port: 4002 },
-  singletonServices.logger
-)
-appServer.enableExitOnSigInt()
-await appServer.init()
-await appServer.start()
-```
-
-**Constructor:** `new PikkuUWSServer(config, logger)`
-
-**Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
-
-**Methods:** `init(httpOptions?)`, `start()`, `stop()`, `enableExitOnSigInt()`
-
-**Property:** `app: uWS.App` — Direct access to uWebSockets app instance.
-
-## WebSocket Standalone (ws library)
-
-For WebSocket-only servers using the `ws` library:
-
-```bash
-yarn add @pikku/ws
-```
-
-```typescript
-import { pikkuWebsocketHandler } from '@pikku/ws'
-import { stopSingletonServices } from '@pikku/core'
-import { Server } from 'http'
-import { WebSocketServer } from 'ws'
-import './.pikku/pikku-bootstrap.gen.js'
-
-const server = new Server()
-const wss = new WebSocketServer({ noServer: true })
-
-pikkuWebsocketHandler({
-  server,
-  wss,
-  logger: singletonServices.logger,
-})
-
-server.listen(4002, 'localhost', () => {
-  console.log('Server running at http://localhost:4002/')
-})
-
-process.on('SIGINT', async () => {
-  await stopSingletonServices()
-  wss.close()
-  server.close()
-  process.exit(0)
-})
-```

package/skills/pikku-deps/SKILL.md

@@ -1,98 +0,0 @@
----
-name: pikku-deps
-description: >-
-  Use for the Pikku dependency security audit: the `pikku audit` CLI command, the
-  `.pikku/audit.json` artifact, the `SecurityAuditReport` type in @pikku/core, and the console
-  Security screen (getSecurityAudit / runSecurityAudit / updateDependency + SecurityAuditView).
-  TRIGGER when: user asks about `pikku audit`, dependency vulnerabilities/advisories, outdated
-  dependencies, the Security screen/page in the console, updating a vulnerable dependency, or
-  reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT
-  (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use
-  pikku-config).
-installGroups: [core]
----
-
-# Pikku Dependency Audit
-
-## Agent Operating Procedure
-
-1. The audit is a generated artifact, not live state. `pikku audit` writes the
-   normalised report to `.pikku/audit.json` (config `outDir`), so it rides the
-   same meta pipeline as every other codegen output — uploaded on deploy,
-   readable by the console addon and any tooling. Read it via
-   `metaService.readFile('audit.json')`, never by shelling out to the package
-   manager from a function.
-2. One source of truth for the shape: `SecurityAuditReport` (and
-   `SecurityAuditIssue` / `SecurityAuditUpdate` / `SecurityAuditSummary` +
-   `SecuritySeverity` / `SecurityUpdateLevel`) are exported from **@pikku/core**.
-   The CLI writes it, the addon reads it, the UI renders it — never redeclare
-   the type at a call site.
-3. Validate with `pikku all --tsc` after changes — it type-checks and **fails on
-   type errors**, like any real build gate. Separately, `pikku audit` never fails
-   a build: advisories are informational, and a missing/failed audit yields an
-   empty-but-valid report.
-
-## The `pikku audit` command
-
-- `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` +
-  `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.
-
-## 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.
-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`.
-
-- `getSecurityAudit` — reads `.pikku/audit.json`, returns the report (or `null`).
-- `runSecurityAudit` — runs `pikku audit --outdated` server-side (regenerates the
-  artifact) then returns the fresh report. Same shape as the Run Tests action.
-- `updateDependency({ package, version })` — bumps the package in `package.json`
-  (preserving the `^`/`~` range prefix), runs `bun install`, re-audits, and
-  returns the fresh report. Throws if the package is not a direct dependency.
-  NOTE: `bun install` must be scoped to a standalone project — do not run it
-  inside a yarn/bun monorepo member (it resolves the whole workspace).
-
-## Console UI (@pikku/console)
-
-- `SecurityPage` — the page: **Run audit** button (`lead`) + responsive
-  `ShellHeader` (structured `search` + `selection` for the Issues/Dependencies
-  lens; never cram raw controls into the non-collapsing `filters`/`view` escape
-  hatch). Empty state until an audit has run.
-- `SecurityAuditView` — exported presentational component. Two lenses
-  (Issues grouped by severity; Dependencies table). Each finding row carries its
-  actions **right-aligned in the row header** (`Accordion.Control` sibling, so a
-  click acts instead of toggling): "View advisory" + a per-finding
-  **remediation slot**.
-- `renderRemediation({ pkg, version, issue })` — the extension seam. OSS default
-  is `UpdateDependencyButton` (the free bump + `bun install`). Downstream
-  consoles (Fabric) pass their own sandbox-verified action here — replace the
-  action, keep the view.
-- Hooks: `useSecurityAudit` (read), `useRunSecurityAudit` (run),
-  `useUpdateDependency` (bump). All are `useMutation`/`useQuery` — surface
-  `mutation.error`, never hand-roll loading/error state or swallow the error.
-
-## Report shape (SecurityAuditReport)
-
-```ts
-{
-  tool: string                 // e.g. 'bun'
-  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?
-  updates: SecurityAuditUpdate[] // package, current, latest, level (major|minor|patch|unknown)
-}
-```
-
-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

@@ -1,163 +0,0 @@
----
-name: pikku-emails
-description: >-
-  Use when working with Pikku's file-based email templates: authoring HTML/subject/text templates,
-  locales, partials and theme, running `pikku emails generate`, and rendering/sending them through
-  an EmailService. TRIGGER when: code uses renderEmailTemplate, EmailTemplateName, EmailService,
-  SendTemplateEmailInput, LocalEmailService, or imports from .pikku/email/pikku-emails.gen.
-  TRIGGER when: the project has an emails/ directory (templates/, locales/, partials/, theme.json)
-  or emailTemplatesDir in pikku.config.json. TRIGGER when: user asks to add/edit a transactional
-  email (verification, password reset, invitation, receipt), wire email sending, or translate an
-  email. DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows
-  in general (use pikku-better-auth).
-installGroups: [core]
----
-
-# Pikku Emails
-
-Pikku compiles a directory of plain template files into a typed, dependency-free
-renderer. `pikku emails generate` reads `emailTemplatesDir` and writes
-`.pikku/email/pikku-emails.gen.ts` (the `renderEmailTemplate` function + per-template
-types) and `pikku-emails-meta.gen.json`. Templates are authored as files; the
-generated output is never edited by hand.
-
-## Agent Operating Procedure
-
-1. Edit source files under `emailTemplatesDir` only. Never edit `.pikku/email/*`.
-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
-   project's typecheck — the generated `data` type will flag missing/wrong variables.
-4. Fix the source cause; do not patch generated files or update hashes by hand.
-
-## Config
-
-```jsonc
-// pikku.config.json
-{
-  "emailTemplatesDir": "emails",   // relative to rootDir; omit to disable emails
-  "outDir": ".pikku"               // gen lands in <outDir>/email/
-}
-```
-
-If `emailTemplatesDir` is unset the command is a no-op.
-
-## Directory layout
-
-```text
-emails/
-  theme.json                 # brand tokens: appName, fonts, colors
-  locales/
-    en.json                  # translation strings, nested namespaces
-    de.json                  # one file per locale (filename = locale key)
-  partials/
-    layout.html              # outer wrapper; must include {{content}}
-    footer.html              # reusable fragment, included with {{> footer}}
-  templates/
-    verify-email.html        # body (required)
-    verify-email.subject.txt # subject line (required)
-    verify-email.text.txt    # plain-text alternative (optional)
-```
-
-A template's **name** is its filename without the `.html` / `.subject.txt` / `.text.txt`
-suffix (`verify-email` above). `html` and `subject` are required; `text` is optional and,
-when present, becomes the plain-text MIME part.
-
-## Templating syntax
-
-Placeholders are `{{ ... }}`. Resolution order inside a template:
-
-- `{{appName}}` — from `data.appName`, falling back to `theme.appName`.
-- `{{theme.colors.accent}}`, `{{theme.fonts.body}}` — values from `theme.json`.
-- `{{t.verifyEmail.heading}}` — string from the active locale file (`locales/<locale>.json`).
-- `{{verifyUrl}}` — any other key is a **runtime variable**, supplied via `data`.
-- `{{> footer}}` — include a partial from `partials/`.
-- `{{content}}` / `{{subject}}` — only meaningful inside `partials/layout.html`
-  (the rendered body and subject). `layout.html` wraps every template if present.
-
-Locale strings may themselves contain variables and partial-free placeholders, e.g.
-`"subject": "{{inviterName}} invited you to join {{organizationName}}"`. These are
-resolved in the same pass, so a subject of `{{t.invitation.subject}}` expands fully.
-
-## Typed variables (per template)
-
-The generator extracts the runtime variables each template references and emits a typed
-`data` shape. Extraction is **scoped to the template**: it walks the template's
-html/subject/text, the partials it includes, and only the locale keys it actually
-references (transitively) — variables from unrelated locale entries do not leak in.
-
-```ts
-import {
-  renderEmailTemplate,
-  type EmailTemplateName,
-  type EmailTemplateVariables,
-} from './.pikku/email/pikku-emails.gen.js'
-
-// EmailTemplateVariables<'organization-invitation'> =
-//   { 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.
-
-## Rendering
-
-```ts
-const rendered = renderEmailTemplate({
-  name: 'verify-email',        // EmailTemplateName (autocompleted)
-  locale: 'en',                // optional, defaults to 'en'
-  data: { verifyUrl: url },    // EmailTemplateVariables<'verify-email'>
-})
-// rendered: { name, locale, subject, html, text?, variables, hash }
-```
-
-`hash` is a stable content hash (useful as an idempotency / dedupe key on outgoing mail).
-
-## Sending through an EmailService
-
-`@pikku/core/services` defines `EmailService.send(input)` where `input` is one of
-`SendTextEmailInput`, `SendHTMLEmailInput`, or `SendTemplateEmailInput`:
-
-```ts
-import type { EmailService } from '@pikku/core/services'
-
-await email.send({
-  to: user.email,
-  template: { name: 'verify-email', locale: user.locale, data: { verifyUrl } },
-})
-```
-
-`LocalEmailService` (dev/test) captures the payload as-is. To actually render templates
-before sending, wrap a delegate service: when `input.template` is present, call
-`renderEmailTemplate` and forward `subject` / `html` / `text` to the delegate (e.g. a
-Resend/SES/SMTP service). This wrapper is project-owned because `renderEmailTemplate`
-is generated per project; wire it in `services.ts` and inject it into functions.
-
-```ts
-async send(input: SendEmailInput) {
-  if (!('template' in input) || !input.template) return this.delegate.send(input)
-  const r = renderEmailTemplate(input.template as RenderEmailInput<EmailTemplateName>)
-  return this.delegate.send({
-    to: input.to, from: input.from, subject: r.subject, html: r.html,
-    ...(r.text ? { text: r.text } : {}),
-  })
-}
-```
-
-## Generated artifacts
-
-- `.pikku/email/pikku-emails.gen.ts` — `renderEmailTemplate`, `EmailTemplateName`,
-  `EmailLocale`, `EmailTemplateVariables<T>`, inlined templates/locales/partials/theme.
-- `.pikku/email/pikku-emails-meta.gen.json` — per-template `variables`, `hasHtml/Subject/Text`,
-  and per-locale content hashes. Both are regenerated; keep them out of hand edits and
-  (typically) git-ignored.
-
-## Gotchas
-
-- New template not appearing → you added `.html` but forgot `.subject.txt` (subject is
-  required), or didn't rerun `pikku emails generate`.
-- Variable typed `unknown`/missing → it's only in a locale string for a different template;
-  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.