@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-kysely/SKILL.md

@@ -9,9 +9,9 @@ description: >-
   non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
   conditional query), the injected `kysely` service is used in a function body, or code uses
   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]
+  about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
+  services (use pikku-service-backends).
+installGroups: [core]
 ---
 
 # Pikku Kysely (SQL Database Services)
@@ -216,15 +216,15 @@ Each database variant exports these services with a prefix (`Pg`, `MySQL`, `SQLi
 A handful more live only on the base package — there is no `Pg`/`MySQL`/`SQLite`
 variant to reach for, you import them from `@pikku/kysely` whatever the engine:
 
-| Service                      | Purpose                                      |
-| ---------------------------- | -------------------------------------------- |
-| `KyselySessionStore`         | Persisted user sessions                      |
-| `KyselyScopeService`         | Scope and role storage                       |
-| `KyselyWebhookService`       | Webhook registrations and deliveries         |
-| `KyselyCredentialService`    | Encrypted third-party credentials            |
-| `KyselyAgentRunStateService` | AI run state (also implemented by AIStorage) |
-| `KyselyWorkflowMirror`       | Mirrors workflow runs into queryable tables  |
-| `KyselyAuditService`         | Durable audit sink (see `pikku-audit`)       |
+| Service                      | Purpose                                                             |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `KyselySessionStore`         | Persisted user sessions                                             |
+| `KyselyScopeService`         | Scope and role storage                                              |
+| `KyselyWebhookService`       | Outgoing webhook deliveries + attempt history (see `pikku-webhook`) |
+| `KyselyCredentialService`    | Encrypted third-party credentials                                   |
+| `KyselyAgentRunStateService` | AI run state (also implemented by AIStorage)                        |
+| `KyselyWorkflowMirror`       | Mirrors workflow runs into queryable tables                         |
+| `KyselyAuditService`         | Durable audit sink (see `pikku-services`)                           |
 
 All services take a `Kysely<KyselyPikkuDB>` instance in their constructor and have an `init()` method that creates tables if needed.
 
@@ -257,7 +257,7 @@ const newVersion = await secrets.rotateKEK()
 
 `getSecret` hands back a `SecretValue<T>`, not the bare value — it serializes as
 `[secret]` until something reveals it, which is what stops a secret drifting into
-a log line or an audit row. See `pikku-config` for the reveal rules.
+a log line or an audit row. See `pikku-services` for the reveal rules.
 
 ## Usage Patterns
 

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

@@ -0,0 +1,163 @@
+---
+name: pikku-list-query
+description: >-
+  Use when building a paginated/infinite-scroll list — any RPC that returns rows a user scrolls through (tables, card grids, search results). Covers pikkuListFunc, the ListInput/ListOutput cursor contract, and the generated usePikkuInfiniteQuery hook.
+  TRIGGER when: user asks for infinite scroll, "load more", a paginated table/list/grid, or a list that could grow beyond a single page.
+  DO NOT TRIGGER when: the list is small and fixed (e.g. a settings page with 5 items) — a plain pikkuFunc + usePikkuQuery returning a full array is simpler and correct there.
+installGroups: [core, client]
+---
+
+# Pikku List Queries
+
+## Agent Operating Procedure
+
+1. Capture baseline. Run `pikku all` BEFORE writing code; only NEW errors are yours to fix.
+2. Write the backend function with `pikkuListFunc` (below) — never a bespoke `{items: [...]}` shape once the list can page.
+3. Run `pikku all` to regenerate `usePikkuInfiniteQuery` for the new function.
+4. Wire the frontend with `usePikkuInfiniteQuery`, not a hand-rolled `useState` page counter and not a raw `useInfiniteQuery` — the generated hook already resolves cursor plumbing from your function's types.
+5. Validate with `pikku all`.
+
+## The `pikkuListFunc` contract
+
+A list function is a normal `pikkuFunc`/`pikkuSessionlessFunc` whose input/output conform to two shared shapes from `@pikku/core`:
+
+```typescript
+interface ListInput<F extends Record<string, unknown> = {}, S extends string = never> {
+  cursor?: string // opaque — echo back whatever you returned as nextCursor
+  limit?: number // page size; server may cap it
+  sort?: Array<{ column: S; direction: 'asc' | 'desc' }>
+  filter?: Filter<F> // structured AND/OR tree, Prisma-style leaf operators
+  search?: string // free-text search across server-chosen fields
+}
+
+interface ListOutput<Row> {
+  rows: Row[]
+  nextCursor: string | null // null = no more pages
+  totalCount?: number // optional — skip when expensive to compute
+}
+```
+
+Adopting this shape is what makes the function eligible for the generated `usePikkuInfiniteQuery` hook — the react-query codegen structurally detects any RPC whose output includes `nextCursor` and generates an infinite-query hook for it automatically. No manual wiring, no opt-in flag.
+
+```typescript
+import { pikkuListFunc } from '#pikku/function'
+
+interface Item {
+  id: string
+  label: string
+}
+
+export const listItems = pikkuListFunc<{ status?: string }, Item>({
+  expose: true,
+  auth: true,
+  readonly: true,
+  description: 'List items for the signed-in user, paginated.',
+  // `input` is inferred as ListInput<{ status?: string }> from the generics above —
+  // never re-annotate it inline.
+  func: async ({ kysely }, input, { session }) => {
+    // `limit` is caller-supplied on an exposed RPC, so it is CAPPED, not trusted —
+    // `ListInput` says "server may cap" and this is where that happens.
+    const limit = Math.min(Math.max(Math.trunc(input.limit ?? 20) || 20, 1), 100)
+    const parsed = input.cursor ? Number(input.cursor) : 0
+    const offset = Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : 0
+
+    let query = kysely.selectFrom('item').where('userId', '=', session!.userId)
+    const status = leafEquals(input.filter, 'status')
+    if (status !== undefined) {
+      query = query.where('status', '=', status)
+    }
+
+    const rows = await query.orderBy('createdAt', 'desc').offset(offset).limit(limit).execute()
+    const nextOffset = offset + rows.length
+    const totalCount = await query
+      .select((eb) => eb.fn.countAll<number>().as('count'))
+      .executeTakeFirstOrThrow()
+
+    return {
+      rows: rows.map((r) => ({ id: r.id, label: r.label })),
+      nextCursor: nextOffset < totalCount.count ? String(nextOffset) : null,
+      totalCount: totalCount.count,
+    }
+  },
+})
+```
+
+Cursor doesn't have to be a numeric offset — any opaque string works (a keyset value, an encoded timestamp, etc.), as long as you can turn it back into a query position on the next call.
+
+## Frontend: `usePikkuInfiniteQuery`
+
+Generated automatically alongside `usePikkuQuery`/`usePikkuMutation` once `reactQueryFile` is configured (see the react-query wiring docs) — no separate setup for list functions specifically.
+
+```tsx
+import { usePikkuInfiniteQuery } from '.pikku/pikku-react-query.gen'
+
+function ItemList() {
+  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = usePikkuInfiniteQuery(
+    'listItems',
+    { limit: 20 }, // never pass cursor here — the hook manages it
+  )
+
+  const rows = data?.pages.flatMap((page) => page.rows) ?? []
+
+  return (
+    <>
+      {rows.map((row) => (
+        <div key={row.id}>{row.label}</div>
+      ))}
+      {hasNextPage && (
+        <button disabled={isFetchingNextPage} onClick={() => fetchNextPage()}>
+          Load more
+        </button>
+      )}
+    </>
+  )
+}
+```
+
+For scroll-triggered loading (rather than a button), pair it with an `IntersectionObserver` sentinel at the end of the list that calls `fetchNextPage()` when it enters the viewport and `hasNextPage` is true — don't poll on a scroll event handler.
+
+## Common mistakes
+
+- **Bespoke output shape** (`{items, total}` with no `nextCursor`) — compiles, but disqualifies the function from `usePikkuInfiniteQuery`; you're left hand-rolling pagination state. Use `ListOutput<Row>`'s field names (`rows`, `nextCursor`) even if you don't need `filter`/`sort`/`search` yet — they're optional.
+- **Fixed large `limit` instead of real pagination** (e.g. `{ limit: 500 }` fetched once) — works until the collection outgrows the cap, then silently truncates. If a list can grow unbounded, page it from the start.
+- **Passing `cursor` manually into `usePikkuInfiniteQuery`'s input argument** — the hook injects it into each page request itself; the input you pass is the _base_ filter/limit shared by every page.
+
+## `filter` is a TREE, not a bag of fields
+
+`Filter<F>` is recursive: an **array** is an AND of its children, a **multi-key object** is
+an OR keyed by labels that mean nothing at evaluation time, and only a **single-key object**
+is a leaf. A leaf's value is either the value itself or an operator object
+(`{ contains, in, gt, gte, lt, lte, not, startsWith, … }`).
+
+So `'status' in input.filter` answers `false` for `[{ status: 'open' }, { userId: 'u1' }]`
+and for `{ status: { in: ['open', 'held'] } }` — the first because the filter is an array,
+the second because the value is an operator object rather than the string the code then
+compares. Both cases **silently return unfiltered rows**, which on a list endpoint means
+handing back records the caller asked to exclude. Pikku ships no filter-to-SQL helper: the
+backend decides what it accepts, and it has to say so.
+
+Read exactly the shape you support, and refuse the rest rather than ignoring it:
+
+```typescript
+import type { Filter } from '@pikku/core/function'
+
+/** The one shape this endpoint accepts: a single-key leaf with a plain value. */
+function leafEquals<F extends Record<string, unknown>, K extends keyof F & string>(
+  filter: Filter<F> | undefined,
+  field: K,
+): F[K] | undefined {
+  if (!filter || Array.isArray(filter)) return undefined
+  const keys = Object.keys(filter)
+  if (keys.length !== 1 || keys[0] !== field) return undefined
+  const value = (filter as Record<string, unknown>)[field]
+  if (value !== null && typeof value === 'object') {
+    throw new Error(`filter.${field} takes a value, not an operator object`)
+  }
+  return value as F[K]
+}
+```
+
+Supporting AND/OR or operators means walking the tree properly — recurse into the array and
+the multi-key object, and map each leaf operator to its Kysely equivalent. Do that when the
+UI needs it; until then, throwing on the shapes you do not handle is what stops a filter
+from being quietly dropped.

package/skills/pikku-meta/SKILL.md

@@ -1,139 +1,67 @@
 ---
 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).
+  Use to inspect or evolve a project you did not just write — `pikku meta` and `pikku info` for
+  what the project declares (functions, schemas, wires, workflows, middleware, permissions) and
+  `pikku meta apply` to change it, `pikku versions` / `pikku semver` for contract hashes,
+  breaking-change detection and the semver a release should get, and `pikku audit` / `pikku
+  update` for dependency advisories and moving Pikku forward. TRIGGER when: user asks what
+  functions or routes exist, wants a function's input/output shape, wants to retag a function or
+  set config on a declaration, asks about API versioning, breaking changes, what semver a release
+  deserves, dependency vulnerabilities, the console Security screen, or upgrading Pikku. DO NOT
+  TRIGGER when: user is writing a new function or wiring (use the 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]'
+argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply|versions|semver|audit|update]'
 ---
 
 # 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.
+The project already knows what it declares. Ask it rather than grepping for it,
+and change it through the write path rather than by hand.
+
+## Pick the reference
+
+| You are… | Read |
+| --- | --- |
+| Asking what exists, or setting config on a declaration | `references/meta.md` |
+| Versioning a contract, or deciding a release's semver | `references/versioning.md` |
+| Chasing a dependency advisory, or upgrading Pikku | `references/audit.md` |
+
+## Start with `pikku meta context`
+
+It answers in one call what a planner needs — functions, wires, middleware,
+permissions, workflows, capabilities, layout. Reach for `pikku meta` when you
+are going to act on the output and `pikku info` when a person will read it;
+they are the same ground in two shapes.
+
+## Direction decides whether a change is breaking
+
+An input is contravariant (the caller writes it) and an output is covariant (the
+caller reads it), so the same edit is not the same event on both. Adding a
+required field breaks an input and is compatible on an output; making a field
+optional is the reverse. `pikku semver` reads the generated JSON Schemas with
+that asymmetry built in, so let it decide rather than eyeballing a diff.
+
+## What NOT to do
+
+- **Do not infer a function's input or output by reading its body**, and do not
+  cast a call site to make it compile. The schema is the type; `pikku meta
+  functions get <id>` has it.
+- **Do not expect an unversioned function to be promoted for you.** Without an
+  explicit `version: 2` it is version 1 of its contract, collides with the
+  pinned `@v1`, and `pikku versions check` reports the published contract as
+  modified.
+- **Do not reach for `override` by default.** The contract key already drops a
+  matching `V<n>` suffix from the export name, so `getBookV1` keys under
+  `getBook`. `override` is for an export that cannot follow that convention.
+- **Do not shell out to the package manager from a function.** The audit is a
+  generated artifact — read `.pikku/audit.json` through
+  `metaService.readFile('audit.json')`.
+- **Do not redeclare the audit report's shape.** `SecurityAuditReport` and its
+  companions come from `@pikku/core`; the CLI writes it, the addon reads it, the
+  UI renders it.
+- **Do not treat a failed audit run as a clean one.** `bun audit` exits non-zero
+  when it *finds* advisories and still writes its payload, so non-zero with
+  output is data; non-zero with no output throws on purpose.

package/skills/{pikku-deps/SKILL.md → pikku-meta/references/audit.md}

@@ -1,19 +1,3 @@
----
-name: pikku-deps
-description: >-
-  Use for the Pikku dependency security audit: the `pikku audit` CLI command, the
-  `.pikku/audit.json` artifact, the `SecurityAuditReport` type in @pikku/core, and the console
-  Security screen (getSecurityAudit / runSecurityAudit / updateDependency + SecurityAuditView).
-  Also covers `pikku update`, which moves the @pikku/* dependency set forward and reports the
-  peers those versions need.
-  TRIGGER when: user asks about `pikku audit` or `pikku update`, dependency
-  vulnerabilities/advisories, outdated dependencies, upgrading Pikku itself, peer dependency
-  conflicts, the Security screen/page in the console, updating a vulnerable dependency, or
-  reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT
-  (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use
-  pikku-config).
----
-
 # Pikku Dependency Audit
 
 ## Agent Operating Procedure
@@ -98,7 +82,7 @@ lockfiles, because that field states intent before a lockfile exists and a
 project can carry a stale one from another tool. Guessing wrong is not a soft
 failure: the spawn dies with `Executable not found in $PATH`.
 Like every console RPC these require an **authenticated session** (the console
-is admin-only), so the host must have Better Auth wired — see `pikku-better-auth`.
+is admin-only), so the host must have Better Auth wired — see `pikku-auth`.
 
 - `getSecurityAudit` — reads `.pikku/audit.json`, returns the report (or `null`).
 - `runSecurityAudit` — runs `pikku audit --outdated` server-side (regenerates the

package/skills/pikku-meta/references/meta.md

@@ -0,0 +1,114 @@
+# 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.
+
+
+## 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-versioning/SKILL.md → pikku-meta/references/versioning.md}

@@ -1,31 +1,5 @@
----
-name: pikku-versioning
-description: >-
-  Use when versioning Pikku function contracts, detecting breaking changes, or managing API
-  backward compatibility. Covers the version property, versions.pikku.json manifest, contract
-  hashing, and CI integration. Also covers `pikku semver`, which derives a release's semver by
-  diffing this build's surface against a deployed one and writes .pikku/changes.gen.json.
-  TRIGGER when: code uses version: on a pikkuFunc, user asks about
-  API versioning, breaking changes, contract hashes, backward compatibility, what semver a
-  release should get, comparing against production/staging, or "pikku versions" / "pikku semver"
-  CLI commands. DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config)
-  or general function definitions (use pikku-concepts), or about updating dependency versions
-  (use pikku-deps).
----
-
 # Pikku Function Versioning
 
-## 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. 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.
-
-Track and protect function contracts across releases. Pikku hashes each function's input/output schema into a manifest so you can detect breaking changes before they ship.
 
 ## Before You Start
 

package/skills/pikku-middleware/SKILL.md

@@ -6,8 +6,8 @@ description: >-
   understanding middleware execution order and priority. TRIGGER when: user wants middleware on
   some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global
   interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about
-  permissions/authorization checks (use pikku-permissions), auth strategies like
-  authBearer/authCookie (use pikku-security), or deployment.
+  permissions, sessions or auth strategies like authBearer/authCookie (use
+  pikku-auth), or deployment.
 installGroups: [core]
 ---
 
@@ -223,7 +223,7 @@ export const reportSomething = pikkuFunc({
 })
 ```
 
-An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-permissions`).
+An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-auth`).
 
 ### It MUST be `addHTTPMiddleware`, never `addTagMiddleware`
 
@@ -255,13 +255,13 @@ Unlike tag middleware over `/rpc`, this works: `runScheduledTask` builds its wir
 
 ### The one sessionless exception: bootstrap
 
-An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-permissions`).
+An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-auth`).
 
 ## Service-to-Service Bearer Auth (gate-only pattern)
 
 Use this when the callee needs to know only THAT the caller is trusted, not WHICH caller it is. If it needs to know which, use the session pattern above.
 
-A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
+A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-auth`), never inside `func`.
 
 **On the server (the service being called):** tag the function, register a `pikkuMiddleware` that reads the `Authorization` header on that tag.
 

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

@@ -3,7 +3,6 @@ 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