@pikku/skills 0.12.14 → 0.12.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.14",
+  "version": "0.12.16",
   "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,6 +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: [fabric]
 ---
 
 # Pikku AI Vercel (Agent Runner)

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

@@ -10,6 +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: [fabric]
 ---
 
 # Pikku Better Auth Integration
@@ -136,21 +137,21 @@ resolves the caller's scopes through the registered `ScopeService` and checks th
 `admin:*` tree (`ADMIN_SCOPES` exports the ids so you never spell them as bare
 strings):
 
-| Gate                                                                 | Scope required           |
-| -------------------------------------------------------------------- | ------------------------ |
-| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate`      |
-| `credentialOAuth`'s `canLinkSingleton`                               | `admin:credentials:link` |
-| the console's user directory                                         | `admin:users:list`       |
-| create a user out of band                                            | `admin:users:create`     |
-| ban / unban                                                          | `admin:users:ban`        |
-| delete a user and their data                                         | `admin:users:remove`     |
-| revoke a user's sessions                                             | `admin:users:sessions`   |
-| set a user's password                                                | `admin:users:password`   |
-| read credential values and who holds them                            | `admin:credentials:read` |
+| Gate                                                                 | Scope required             |
+| -------------------------------------------------------------------- | -------------------------- |
+| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate`        |
+| `credentialOAuth`'s `canLinkSingleton`                               | `admin:credentials:link`   |
+| the console's user directory                                         | `admin:users:list`         |
+| create a user out of band                                            | `admin:users:create`       |
+| ban / unban                                                          | `admin:users:ban`          |
+| delete a user and their data                                         | `admin:users:remove`       |
+| revoke a user's sessions                                             | `admin:users:sessions`     |
+| set a user's password                                                | `admin:users:password`     |
+| read credential values and who holds them                            | `admin:credentials:read`   |
 | set and delete credentials                                           | `admin:credentials:manage` |
-| view declared scopes, roles, and who holds them                      | `admin:scopes:read`      |
-| create roles, change their scopes, grant them                        | `admin:scopes:manage`    |
-| read the audit trail                                                 | `admin:audit:read`       |
+| view declared scopes, roles, and who holds them                      | `admin:scopes:read`        |
+| create roles, change their scopes, grant them                        | `admin:scopes:manage`      |
+| read the audit trail                                                 | `admin:audit:read`         |
 
 Holding the bare `admin` scope satisfies all of them — a parent grant covers
 everything nested beneath it — so `admin` is the direct replacement for the old
@@ -246,6 +247,112 @@ create a session for a banned user, lapsing an expired ban as it goes. It makes
 no authorization decision — who may ban is decided by `admin:users:ban` — so it
 never needs to know about scopes or roles.
 
