@pikku/cli 0.12.91 → 0.12.92

package/skills/pikku-fabric/SKILL.md

@@ -1,318 +0,0 @@
----
-name: pikku-fabric
-description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
-installGroups: [fabric]
----
-
-# Pikku Fabric
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. **Run structural validation first.** Before any edit, run:
-   ```bash
-   pikku fabric validate --json
-   ```
-   This prints every missing file, misconfigured field, and dependency gap with a `fixHint`. Address all `error` findings before proceeding — they block deploy. Resolve `warn` findings before testing — they cause runtime failures. `info` findings are best-practice gaps that are safe to defer.
-2. 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.
-3. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-4. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-5. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-6. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-http`, `pikku-services`, etc.
-
-## Before you start
-
-Always run project discovery first:
-
-```bash
-yarn pikku meta context --json
-```
-
-In OpenCode, call the `pikku-meta` tool before grepping or editing a Fabric app.
-
-- Use `section: "context"` for the project map: functions, wires, workflows, capabilities, and source files.
-- Use `section: "clients"` before frontend/RPC work.
-- Use `section: "functions"` to list function ids, then `section: "function", id: "<functionId>"` for one function.
-- Use `section: "schemas"` to list schema names. Only request full JSON Schema bodies with `schemas: ["SchemaName"]` for the specific schemas needed.
-
-Do not load every schema body by default; that wastes context and usually makes the model worse.
-
-For database work in OpenCode:
-
-- Use `pikku-db` for the actual attached Fabric database state: tables, columns, foreign keys, and applied migrations.
-- Use `pikku-meta` `section: "schemas"` for code-level JSON Schema contracts, not database introspection.
-- Do not inspect database credentials or connect to the database directly; Fabric Control already exposes the safe introspection surface.
-
-## Database: SQLite via libSQL
-
-Fabric apps use SQLite, accessed via Kysely with the libSQL HTTP adapter. NOT PostgreSQL, NOT D1.
-
-### Setup in `services.ts`
-
-```typescript
-import { Kysely, CamelCasePlugin } from 'kysely'
-import { LibsqlWebDialect } from '@pikku/kysely-sqlite'
-import type { DB } from '#pikku/db/schema.gen.js'
-
-const databaseUrl = await variables.get('DATABASE_URL')
-let kysely: Kysely<DB>
-if (databaseUrl) {
-  kysely = new Kysely<DB>({
-    dialect: new LibsqlWebDialect({ url: databaseUrl }),
-    plugins: [new CamelCasePlugin()],
-  })
-} else if (existingServices?.kysely) {
-  kysely = existingServices.kysely as Kysely<DB>
-} else {
-  throw new Error('kysely not provided and DATABASE_URL is unset')
-}
-```
-
-Fabric injects `DATABASE_URL` as a variable binding when the stage starts. In local dev, `pikku db migrate` uses a local `dev.db` SQLite file.
-
-### Migrations
-
-Migrations are plain `.sql` files at the **project root**, in a directory named
-for the engine — `db/sqlite/` for SQLite/libSQL stages, `db/postgres/` for
-Postgres ones. Never `db/migrations/`, and never under `packages/functions/`:
-the deploy pipeline stages `db/<engine>/*.sql` from the root and applies them
-after upload, so a migration anywhere else is silently never run.
-
-```
-db/sqlite/
-  0001-init.sql
-  0002-add-users.sql
-```
-
-Numbers must be consecutive and gap-free, and an applied migration is frozen —
-correct a mistake with a new forward migration, never by editing or renaming one
-that has already run (the recorded hash will no longer match).
-
-Run migrations: `pikku db migrate`. It also regenerates `.pikku/db/schema.gen.ts`
-(Kysely types) and `.pikku/db/zod.gen.ts` — there is no separate types step.
-
-**NEVER hand-edit the generated schema** — write a migration and re-run.
-
-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
-migration that closes the gap.
-
-### Column conventions
-
-- Use `SERIAL`/`INTEGER PRIMARY KEY AUTOINCREMENT` for IDs
-- Use `TEXT` for strings, `INTEGER` for booleans (0/1) and timestamps (Unix ms)
-- Use `CHECK` constraints sparingly — prefer app-level validation
-- Table and column names: snake_case in SQL, camelCase in TypeScript (via `CamelCasePlugin`)
-
-## Deploy Provider
-
-`pikku.config.json` (in the project root, not `packages/functions/`) **must** declare the Fabric deploy provider:
-
-```json
-{
-  "deploy": {
-    "providers": {
-      "cloudflare": "@pikkufabric/deploy-cloudflare"
-    }
-  }
-}
-```
-
-Without this, `pikku deploy plan --provider cloudflare` uses the OSS adapter which lacks Fabric's workflow service wiring.
-
-The Fabric adapter automatically:
-
-- Injects `SQLiteKyselyWorkflowService` when `DATABASE_URL` is bound
-- Sets up the libSQL workflow queue
-- Wires `workflowQueues: true` for the scaffold
-
-No manual workflow service setup is needed.
-
-## Project Layout
-
-```
-packages/functions/
-  src/
-    functions/         # Business logic — one pikkuFunc/workflow per file
-    wirings/           # Transport bindings
-      *.http.ts        # wireHTTP / defineHTTPRoutes / wireHTTPRoutes
-      *.channel.ts     # wireChannel
-      *.queue.ts       # wireQueueWorker
-      *.schedule.ts    # wireScheduler
-      *.mcp.ts         # wireMCPTool
-      *.cli.ts         # wireCLI
-    services.ts        # pikkuServices factory (singleton)
-    middleware.ts      # Shared middleware
-    permissions.ts     # Shared permissions
-  .pikku/
-    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)
-pikku.config.json      # Pikku + deploy config (project root)
-pikkufabric.config.json # Fabric project link + frontends (project root)
-```
-
-## `pikkufabric.config.json`
-
-Links the repo to a Fabric project and declares its frontends:
-
-```json
-{
-  "projectId": "my-project-id",
-  "production": {
-    "domain": "example.com"
-  },
-  "frontends": {
-    "app": {
-      "cwd": "apps/app",
-      "primary": true,
-      "deploy": true,
-      "kind": "ssr",
-      "dev": {
-        "command": ["yarn", "dev"],
-        "port": 7105,
-        "healthPath": "/"
-      }
-    }
-  }
-}
-```
-
-- `projectId`: written by `pikku fabric init` / `link`. Templates ship the
-  `__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
-
-## 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.
-
-```typescript
-export const listTasks = pikkuSessionlessFunc({
-  expose: true,
-  readonly: true,
-  func: async ({ kysely }, {}) => {
-    return { tasks: await kysely.selectFrom('tasks').selectAll().execute() }
-  },
-})
-```
-
-Add `wireHTTP` only when you need a specific REST shape (webhooks, third-party callers).
-
-### Transport rule
-
-- Always use RPC first.
-- If the function should be callable from the app or other generated clients, prefer `expose: true`.
-- Use `expose: true` for public/generated client access unless the user explicitly wants a private function.
-- Do not add HTTP routes unless the user explicitly asks for HTTP/REST, or the project settings explicitly require HTTP transport.
-- Every new or changed function must have a real description.
-- If function metadata would show `missing description`, the work is not finished yet.
-
-## Run it locally
-
-A Fabric app is two processes: the pikku API server (`:3000`) and the frontend
-(vite). The starter template's `bun run dev` starts **both** and takes the whole
-session down if either dies — a frontend running against a dead API looks like an
-app bug and is the single most common way to waste an hour here.
-
-```bash
-bun run prebuild   # pikku all — codegen must be current before the server boots
-bun run dev
-```
-
-Then open the app, sign up as a real user, and click through what you built.
-**HTTP 200 is not evidence.** These are client-rendered pages: the server returns
-200 with an empty shell, so a page whose component throws still looks fine to
-curl. Either open it in a browser or drive it headlessly and assert on rendered
-text.
-
-Secrets come from `process.env`, which the CLI populates from a `.env` in the
-working directory. `BETTER_AUTH_SECRET` is required — without it the first
-sign-up fails with `Requested secret not found`, which names no key and points at
-no file. The starter template generates one on first `bun run dev`.
-
-If you are running the two processes yourself rather than through the template's
-script, run `pikku dev` from the **project root** (it resolves `srcDirectories`
-relative to the config, so a nested cwd yields a doubled watch path and no hot
-reload).
-
-## Deploy
-
-```bash
-pikku fabric login              # opens a browser; needs a human, wait for it
-pikku fabric init https://github.com/<owner>/<repo>
-pikku fabric validate           # must pass clean
-pikku fabric deploy plan --production
-pikku fabric deploy apply --production --auto-apply
-```
-
-`apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
-it refuses rather than hangs. `--auto-apply` supplies that confirmation; drop it
-only when a human is at a real terminal.
-
-`init` adopts a **GitHub** repo, and adoption goes through the Pikku Fabric
-GitHub App — the app has to be installed on the account or org that owns the
-repo, and if it is installed with "selected repositories" this one must be in
-the selection. There is no CLI flag that works around a missing installation:
-`init` returns "Connect the GitHub account '<owner>'". Send the user to install
-it, or create the project in the console instead (which provisions a Fabric-hosted
-git repo you push to) and write the returned `projectId` into
-`pikkufabric.config.json` yourself.
-
-Deploy refuses to run unless the target branch equals its upstream — the guard
-compares `main` against `main@{upstream}`. So the remote you pushed to must be
-the one the branch tracks; a stale `origin` left over from scaffolding blocks
-the deploy with "local HEAD … ≠ remote …" even though your code is pushed.
-`git branch --set-upstream-to=<remote>/main main` before deploying.
-
-## Versioning
-
-Functions with `expose: true` are versioned via `versions.pikku.json`. When you change a function's input or output schema, you must bump its version number — otherwise `pikku all` will report a breaking change and callers' generated clients become stale.
-
-The `pikku-verify` tool catches this automatically.
-
-## After every code change
-
-Always call the `pikku-verify` tool after modifying functions, wirings, or schemas. It runs:
-
-1. `pikku all` — regenerates all codegen, checks version compliance
-2. `tsc --noEmit` — validates TypeScript types
-
-The output card shows whether any breaking changes were detected.
-
-## Hard rules
-
-These apply in every Fabric app:
-
-- **No `process.env`** — use `variables.get('NAME')` and `secrets.getSecret('NAME')`. Declare with `wireVariable` / `wireSecret`.
-- **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.
-- **No hand-editing `.pikku/db/schema.gen.ts`** — write a migration and re-run `pikku db migrate`.
-- **One runtime unit per file** — never define multiple functions/workflows in a single source file.
-- **Workflow steps don't need manual wiring** — `pikkuSessionlessFunc` step functions in `*.steps.ts` files are auto-discovered by codegen.
-
-## Converting an existing app to Fabric format
-
-Start by running the structural validator — it tells you exactly what is missing:
-
-```bash
-pikku fabric validate --json
-```
-
-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()`.
-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`.
-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

@@ -1,112 +0,0 @@
----
-name: pikku-fabric-debug
-description: 'Debug a deployed Fabric stage from the CLI — read logs, find recent errors, follow a single request end-to-end by traceId, and check request/error/latency metrics. TRIGGER when: a deployed Fabric app is erroring, timing out, or behaving differently than local; the user asks "why is prod failing", "check the logs", "what happened to this request"; or a deploy succeeded but the app misbehaves. DO NOT TRIGGER when: the failure reproduces locally (debug it locally), the deploy itself failed (use pikku-fabric — that is a build/config problem, not a runtime one), or the project is not deployed to Fabric.'
-installGroups: [fabric]
----
-
-# Debugging a deployed Fabric stage
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Reproduce locally first. If it fails locally too, debug it there — the
-   deployed stage adds cost and latency to every iteration.
-2. Start from `errors`, not `logs`. Errors are already filtered and carry the
-   traceId that unlocks the rest.
-3. Follow one trace end-to-end before forming a theory. A single failing request
-   tells you more than a hundred unrelated log lines.
-4. Fix the source cause and redeploy. Never leave the diagnosis at "it is flaky".
-5. Confirm the fix against the same stage — recheck `errors` for the function.
-
-Every command below requires a logged-in CLI and a linked project. Both fail
-with the exact remediation if not:
-
-```
-Not logged in. Run `pikku fabric login` first.
-No fabric project linked. Run `pikku fabric link` first.
-```
-
-## The loop
-
-**1 — What is broken?**
-
-```bash
-pikku fabric errors -b main                 # branch defaults to main
-pikku fabric errors -b main --function createOrder
-```
-
-Prints a `WHEN | FUNCTION | TRACE | MESSAGE` table. The message is **truncated
-to 100 characters** — treat it as a label, not the full error. The TRACE column
-is the input to the next step.
-
-**2 — What happened in that one request?**
-
-```bash
-pikku fabric trace <traceId> -b main
-pikku fabric trace <traceId> -b main --json
-```
-
-`--branch` is **required** here (no default). Each event prints as:
-
-```
-<timestamp> <scriptName> <wireType>:<wireId> <duration>ms — <error|message|outcome>
-```
-
-This is the whole request across the stage — every unit it touched, in order,
-with per-event durations. The last event before the failure is where to look.
-
-**3 — Is it one request or the whole stage?**
-
-```bash
-pikku fabric metrics -b main                       # last 24h
-pikku fabric metrics -b main --hours 2 --function createOrder
-```
-
-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`
-breakdown (requests per http/queue/scheduler/…) that the table output omits.
-
-**4 — Wider context around the failure**
-
-```bash
-pikku fabric logs -b main
-pikku fabric logs -b main --level warn
-pikku fabric logs -b main -f              # follow
-```
-
-`--branch` is **required** — `logs` throws `Specify --branch <branch-name>.`
-without it, even though the flag reads as optional.
-
-**5 — Is the running code the code you think it is?**
-
-```bash
-pikku fabric status     # active + in-flight deployment, per stage, with gitSha
-```
-
-Check this *before* deep-diving. A stage still serving an older `gitSha`, or a
-deploy stuck in flight, explains a whole class of "my fix did nothing".
-
-## Known gaps — do not misread these as bugs in your app
-
-- **`pikku fabric logs --since` and `--deployment` are accepted and ignored.**
-  They are declared as options but the command never reads them, so
-  `--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
-  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.
-
-## What NOT to do
-
-- **Do not SSH anywhere or query the telemetry backend directly.** These
-  commands are the supported surface; anything lower-level is Fabric-internal
-  and will not exist for your project.
-- **Do not debug by redeploying with added `console.log`s.** Get the traceId,
-  read the trace. A deploy cycle per hypothesis is the slow path.
-- **Do not read the truncated `errors` message as the full error.** Always
-  confirm against `trace` before changing code.
-- **Do not treat an empty `errors` table as "the app is fine"** — a request that
-  returns a wrong 200 logs nothing. Check `metrics` for the outcome mix.

package/skills/pikku-feature/SKILL.md

@@ -1,258 +0,0 @@
----
-name: pikku-feature
-description: 'Drive create-a-feature work for a Pikku project: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "build a todo app", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, or asks about Pikku concepts (use pikku-concepts).'
-installGroups: [core]
-allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *)
-argument-hint: '<feature description>'
----
-
-# Pikku Create-a-Feature
-
-## 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.
-
-End-to-end flow: **discover → state intent → branch → implement → verify → commit → hand to reviewer**.
-
-There is **no plan JSON**. The branch + diff IS the contract. The reviewer
-sees real, compiled, working code. Apply = merge. Reject = `git branch -D`.
-
-## Stage 1 — Discover
-
-Run **once** at the start of every feature request:
-
-```bash
-yarn pikku meta context --json
-```
-
-This single call returns functions, wires, middleware, permissions, workflows,
-`capabilities` (which wire types are in use), and `layout` (where new files
-should land).
-
-Only fall back to targeted commands when you need full input/output JSON
-schemas (`yarn pikku meta functions get <id>`) or workflow steps
-(`yarn pikku meta workflows get <id>`).
-
-**Capability rule:** do not introduce new wires of a type whose
-`capabilities.<type>` is `false` unless the user explicitly asked for it.
-
-## Stage 2 — State intent in plain English (BEFORE writing code)
-
-Before touching any files, give the user one paragraph stating exactly what
-you'll do. This is the lightweight "plan" — it is chat, not JSON.
-
-> I'll add a `todos` table via a new migration in `sql/`, and two
-> `pikkuSessionlessFunc`s (`createTodo`, `listTodos` with
-> `readonly: true`) in `packages/functions/src/functions/`. Both
-> `expose: true`, so they'll be reachable via the auto-generated RPC
-> client and React Query hooks — no HTTP wiring needed. No new
-> dependencies. OK to proceed?
-
-Wait for the user to confirm or redirect. They can ask for changes ("use the
-existing tasks table" / "make it a queue not http") in normal chat — no
-schema, no JSON, no ceremony.
-
-**Non-interactive runs (auto mode, CI, batch jobs):** state intent in one
-paragraph and proceed without waiting. Surface course corrections promptly
-in the post-implementation report.
-
-## Stage 3 — Branch off
-
-After confirmation, ensure the working tree is clean and create a feature
-branch off the current default branch (whatever `git branch --show-current`
-returns at the start — `main`, `master`, `develop`, all fine):
-
-```bash
-git status
-git switch -c feature/<short-slug>
-```
-
-If the working tree is dirty, **stop and ask** — never stash silently or
-overwrite uncommitted work.
-
-## Stage 4 — Implement
-
-Write the code as a normal human contributor would. Use the project's
-existing conventions (look at neighbour files in `srcDirectories[0]/functions/`
-and `.../wirings/` for style).
-
-### RPC is the default transport
-
-**Just write the function with `expose: true`** — that's enough to make it
-callable. Pikku auto-generates an RPC client (and React Query hooks if the
-project's `clientFiles.reactQueryFile` is set) from every exposed function.
-You do **not** need an HTTP wiring for callers to reach the function.
-
-Default flow for a feature:
-
-1. Write the function file with `expose: true` (and `readonly: true` for
-   reads).
-2. Run `pikku all` — RPC map, fetch client, and React Query hooks are
-   regenerated. Frontends call `useListTodos()` / `mutation.mutate(...)`
-   without you wiring anything.
-
-Add an HTTP wiring **only when** the feature genuinely needs a specific
-REST shape (third-party callers, webhooks, REST-conventional URLs). Most
-in-app features don't.
-
-### Hard rules that always apply
-
-- **`expose: true`** for any function called from a frontend or another
-  service. Without it the RPC client won't generate hooks for it.
-- **`readonly: true` for queries.** Mark read functions as `readonly: true`
-  on the function config. The runner uses this to enforce read-only sessions
-  (a write func called under a readonly session is rejected). The RPC layer
-  also uses it to pick `useQuery` (cacheable) vs `useMutation` for client
-  hooks. Mutations leave `readonly` unset (or `false`).
-- **`kind` ⇔ `auth` coupling for HTTP wirings (when you have one).** If the
-  function is `pikkuFunc` (session-aware), the HTTP wiring needs
-  `auth: true`. `pikkuSessionlessFunc` ⇒ `auth: false`. Mismatching is a
-  hard error (PKU573).
-- **HTTP method by intent (when you wire HTTP).** Reads → `GET`. Writes →
-  `POST`/`PUT`/`PATCH`/`DELETE` per REST conventions.
-- **Workflows.** Prefer `pikkuWorkflowGraph` (DSL) over
-  `pikkuWorkflowComplexFunc`. `mode: 'inline'` is sync; `'distributed'` is
-  queue-dispatched.
-- **Auth checks belong on the function or wiring**, not in function bodies.
-  Use the `permissions` field with a `pikkuPermission` factory.
-- **Throw typed errors** from `@pikku/core/errors` — `NotFoundError`,
-  `ConflictError`, `BadRequestError`. Never bare `Error`.
-- **Migrations are inline SQL files** in the project's migrations dir
-  (typically `sql/`). Use a numbered prefix matching existing files.
-- **Secrets and env-vars: NEVER `process.env`.** Declare them with
-  `wireSecret` (sensitive) or `wireVariable` (non-sensitive) — both with a
-  zod schema for type-safe access. Read with
-  `services.secrets.getSecret('NAME')` or `services.variables.get('NAME')`.
-  See the **pikku-config** skill for the full pattern (including
-  OAuth2 credentials). This applies even in `config.ts` and singleton
-  service factories.
-
-### Conventions to copy from neighbours
-
-Some patterns vary by project; **read a neighbour file before writing**:
-
-- **Function shape**: zod schemas as exported `const`s (`CreateTodoInput`,
-  `CreateTodoOutput`) passed to `input`/`output` on the func config — vs
-  generic-typed config. Schema name **must match codegen expectations** (the
-  exported const name = the schema name in generated `.gen.json`).
-- **Imports**: usually `'#pikku'` for `pikkuFunc` / `pikkuSessionlessFunc`
-  etc. Copy what neighbours do.
-- **Service usage**: e.g. `kysely`, `redis`. Look at how an existing function
-  destructures services from its first arg. **Check `application-types.d.ts`**
-  to see whether services like `kysely` are typed (`Kysely<DB>`) or untyped
-  (`Kysely<any>`) — that drives whether you can lean on generated DB types
-  or have to coerce manually.
-- **DB schema namespace**: many projects put tables under a `CREATE SCHEMA`
-  (e.g. `app.todos`). Read the first migration in `sql/` to see the
-  convention; reuse helper functions/triggers (e.g. `update_last_updated_at`)
-  rather than redefining them.
-- **HTTP wiring style** (only relevant if you're adding one). Two common
-  shapes — match what the project already uses:
-  - Per-route `wireHTTP({ method, route, func, auth })`.
-  - Single map: `const routes = defineHTTPRoutes({ auth: false, routes: {
-fooName: { method: 'post', route: '/foo', func: fooFunc } }}); wireHTTPRoutes(routes)`.
-
-For shared wiring files (e.g. `todos.http.ts` holding both create and list):
-create the file with imports if it doesn't exist; **append** wire calls and
-add missing imports if it does.
-
-## Stage 5 — Verify
-
-Both must complete cleanly **for your changes** before committing:
-
-```bash
-yarn pikku all
-# Type-check the workspaces you touched:
-cd packages/functions && npx tsc --noEmit
-```
-
-Notes on running `tsc`:
-
-- A root-level `yarn tsc` may be a no-op in monorepos that don't define a
-  `tsc` script in each workspace. Don't trust an exit-zero from the root if
-  no actual checking happened — verify by running `npx tsc --noEmit` in the
-  package(s) you touched.
-
-### What "fails" means
-
-**Trust the exit code, not the stderr noise.** `yarn pikku all` may print
-warnings, `[PKUxxx]` messages, even `level: critical` log lines, while
-still exiting `0` — those are pre-existing project state, not your
-problem. Same for `meta context --json`: it streams logs to stderr that
-look scary on a clean baseline. The exit code is the source of truth.
-
-If a command exits non-zero, that's a real failure — fix or stop.
-
-### Baseline noise — only your errors matter
-
-Many real-world projects ship with pre-existing warnings or errors
-(legacy types, version drift, gen-layer messages). Those are not your
-problem; do not "fix" them.
-
-To distinguish your errors from baseline:
-
-1. **Before implementing** (Stage 4), capture the baseline:
-   ```bash
-   yarn pikku all 2>&1 | tee /tmp/pikku-before.log
-   ```
-2. **After implementing**, compare:
-   ```bash
-   yarn pikku all 2>&1 | tee /tmp/pikku-after.log
-   diff /tmp/pikku-before.log /tmp/pikku-after.log
-   ```
-
-A clean diff means your changes introduced no new issues — even if the
-underlying logs both show pre-existing warnings.
-
-If something genuinely failed because of YOUR change, fix the actual issue.
-**Do not** mask errors with `as any`, `@ts-ignore`, or `--no-verify`. If
-you're stuck, surface the failure to the user — don't hand them a broken
-branch.
-
-## Stage 6 — Commit
-
-```bash
-git add -A
-git commit -m "feat: <short title>"
-```
-
-## Stage 7 — Hand off
-
-Tell the user the branch name and how to review. Two options:
-
-- **Local review:** open the pikku console — the changes view diffs the
-  current branch against `main` with pikku-aware structure (added functions,
-  new wires, migrations).
-- **PR review:** ask before pushing. Once they confirm, `git push -u origin
-feature/<slug>` and surface the PR-create URL.
-
-Do not push without explicit confirmation. Do not merge.
-
-## Hard constraints
-
-The skill's `allowed-tools` does **not** permit:
-
-- `yarn add` / `npm install` / dependency changes (ask the user first)
-- `yarn dbmigrate` (never run migrations against the real DB during planning)
-- `pikku deploy apply` (never deploy)
-- secret writes
-- network calls beyond what the implementation requires
-
-If the feature genuinely needs any of these, **stop and ask** with a clear
-explanation of why and what would change.
-
-## Output discipline
-
-- Stage 2 (intent statement) is plain English, one paragraph.
-- Between stages, give one-line updates: "Discovered 30 functions, http+queue
-  in use. Drafting intent..." → "Branch `feature/todos` created, implementing..."
-  → "`pikku all` clean, `tsc` clean, committed. Review via console or run
-  `git diff main`."
-- Don't narrate file-by-file. Only surface what's interesting (new patterns,
-  judgment calls, things you suppressed).