@pikku/skills 0.12.13 → 0.12.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.13",
+  "version": "0.12.15",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-ai-vercel/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   VercelAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
   @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-agent) or
   voice I/O (use pikku-ai-voice).
-installGroups: [core]
+installGroups: [fabric]
 ---
 
 # Pikku AI Vercel (Agent Runner)

package/skills/pikku-ai-voice/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   agents, speech-to-text, text-to-speech, transcription, or @pikku/ai-voice. DO NOT TRIGGER when:
   user asks about AI agent wiring generally (use pikku-agent) or the runner itself (use
   pikku-ai-vercel).
+installGroups: [fabric]
 ---
 
 # Pikku AI Voice (Speech I/O)

package/skills/pikku-audit/SKILL.md

@@ -10,7 +10,6 @@ description: >-
   uses auditLog, createInvocationAudit, createAuditedKysely, or AuditService. DO NOT TRIGGER when:
   user wants app logging/telemetry (use the logger) or DB migrations in general (use
   pikku-kysely).
-installGroups: [core]
 ---
 
 # Pikku Audit

package/skills/pikku-better-auth/SKILL.md

@@ -10,7 +10,7 @@ description: >-
   user asks about ANY form of authentication, login, logout, sessions, or user identity — always
   answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security)
   or custom session services (use pikku-services).
-installGroups: [core]
+installGroups: [fabric]
 ---
 
 # Pikku Better Auth Integration

package/skills/pikku-build-app/SKILL.md

@@ -10,7 +10,6 @@ description: >-
   something quick or throwaway (use pikku-build-quick), wants every platform surface demonstrated
   (use pikku-build-platform), or is adding one feature to an app that already has its knowledge
   base and milestones (use pikku-feature).
-installGroups: [core]
 ---
 
 # Build a product on open-source Pikku

package/skills/pikku-build-platform/SKILL.md

@@ -8,8 +8,7 @@ description: >-
   app, or asked to demonstrate what Pikku can do. DO NOT TRIGGER when: the user wants a product
   built (use pikku-build-app), something quick (use pikku-build-quick), or one specific surface
   wired into an existing app — a single workflow, cron job or agent (use that surface's own skill,
-  e.g. pikku-workflow, pikku-cron, pikku-agent).
-installGroups: [core]
+  e.g. pikku-workflow, pikku-schedule, pikku-agent).
 ---
 
 # Build a platform showcase on Pikku
@@ -90,7 +89,7 @@ on a human or a timer and must survive a restart.
   from the UI.
 - Three workflows ship with the template. Read them before writing yours.
 
-### Schedules — `pikku-schedule` / `pikku-cron`
+### Schedules — `pikku-schedule`
 
 Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
 
@@ -231,7 +230,7 @@ built.
 ## Reference
 
 - Base workflow: `pikku-build-app` — read it first, follow it in full
-- Per-surface skills: `pikku-workflow`, `pikku-schedule`, `pikku-cron`,
+- Per-surface skills: `pikku-workflow`, `pikku-schedule`,
   `pikku-queue`, `pikku-agent`, `pikku-ai-vercel`, `pikku-realtime`,
   `pikku-websocket`, `pikku-mcp`, `pikku-trigger`, `pikku-i18n`, `pikku-rtl`,
   `pikku-emails`, `pikku-versioning`, `pikku-addon`, `pikku-security`,

package/skills/pikku-build-quick/SKILL.md

@@ -12,7 +12,6 @@ description: >-
   workflows, queues, realtime or i18n (use pikku-build-platform); or the user is adding a feature
   to an app that already exists rather than building one from a fresh scaffold (use
   pikku-feature).
-installGroups: [core]
 ---
 
 # Build an app on Pikku, fast

package/skills/pikku-cli/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   options, parameters, custom renderers, and nested command groups. TRIGGER when: code uses
   wireCLI/pikkuCLICommand, user asks about CLI commands, terminal tools, command-line interface,
   or adding subcommands. DO NOT TRIGGER when: user asks about the pikku CLI tool itself (use
-  pikku-info) or HTTP endpoints (use pikku-http).
+  pikku-meta) or HTTP endpoints (use pikku-http).
 installGroups: [core]
 ---
 

package/skills/pikku-concepts/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pikku-concepts
 description: >-