+### The plugins `@pikku/better-auth` ships
+
+Five, all imported from the package root and passed to `betterAuth({ plugins })`
+like any other. None is automatic — an app wires the ones it needs.
+
+| Plugin              | Plugin `id`        | Adds                                                                    | Use it when                                                   |
+| ------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `ban()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
+| `actor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
+| `credentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
+| `delegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
+| `fabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+
+The plugin's `id` is what better-auth stores; the **export name** is what the
+inspector reads off your `plugins` array and what generated metadata is keyed
+by, so the two differ for `ban` and `delegatedAuth`.
+
+#### `credentialOAuth()` — link API credentials, not identities
+
+```typescript
+credentialOAuth({
+  config: [
+    {
+      providerId: 'github',
+      type: 'wire',
+      clientId,
+      clientSecret,
+      authorizationUrl,
+      tokenUrl,
+      scopes: ['repo'],
+    },
+    { providerId: 'slack', type: 'singleton' /* … */ },
+  ],
+  scopeService,
+  logger,
+})
+```
+
+Wraps better-auth's `genericOAuth` to keep its token exchange and refresh, and
+replaces only the two identity-bound endpoints. `genericOAuth`'s own
+`/oauth2/link` models an identity **provider**: it demands a userinfo response
+and refuses to link when the provider's email differs from the user's. A
+credential is not an identity — most credential providers expose only
+`/authorize` and `/token` — so the account row is keyed on _whose_ credential it
+is (`accountId` = the linking user's id), making `(providerId, userId)` unique
+by construction. Tokens land in better-auth's `account` table, so
+`auth.api.getAccessToken()` refreshes them on read.
+
+`type` decides the blast radius:
+
+- **`wire`** — every user links their own, and the credential is read on
+  the wire that runs as them. Signed in is enough.
+- **`singleton`** — one token the whole app shares, owned by a reserved
+  `pikku-platform` user row created on demand. Rebinding it changes the
+  credential for _everyone_, so it is gated on `admin:credentials:link` (or the
+  `admin` root above it), and **fails closed** with no `ScopeService`. Override
+  the whole gate with `canLinkSingleton`.
+
+An undeclared `providerId` is a 404; an anonymous caller a 401; a refused
+singleton a 403 that leaves no platform user behind.
+
+#### `delegatedAuth()` — the upstream API is the identity provider
+
+```typescript
+delegatedAuth({
+  authenticate: async ({ email, password, apiKey }) => upstream.login(...),
+  storeCredential: (userId, identity) =>
+    credentialService.set('acme', identity.credential, userId),
+  defaultRole: 'member',
+  mapRole: (upstreamRole) => ROLE_MAP[upstreamRole],
+  scopeService,
+  logger,
+})
+```
+
+`POST /sign-in/delegated` forwards the credentials the user already has to
+`authenticate`. On success it JIT-provisions a real user row (email-keyed and
+`emailVerified` — the upstream just verified them), links it via an `account`
+row (`providerId: 'delegated'`, `accountId: externalId`), persists the upstream
+token **before** minting the session, and returns a normal session cookie.
+Passwords are never stored. Exactly one upstream per app: additional imported
+APIs are linked integrations (`credentialOAuth`), not extra login methods.
+
+A resolved role is granted through the `ScopeService` as a pikku role, so it
+lands in `pikku_user_role` rather than on a column. A role the app never
+defined is a provisioning gap, not a sign-in failure — the grant is dropped with
+a warning and the user still gets in.
+
+`storeCredential` failing, by contrast, **fails the sign-in**: every proxied
+call would be dead anyway.
+
+#### `fabric()` — control-plane operator sign-in
+
+```typescript
+fabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
+```
+
+`POST /sign-in/fabric` verifies a short-lived RS256 token that the Fabric
+control plane signed for an operator session, then signs them into a synthetic
+`fabric-<id>@fabric.internal` row holding the `admin` scope. Asymmetric on
+purpose: the app holds only the public key, so it can never forge an operator
+login, and the same `FABRIC_AUTH_PUBLIC_KEY` is distributed to every stage with
+no per-environment secret. A missing or empty key disables the endpoint, and a
+token whose `purpose` claim is not `fabric-admin` is rejected. Without a
+`ScopeService` the operator signs in holding nothing.
+
 ### 2. Production database adapter
 
 For real deployments swap `memoryAdapter` for the Kysely adapter backed by an injected DB. Better Auth owns its own tables (`user`, `session`, `account`, `verification`, plus plugin tables) — generate its schema with `npx @better-auth/cli generate` and apply it as a migration.
@@ -370,14 +477,35 @@ plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
 session cookie. `secret` may also be a (possibly async) function, so it can come
 off the secrets service instead of a captured value.
 
+**Which command is running decides whether it works, not whether a secret is
+set.** `pikku dev` sets `PIKKU_DEV_ACTOR_SIGN_IN` and mints an ephemeral
+`SCENARIO_ACTOR_SECRET` for the run, so local development needs no configuration
+at all. Everywhere else the endpoint refuses (`Actor sign-in is disabled outside
+\`pikku dev\``) — `pikku serve` clears the marker outright, so a secret that
+leaked into a production environment enables nothing and gets a warning naming
+itself instead.
+
+A stage that genuinely must run scenarios opts in on purpose, with
+`PIKKU_ALLOW_ACTOR_SIGN_IN=passwordless-actor-sign-in`. Any other value is
+ignored and warned about, so the hatch cannot be opened by copying a `true` from
+the line above, and it is the only hatch — there is no build-time option, because
+an option compiled into the bundle cannot be audited from the environment it
+runs in.
+
+**Signing in and provisioning are separate powers.** An unknown address becomes
+an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
+in as the personas the deployment provisioned when it started and refuses
+everything else (`No actor account exists for that address`), so holding the
+secret on such a stage does not let anyone invent identities. Those rows are
+written by `provisionPersonas` from `@pikku/better-auth`, called in the server's
+own lifecycle, so provisioning needs no actor secret and works on a stage whose
+endpoint is shut.
+
 **`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
-persona.** `pikku persona sync` grants declared roles to actor accounts, so an
-`admin` persona is an actor holding real admin — anyone with the secret can take
-a session as one. Keep the endpoint **off outside development and sandbox
-deployments**: leave the secret unset on any stage that should not run scenarios,
-which is the supported switch (`Actor sign-in is not configured`), rather than
-conditionally registering the plugin. Do not treat "actors only" as a licence to
-enable it in production.
+persona.** Provisioning grants declared roles to actor accounts, so an
+`admin` persona is an actor holding real admin — anyone with the secret _and_ the
+opt-in can take a session as one. Do not treat "actors only" as a licence to open
+the hatch in production.
 
 Within that boundary, three properties bound the damage:
 
@@ -385,9 +513,9 @@ Within that boundary, three properties bound the damage:
   column; an email matching a row without it is refused with `User is not an
 actor`. So the secret cannot take over a **real user's** account — the blast
   radius is the actor accounts and whatever roles they were granted.
-- **Unknown emails are created**, flagged `actor: true`, so a scenario that
-  declares a new persona needs no seed step. Note the flip side: the secret
-  mints accounts, it does not merely use existing ones.
+- **Unknown emails are created only under `pikku dev`**, flagged `actor: true`,
+  so a local scenario declaring a new persona needs no seed step. Anywhere else
+  the account has to have been provisioned at boot first.
 - **The comparison is constant-time and length-hiding**, so a wrong secret leaks
   neither the length nor a prefix of the right one.
 
@@ -395,6 +523,65 @@ This is the endpoint `pikku scenario` signs its actors in through, and the one
 the frontend dev switcher posts to — see `pikku-scenario` for declaring the
 actors and `pikku-react` for `useDevActors()`.
 
+### Provisioning personas (`provisionPersonas`)
+
+Anywhere but `pikku dev`, the accounts have to exist before anyone signs in.
+The deployment creates them itself, from its own lifecycle:
+
+```ts
+import { provisionPersonas } from '@pikku/better-auth'
+import {
+  personaConfigs,
+  personaEnvironments,
+} from '#pikku/pikku-personas.gen.js'
+
+await provisionPersonas(singletonServices, {
+  personas: personaConfigs,
+  environments: personaEnvironments,
+})
+```
+
+It runs where the database already is, which is the point: the CLI has no
+connection to a deployed environment's database — it resolves one from the local
+project config — so a `pikku persona sync staging` that wrote rows would write
+them to whatever database the checkout happened to point at. `pikku persona sync
+<environment>` still exists, and reports who that environment will provision and
+why anyone was skipped, which is what you run _before_ the deploy.
+
+It creates missing accounts as `actor: true`, applies the roles each persona
+declares, and is additive — it never revokes. `PIKKU_ENV` (or an explicit
+`environment`) selects who is eligible, through the same rule that decides who
+may run there; an address already held by a real, non-actor user throws rather
+than being granted the persona's roles.
+
+**Deleting a persona does not delete its account.** Being additive leaves a hole:
+the account keeps every role it was granted, and the actor endpoint authenticates
+on the `actor` column alone without consulting the declaration — so an `admin`
+persona nobody declares any more is still a live way in wherever that endpoint is
+open. By default provisioning warns about those accounts and changes nothing.
+`orphans: 'ban'` shuts them:
+
+```ts
+await provisionPersonas(singletonServices, {
+  personas: personaConfigs,
+  environments: personaEnvironments,
+  orphans: 'ban',
+})
+```
+
+It writes the same `banned` column the console's ban RPC writes (so it needs the
+`ban()` plugin wired, and says so if it isn't), revokes the account's sessions,
+and leaves the row, its grants and its history intact — provisioning lifts the
+ban again by itself if the persona comes back. Deleting is deliberately not
+offered: an actor row is referenced by whatever those scenarios did while it
+existed.
+
+`report` is the default because a rolling deploy runs the new replica's
+provisioning while the old replica is still serving, so for the length of that
+overlap "no persona claims this" is a statement about the newer declaration only.
+A persona pinned to another environment counts as unclaimed here — it has no
+business holding a signable account in an environment its own rule refuses it.
+
 ---
 
 ## Secret Management

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

@@ -325,7 +325,9 @@ or not the note says `built`.
    for working on an empty state the test data would hide). Because reset always
    arrives at a database it just wiped, **the seed file is plain `INSERT`s** — no
    `ON CONFLICT DO NOTHING`, no `INSERT OR IGNORE`. Nothing ever applies it
-   twice, so it never has to defend itself.
+   twice, so it never has to defend itself. It is also **local only** — no deploy
+   applies it, so anything the app would be broken without in production is
+   configuration and belongs in a migration, not here.
    Do this generously and do it now: an empty app demos badly and critiques
    badly, and you cannot judge a screen's hierarchy, overflow, or truncation
    against zero rows. Seed rows each persona sees differently — with an ownership

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

@@ -115,7 +115,9 @@ Then, in this order — it is the order codegen depends on:
 2. **Seed** — rows in `db/sqlite-dev-seed.sql`. There is no seed command:
    `bunx --bun pikku db reset` wipes, migrates and seeds in one go, and is the
    only thing that applies the file. It always starts from a wiped database, so
-   the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. **Be generous, and
+   the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. It is local only:
+   no deploy applies it, so anything the app cannot run without belongs in a
+   migration instead. **Be generous, and
    seed rows for both personas.** An empty app demos badly, and you cannot see a
    layout break against zero rows.
 3. **Functions** — one `pikkuFunc` per `*.function.ts`, `expose: true`. Pikku

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-emails/SKILL.md

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

package/skills/pikku-fabric/SKILL.md

@@ -109,11 +109,25 @@ plain `INSERT`s** — no `INSERT OR IGNORE`, no `ON CONFLICT DO NOTHING`, no
 you find yourself reaching for an idempotent form, that's a sign the data wants
 to be a migration instead.
 
-This is **test data only**: enough rows that a fresh dev database isn't an empty
-app. It never reaches staging or production — reset refuses `NODE_ENV=production`
-and refuses a database outside the runtime directory. Anything a real environment
-needs — accounts, role grants — is provisioning, not seeding, and belongs in
-`pikku persona sync` or a migration.
+This is **local dev data only**: enough rows that a fresh dev database isn't an
+empty app. Nothing else ever runs it. A deployed stage applies `db/<engine>/*.sql`
+and stops there — reset refuses `NODE_ENV=production` and refuses a database
+outside the runtime directory, and no deploy step reaches for the seed file.
+
+So the test is not "is this row realistic?", it is **"would the app be broken
+without it in production?"** If yes, it is configuration and belongs in a
+migration, however much it looks like sample data. A venue and its rooms, a
+product catalogue, a tenant, a country list, the organization the whole
+deployment hangs off — all configuration. Accounts and role grants are
+provisioning: `provisionPersonas` at deployment, or a migration. What is left
+over is the seed's job — the bookings, orders and messages a demo needs and a real
+environment starts without.
+
+Get this wrong and it hides: the app is perfect locally, where reset has just
+run, and every deployed environment comes up with empty tables. The signature is
+a stage whose pages return 200 — the shell renders fine — while its first data
+read throws `no result` or a foreign-key violation on a row the seed was
+silently supplying.
 
 A Better Auth app has a second constraint: the plugins you enable (`ban()`,
 `actor()`, …) each declare columns, and `pikku db migrate` refuses to run while

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: [client]
+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-kysely/SKILL.md

@@ -11,6 +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: [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-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: [client]
+installGroups: [client, fabric]
 ---
 
 # Pikku React Query Hooks

package/skills/pikku-rpc/SKILL.md

@@ -6,6 +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: [fabric]
 ---
 
 # Pikku RPC Wiring

package/skills/pikku-ws/SKILL.md

@@ -5,6 +5,7 @@ description: >-
   adapter for Pikku channels. TRIGGER when: code uses @pikku/ws, user asks about ws library
   WebSocket server, or Node.js WebSocket runtime. DO NOT TRIGGER when: user asks about WebSocket
   wiring/channels (use pikku-websocket) or uWebSockets (use pikku-deploy-uws).
+installGroups: [fabric]
 ---
 
 # Pikku WS (WebSocket Server Runtime)