-  Foundational guide to Pikku framework concepts. Use this skill when working with any Pikku
-  codebase, starting a new Pikku project, or migrating a backend to Pikku. Covers the core mental
-  model, function types, project structure, code generation, testing, and how Pikku maps to
-  traditional backend patterns. TRIGGER when: user asks "what is Pikku?", starts a new Pikku
-  project, migrates from Express/NestJS/Hono, or needs to understand how Pikku works. DO NOT
-  TRIGGER when: user is doing a specific wiring task (use the specific skill instead, e.g.
-  pikku-http, pikku-websocket).
+  Use FIRST in any Pikku codebase, before writing an import or reaching for another pikku skill.
+  Covers the core mental model, function types, project structure, code generation and testing,
+  and how to read `pikku doc` — the API surface of the pikku actually installed here, which also
+  indexes which skill teaches each door. TRIGGER when: starting any Pikku task, about to import
+  from `#pikku/*`, unsure whether an export exists or what its options are called, choosing which
+  pikku skill to load, a build failed on an unknown import or option, or migrating an existing
+  backend to Pikku. DO NOT TRIGGER when: the task is not a Pikku project.
 installGroups: [core]
 ---
 
@@ -17,7 +17,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run `pikku doc --ai` for the installed API surface, and the relevant `pikku meta ... --json` for what this project has wired.
 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.
@@ -25,12 +25,54 @@ Use this skill as an execution checklist, not reference material.
 
 Pikku is a TypeScript framework that separates business logic from transport mechanisms. You define a function once, then wire it to HTTP, WebSocket, queues, schedulers, MCP, CLI, or RPC — without the function knowing how it's being called.
 
-For deep-dive on each topic, see the dedicated skills:
+## Ask The Installed Pikku, Don't Guess
 
-- **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-agent`, `pikku-workflow`
-- **Authorization**: `pikku-security` (authentication/sessions), `pikku-permissions` (permission checks, scopes), `pikku-middleware` (global/tag/route middleware)
-- **Infrastructure**: `pikku-services`, `pikku-config`
-- **Project introspection**: `pikku-info`
+Pikku generates `#pikku/*` imports per project and changes between versions. Anything you
+remember about its API may be from a different version than the one in this directory.
+Everything below is the mental model; `pikku doc` is the API surface, computed when the
+installed CLI was built. It needs no config and works outside a project.
+
+**Do not write an import, an export name, or an option key you have not seen in `pikku doc`.**
+A name that looks right and is not costs a full build cycle to discover. If the doc does not
+list it, it does not exist here — do not reach into `node_modules` or `.pikku` for something
+that will work anyway.
+
+### Start here, every time
+
+```
+pikku doc --ai
+```
+
+≈480 tokens, giving the 20 `#pikku/*` doors grouped by the job they do, and beside each the
+skill that teaches it. Read that routing table as the index to every other pikku skill — it is
+generated from the installed version, so it never names a skill for a door that no longer exists.
+
+Then go one of two ways. For **what exists** — the exact export name, its options, its
+signature — stay in the doc:
+
+```
+pikku doc http                 one door: its exports, each with a signature or a key count
+pikku doc wireHTTP             one export: signature, every key with what it is for
+pikku doc wireHTTP pikkuFunc   several topics in one call, rather than one call each
+```
+
+For **how it fits together** — composition, lifecycle, the generated client — load the skill
+the routing table named. The doc lists keys; it does not teach patterns.
+
+On a door screen, `N keys — pikku doc X` means a second call buys you something; an inlined
+signature means it does not. Error classes carry the HTTP status they are registered with,
+which is what decides whether a thrown error becomes a 409 or a 500.
+
+### Two things the doc will not give you
+
+- **Worked examples are sparse.** Most exports show a signature and keys, not usage.
+- **`pikkuFunc` lists keys that belong elsewhere.** `before`, `after`, `skip`, `surfaces` and
+  `requiresActor` apply only to scenarios; `workflowQueued`, `workflowRetries` and
+  `workflowTimeout` only to a workflow step. One shared config type offers all of them to
+  every function — each key says which it belongs to.
+
+`pikku doc` needs `@pikku/cli` 0.12.115 or newer. On an older pin, fall back to the door's
+skill and `pikku meta --json`, and do not guess at names the doc would have given you.
 
 ## Core Mental Model
 
@@ -59,7 +101,7 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
+Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`, a separate install; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
@@ -270,8 +312,8 @@ src/
 ├── schemas.ts           # Zod/Valibot schemas
 ├── services.ts          # Service factories (see pikku-services)
 ├── lifecycle.ts         # Server lifecycle hooks (pikku dev/serve only)
-├── middleware.ts         # Middleware definitions (see pikku-security)
-├── permissions.ts       # Permission definitions (see pikku-security)
+├── middleware.ts         # Middleware definitions (see pikku-middleware)
+├── permissions.ts       # Permission definitions (see pikku-permissions)
 └── .pikku/              # Generated (gitignored)
     ├── function/        # #pikku/function
     ├── http/            # #pikku/http

package/skills/pikku-concepts/references/concept-mapping.md

@@ -15,7 +15,7 @@ Authoritative mapping table plus side-by-side code examples showing how common b
 | **Dependency Injection**                | `pikkuServices` (singleton) + `pikkuWireServices` (per-request) | `pikku-services`  |
 | **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-websocket` |
 | **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-queue`     |
-| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
+| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-schedule`      |
 | **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
 | **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
 | **Type-safe API client**                | `npx pikku all` generates clients                               | `pikku-concepts`  |

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

@@ -5,7 +5,6 @@ description: >-
   tasks, and WebSocket via Durable Objects. TRIGGER when: code imports @pikku/cloudflare, user
   mentions Cloudflare Workers deployment, or worker entry uses ExportedHandler/wrangler.toml. DO
   NOT TRIGGER when: just defining functions/wirings without Cloudflare-specific code.
-installGroups: [fabric]
 ---
 
 # Pikku Cloudflare Workers Deployment

package/skills/pikku-deps/SKILL.md

@@ -12,7 +12,6 @@ description: >-
   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

package/skills/pikku-emails/SKILL.md

@@ -10,7 +10,7 @@ description: >-
   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]
+installGroups: [fabric]
 ---
 
 # Pikku Emails

package/skills/pikku-fabric/SKILL.md

@@ -273,13 +273,64 @@ reload).
 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
+pikku fabric deploy apply --production --sync --auto-approve
 ```
 
+There is no `deploy plan` subcommand — `apply` runs the same auth, git-safety
+and ref resolution itself, and fabric produces the real plan server-side.
+
 `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.
+it refuses rather than hangs. `--auto-approve` supplies that confirmation; drop
+it only when a human is at a real terminal.
+
+By default `apply` queues the deploy, prints the deployment id and returns. That
+tells you nothing about whether it worked. `--sync` waits for a terminal state
+and exits non-zero unless the deployment went live, which is the only form worth
+running in CI:
+
+| exit | meaning |
+| ---- | ------- |
+| 0 | live (or queued, without `--sync`) |
+| 1 | the command could not run — not logged in, unsafe git state, bad flags |
+| 2 | the deployment failed, errored, timed out server-side, or was cancelled |
+| 3 | the deployment is blocked and nothing the CLI can do will unblock it |
+| 4 | the wait hit `--timeout` with the deployment still in flight |
+
+Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
+Why it parked is the whole story, and it is `statusReason`, not `status`:
+
+- `awaiting_approval` — the plan is fine, a human has to publish it.
+  `--auto-approve` does that; without it you get exit 3 and the command to run.
+  One exception: if fabric marked any pending migration **destructive** — a
+  drop, a truncate, a rewrite — `--auto-approve` alone declines and exits 3,
+  because a standing yes was given before anyone knew the plan dropped a table.
+  The CLI lists the migrations and fabric's reasons; `--allow-destructive`
+  accepts them for that deploy.
+- `needs_config` — a declared secret or variable has no value covering the
+  stage. The CLI names them. `--auto-approve` will **not** force this through;
+  set the values (`pikku fabric secrets set <name>`) and re-attach.
+- `needs_attention` — the plan is red. Nothing to approve.
+
+`--sync` defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
+it prints the deployment id and the re-attach command rather than lying about
+the outcome.
+
+Splitting kick-off from waiting across two CI jobs is the reason
+`--deployment-id` exists:
+
+```bash
+id=$(pikku fabric deploy apply --production --auto-approve --json | jq -r 'select(.event=="result").deploymentId')
+# …later, in another job…
+pikku fabric deploy apply --deployment-id "$id" --sync --auto-approve
+```
+
+`--deployment-id` skips the git safety check entirely (the deployment already
+pins a sha, and the checkout is allowed to have moved on) and refuses to be
+combined with `--branch`/`--production`, which would let the two disagree.
+
+Under `--json`, `--sync` emits one NDJSON event per line — `created`/`attached`,
+`status` on each transition, `blocked`, `approved` — and the last line is the
+terminal result object, tagged `"event": "result"`.
 
 `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

package/skills/pikku-feature/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-feature
 description: 'Drive create-a-feature work inside a Pikku project that already exists: 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", "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 within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
-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>'
 ---

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

@@ -6,6 +6,7 @@ description: >-
   parseSlashCommand, buildSlackInstallUrl, or user asks about Slack integration, Slack bots, or
   @pikku/gateway-slack. DO NOT TRIGGER when: user asks about general gateway/webhook patterns (use
   pikku-trigger).
+installGroups: [core]
 ---
 
 # Pikku Gateway Slack

package/skills/pikku-i18n/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-i18n
 description: 'Wire i18n into a Pikku frontend with Paraglide JS (inlang). English by default, every user-facing string is a typed message function (`m.some__key()`) compiled from `messages/<locale>.json`, and additional languages are served under `/fr` `/de` URL prefixes. TRIGGER when: scaffolding or editing a frontend and writing user-facing text, adding a second language, or asked to "make this translatable / use tokens / add i18n". DO NOT TRIGGER for backend functions, error messages thrown from functions, or log output.'
-installGroups: [core]
+installGroups: [client, fabric]
 ---
 
 # Pikku i18n (Paraglide JS)

package/skills/pikku-jose/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   code uses JoseJWTService, user asks about JWT setup, token signing, token verification, or
   @pikku/jose. DO NOT TRIGGER when: user asks about session middleware (use pikku-security) or
   general service setup (use pikku-services).
+installGroups: [fabric]
 ---
 
 # Pikku Jose (JWT Service)

package/skills/pikku-knowledge/SKILL.md

@@ -13,7 +13,6 @@ description: >-
   brief to record. DO NOT TRIGGER when: user asks what
   functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
   note), or to write a scenario test (use pikku-scenario).
-installGroups: [core]
 ---
 
 # Pikku Knowledge

package/skills/pikku-kysely/SKILL.md

@@ -11,7 +11,7 @@ description: >-
   PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
   about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB (use pikku-mongodb) or
   Redis (use pikku-redis).
-installGroups: [core]
+installGroups: [fabric]
 ---
 
 # Pikku Kysely (SQL Database Services)

package/skills/pikku-machine-auth/SKILL.md

@@ -9,6 +9,7 @@ description: >-
   credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO
   NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the
   app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).
+installGroups: [fabric]
 ---
 
 # Pikku Machine Auth

package/skills/pikku-meta/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: pikku-meta
+description: >-
+  Read and change a Pikku project's declarations without grepping or hand-editing — functions
+  (with their transport, middleware and permissions), schemas, workflows, wires, tags, middleware
+  and permission definitions, plus `pikku meta apply` to set config on them. TRIGGER when: user
+  asks "what functions exist?", "show me the project structure", "list routes/middleware/
+  permissions", needs a function's input/output shape, or wants to add a permission, retag a
+  function, or change a declaration's config. DO NOT TRIGGER when: user is writing a NEW function
+  or wiring (use the specific wiring skill) or asking about Pikku concepts (use pikku-concepts).
+installGroups: [core]
+allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku info *)
+argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply]'
+---
+
+# Pikku Project Metadata
+
+`pikku meta` is the machine-readable view of the project and the write path to it.
+`pikku info` is the same ground as human-readable tables. Prefer `meta` when you are
+going to act on the output; prefer `info` when a person is going to read it.
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Discover before editing. 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. Change a declaration's config with `pikku meta apply`, not by hand-editing the file.
+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.
+
+## Reading
+
+| Command                         | What it answers                                                                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `pikku meta context`            | Everything a planner needs in one call — functions, wires, middleware, permissions, workflows, capabilities, layout. Start here. |
+| `pikku meta functions get <id>` | One function's input/output schema names, source file, tags, expose/readonly                                                     |
+| `pikku meta schemas get <name>` | One generated JSON schema                                                                                                        |
+| `pikku meta workflows get <id>` | One workflow's steps                                                                                                             |
+| `pikku meta permissions list`   | What permissions exist and where they are defined                                                                                |
+| `pikku meta middleware list`    | What middleware exists                                                                                                           |
+| `pikku meta wires list`         | Wires by transport (http, channel, scheduler, queue, trigger)                                                                    |
+| `pikku meta clients`            | Exposed RPCs/workflows/channels with their type names — what a frontend can call                                                 |
+
+`list` is the default for each group, so `pikku meta functions` and `pikku meta functions list`
+are the same call.
+
+A function's input/output shape comes from here. Do not infer it by reading the
+function body, and do not cast a call site to make it compile — the schema is the type.
+
+## Changing
+
+`pikku meta apply` applies a batch of edits to your own source. Pass JSON as a file
+or on stdin:
+
+```bash
+pikku meta apply ops.json
+```
+
+```json
+{
+  "operations": [
+    {
+      "kind": "functionConfig",
+      "sourceFile": "src/functions/todos.functions.ts",
+      "exportedName": "listTodos",
+      "changes": { "title": "List Todos", "tags": ["todos", "read"] }
+    },
+
+    {
+      "kind": "functionConfig",
+      "sourceFile": "src/functions/todos.functions.ts",
+      "exportedName": "listTodos",
+      "changes": {
+        "permissions": {
+          "functionLevel": {
+            "name": "isTodoOwner",
+            "from": "../permissions.js"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+Three kinds: `functionConfig`, `agentConfig`, `functionBody`. Every operation names
+a `sourceFile` and the `exportedName` declared in it.
+
+`functionConfig` changes: `title`, `description`, `summary`, `tags`, `errors`,
+`expose`, `remote`, `mcp`, `readonly`, `approvalRequired`, `permissions`.
+`agentConfig` changes: `name`, `description`, `instructions`, `role`, `personality`,
+`goal`, `model`, `maxSteps`, `temperature`, `toolChoice`, `tools`, `tags`.
+
+`null` removes a property. Edits are spliced into the original text, so formatting,
+comments and JSDoc survive.
+
+`permissions` and `tools` are written as identifiers rather than literals, so each
+one carries the module it comes from (`{"name": "isTodoOwner", "from": "../permissions.js"}`)
+and the missing import is added for you — widening an existing import from that
+module rather than adding a second one.
+
+### Why batch
+
+The whole batch either lands or it does not: every operation is resolved before
+anything is written, so a failure leaves every file untouched and names the
+operation that caused it. Batching is also what makes one codegen pass correct —
+**run `pikku all` once after the batch**, not once per property. The response tells
+you whether it is needed:
+
+```json
+{
+  "schemaVersion": "meta-apply.v1",
+  "applied": 2,
+  "files": ["src/functions/todos.functions.ts"],
+  "generatedMetaIsStale": true
+}
+```
+
+## Human-readable tables (`pikku info`)
+
+Four subcommands only — `functions`, `tags`, `middleware`, `permissions`. Routes,
+channels, schedulers and queues are not subcommands; they are the _transport_ column
+of `info functions --verbose`.
+
+```bash
+yarn pikku info functions --verbose --silent
+yarn pikku info tags --silent
+yarn pikku info middleware --verbose --silent
+yarn pikku info permissions --verbose --silent
+```
+
+`--silent` suppresses the banner and inspector diagnostics. It works, but it is not
+declared as an option, so every run also prints `Warning: Unknown option: --silent
+(ignored)` — the warning is wrong. Ignore that one line.
+
+`--limit N` caps rows (default 50); the footer says how many were withheld.
+On `tags`, `--verbose` swaps counts for names; elsewhere it adds columns.

package/skills/pikku-n8n-import/SKILL.md

@@ -3,6 +3,7 @@ name: pikku-n8n-import
 description: 'Use to import an n8n workflow JSON export into a runnable Pikku workflow. Triggers when the user says "import this n8n workflow", "convert this n8n export to pikku", points at an n8n `.json` export or a directory of them, or picks up after `pikku import n8n` left throwing stub functions (`STUB — generated from n8n …`, `— implement me`) or a `<workflow>.integrations.json` manifest. Owns the whole flow: run the importer, triage what it could not map, fill each stub, report any missing `@pikku/addon-*` integrations, and verify the result compiles and runs with no surviving stubs. DO NOT TRIGGER for hand-written addon wiring unrelated to an n8n import (use pikku-addon), or for authoring workflows from scratch (use pikku-workflow).'
 metadata:
   version: 1.0.0
+installGroups: [fabric]
 ---
 
 # n8n → Pikku Import

package/skills/pikku-paraglide/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-paraglide
 description: 'Generate typed, static enum-label maps for a Paraglide i18n frontend with `@pikku/paraglide`, and reconcile them against the database enum columns so a label can never silently drift from a DB value. Enum-valued labels live under a reserved `enum__<group>__<member>` message namespace; the generator emits `i18n-enum.gen.ts` typed `satisfies EnumLabel<DbEnum>`. TRIGGER when: labelling an enum/status/kind/role value in a Paraglide app, replacing a dynamic `mKey(...)`/`m[...]` lookup with a static map, wiring `@pikku/paraglide` into Vite, or reconciling i18n against `CHECK (col IN (...))` / Postgres enum columns. DO NOT TRIGGER for plain free-text UI copy (that is a normal `m.some_key()` message), backend errors, or logs.'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku Paraglide enum labels

package/skills/pikku-product-second-opinion/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-product-second-opinion
 description: 'Use when a non-technical owner (founder, PM, operator) wants a plain-language report on an app they hold but did not build — explaining how it works and how it could be better. Reads the .knowledge/ blueprint from pikku-software-archaeology and produces a layered, jargon-free report that credits what works, names what does not (with business impact + effort), and argues an opinionated better design. TRIGGER: "explain how my app works", "what would you do differently", "review my app for a non-technical audience", "I inherited/am stuck with an agency-built app", "is this built well?". DO NOT TRIGGER for: extracting the machine-readable blueprint itself (use pikku-software-archaeology), or an engineer-facing technical code review.'
-installGroups: [fabric]
 ---
 
 # Product Second Opinion

package/skills/pikku-queue/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   app. Covers wireQueueWorker, job enqueuing, progress tracking, retries, BullMQ and PgBoss
   adapters. TRIGGER when: code uses wireQueueWorker, user asks about background jobs, task queues,
   async processing, BullMQ, PgBoss, or job retries. DO NOT TRIGGER when: user asks about scheduled
-  cron tasks (use pikku-cron) or event-driven triggers (use pikku-trigger).
+  cron tasks (use pikku-schedule) or event-driven triggers (use pikku-trigger).
 installGroups: [core]
 ---
 

package/skills/pikku-react/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-react
 description: 'Set up @pikku/react in a React app: PikkuProvider context, createPikku factory, and the usePikkuRPC / usePikkuFetch hooks for direct (non-React-Query) calls. TRIGGER when: the user is bootstrapping a React frontend that talks to a Pikku backend, asks how to wire `PikkuProvider`, or needs to make one-off RPC calls outside of useQuery/useMutation. TRIGGER when: user asks about the dev actor switcher, "sign in as" / quick-login UI, useDevActors, VITE_DEV_ACTORS, or the app-missing-actor-quick-login validate finding. DO NOT TRIGGER when: the user is asking about useQuery/useMutation hooks (use pikku-react-query) or about workflows (use pikku-workflows-client).'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku React

package/skills/pikku-react-query/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-react-query
 description: 'Use the Pikku auto-generated React Query hooks (`usePikkuQuery`, `usePikkuMutation`, `usePikkuInfiniteQuery`) to call backend RPC functions from a React frontend with full type safety. TRIGGER when: writing React components that need to call a Pikku function, fetch data, mutate data, or paginate; user mentions React Query, useQuery, useMutation, or building a frontend that talks to a Pikku backend. DO NOT TRIGGER when: working on the backend (use pikku-rpc / pikku-feature) or wiring a non-React frontend.'
-installGroups: [core]
+installGroups: [client, fabric]
 ---
 
 # Pikku React Query Hooks

package/skills/pikku-realtime/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-realtime
 description: 'Use Pikku''s realtime feature — typed pub/sub events over WebSocket (multi-topic) or SSE (single-topic, auto-cleanup). Covers declaring EventHubTopics, scaffolding the /events channel, the auto-generated `PikkuRealtime` client, and publishing events from a function. TRIGGER when: the user asks for realtime updates, pub/sub, push notifications, server-sent events, websocket events, eventhub, or "live" data on the frontend. DO NOT TRIGGER when: the user wants RPC-style request/response (use pikku-rpc / pikku-react-query) or a custom one-off WebSocket channel (use pikku-websocket).'
-installGroups: [core]
 ---
 
 # Pikku Realtime

package/skills/pikku-rpc/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   TRIGGER when: code uses wire.rpc or expose: true, user asks about calling one Pikku function
   from another, function composition, or RPC endpoints. DO NOT TRIGGER when: user asks about HTTP
   routes (use pikku-http) or addon cross-package calls (use pikku-addon).
-installGroups: [core]
+installGroups: [fabric]
 ---
 
 # Pikku RPC Wiring

package/skills/pikku-rtl/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-rtl
 description: 'Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku RTL (Arabic + English)