@pikku/skills 0.12.57 → 0.12.59

package/skills/pikku-kysely/SKILL.md

@@ -1,9 +1,14 @@
 ---
 name: pikku-kysely
 description: >-
-  Use when WRITING KYSELY QUERIES (select, join, aggregate, insert, update, delete) inside a Pikku function body, or when setting up SQL database services with Kysely. Covers the query builder API (joins, groupBy/having, returning, sql template, $if, transactions, jsonArrayFrom), how many round trips a function body costs and how to collapse sequential awaits into one statement, and @pikku/kysely service setup (channel stores, workflow, secret, AI storage and deployment services).
-  TRIGGER when: writing any non-trivial kysely query (join, count/sum, groupBy, subquery, transaction, conditional query), a function body awaits more than one query, the injected `kysely` service is used, code uses PikkuKysely, KyselyChannelStore, KyselyWorkflowService or KyselySecretService, or the user asks about SQL setup with Pikku.
-  DO NOT TRIGGER when: the services are MongoDB or Redis backed (use pikku-service-backends), or the task is the pagination contract rather than the query (use pikku-list-query).
+  Writing Kysely queries (select, join, aggregate, insert, update, delete, transactions, sql
+  template, jsonArrayFrom) in Pikku function bodies, collapsing sequential awaits into fewer round
+  trips, and @pikku/kysely service setup (channel stores, workflow, secret, AI storage, deployment).
+  TRIGGER when: writing a non-trivial kysely query, a function body awaits several queries, the
+  injected `kysely` service or
+  PikkuKysely/KyselyChannelStore/KyselyWorkflowService/KyselySecretService is used, or asked about
+  SQL setup. DO NOT TRIGGER for MongoDB/Redis services (use pikku-service-backends) or the
+  pagination contract (use pikku-list-query).
 installGroups: [core]
 ---
 
@@ -119,15 +124,27 @@ just stop queuing behind each other.
 
 ```typescript
 // Three hops, in series
-const item = await kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst()
-const bins = await kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute()
-const moves = await kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute()
+const item = await kysely
+  .selectFrom('item')
+  .where('id', '=', id)
+  .selectAll()
+  .executeTakeFirst()
+const bins = await kysely
+  .selectFrom('bin')
+  .where('warehouseId', '=', wid)
+  .selectAll()
+  .execute()
+const moves = await kysely
+  .selectFrom('stockMove')
+  .where('itemId', '=', id)
+  .selectAll()
+  .execute()
 
 // One hop's worth of latency
 const [item, bins, moves] = await Promise.all([
-  kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst(),
-  kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute(),
-  kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute(),
+  kysely.selectFrom('item').where('id', '=', id).selectAll().executeTakeFirst(),
+  kysely.selectFrom('bin').where('warehouseId', '=', wid).selectAll().execute(),
+  kysely.selectFrom('stockMove').where('itemId', '=', id).selectAll().execute(),
 ])
 ```
 
@@ -142,7 +159,11 @@ wants.
 // N+1 — one extra hop per warehouse
 const warehouses = await kysely.selectFrom('warehouse').selectAll().execute()
 for (const w of warehouses) {
-  w.bins = await kysely.selectFrom('bin').where('warehouseId','=',w.id).selectAll().execute()
+  w.bins = await kysely
+    .selectFrom('bin')
+    .where('warehouseId', '=', w.id)
+    .selectAll()
+    .execute()
 }
 // One hop — see NESTED DATA above
 ```
@@ -158,7 +179,11 @@ and what comes back tells you which branch happened.
 
 ```typescript
 // Two hops and a race
-const existing = await kysely.selectFrom('item').where('sku','=',sku).select('id').executeTakeFirst()
+const existing = await kysely
+  .selectFrom('item')
+  .where('sku', '=', sku)
+  .select('id')
+  .executeTakeFirst()
 if (existing) throw new ConflictError()
 await kysely.insertInto('item').values({ sku, name }).execute()
 
@@ -183,8 +208,20 @@ never have crossed the wire.
 
 ```typescript
 // Two hops — the ids are only ever used as a filter
-const ids = await kysely.selectFrom('bin').where('warehouseId','=',wid).select('id').execute()
-const stock = await kysely.selectFrom('stock').where('binId','in', ids.map((b) => b.id)).selectAll().execute()
+const ids = await kysely
+  .selectFrom('bin')
+  .where('warehouseId', '=', wid)
+  .select('id')
+  .execute()
+const stock = await kysely
+  .selectFrom('stock')
+  .where(
+    'binId',
+    'in',
+    ids.map((b) => b.id)
+  )
+  .selectAll()
+  .execute()
 
 // One hop
 const stock = await kysely

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

@@ -1,9 +1,11 @@
 ---
 name: pikku-list-query
 description: >-
-  Use when building a paginated or infinite-scroll list: any RPC that returns rows a user scrolls through (tables, card grids, search results). Covers the backend pikkuListFunc, the ListInput/ListOutput cursor contract, the filter tree, 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 (for example 5 settings items), where a plain pikkuFunc plus usePikkuQuery returning a full array is correct, or when the task is general React provider and hook setup (use pikku-react).
+  Paginated or infinite-scroll lists: pikkuListFunc, the ListInput/ListOutput cursor contract, the
+  filter tree, the generated usePikkuInfiniteQuery hook. TRIGGER when: asked for infinite scroll,
+  "load more", a paginated table/list/grid, or a list that could outgrow one page. DO NOT TRIGGER
+  for small fixed lists (a plain pikkuFunc plus usePikkuQuery is correct) or general React provider
+  and hook setup (use pikku-react).
 installGroups: [core, client]
 ---
 
@@ -22,7 +24,10 @@ installGroups: [core, client]
 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> {
+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' }>
@@ -57,7 +62,10 @@ export const listItems = pikkuListFunc<{ status?: string }, Item>({
   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 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
 
@@ -67,7 +75,11 @@ export const listItems = pikkuListFunc<{ status?: string }, Item>({
       query = query.where('status', '=', status)
     }
 
-    const rows = await query.orderBy('createdAt', 'desc').offset(offset).limit(limit).execute()
+    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'))
@@ -92,10 +104,11 @@ Generated automatically alongside `usePikkuQuery`/`usePikkuMutation` once `react
 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 { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+    usePikkuInfiniteQuery(
+      'listItems',
+      { limit: 20 } // never pass cursor here — the hook manages it
+    )
 
   const rows = data?.pages.flatMap((page) => page.rows) ?? []
 
@@ -142,10 +155,10 @@ Read exactly the shape you support, and refuse the rest rather than ignoring it:
 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 {
+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

package/skills/pikku-meta/SKILL.md

@@ -1,16 +1,13 @@
 ---
 name: pikku-meta
 description: >-
-  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 release` for contract hashes,
-  breaking-change detection, the semver a release should get and shipping it, 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).
+  Inspect or evolve a project you did not just write: `pikku meta`/`pikku info` for functions,
+  schemas, wires, workflows, middleware, permissions; `pikku meta apply`; `pikku versions`/`pikku
+  release` for contract hashes, breaking changes and semver; `pikku audit`/`pikku update` for
+  advisories and upgrades. TRIGGER when: asked what functions or routes exist, a function's
+  input/output shape, retagging, API versioning, breaking changes, release semver, dependency
+  vulnerabilities or upgrading Pikku. DO NOT TRIGGER when writing a new function or wiring (use the
+  wiring skill) or on 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|versions|release|audit|update]'
@@ -23,11 +20,11 @@ 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` |
+| You are…                                                    | Read                       |
+| ----------------------------------------------------------- | -------------------------- |
+| Asking what exists, or setting config on a declaration      | `references/meta.md`       |
 | Versioning a contract, or versioning and shipping a release | `references/versioning.md` |
-| Chasing a dependency advisory, or upgrading Pikku | `references/audit.md` |
+| Chasing a dependency advisory, or upgrading Pikku           | `references/audit.md`      |
 
 ## Start with `pikku meta context`
 
@@ -48,7 +45,7 @@ that asymmetry built in, so let it decide rather than eyeballing a diff.
 
 - **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.
+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
@@ -63,5 +60,5 @@ that asymmetry built in, so let it decide rather than eyeballing a diff.
   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
+  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-meta/references/audit.md

@@ -5,8 +5,6 @@
 - [Agent Operating Procedure](#agent-operating-procedure)
 - [The `pikku audit` command](#the-pikku-audit-command)
 - [The `pikku update` command](#the-pikku-update-command)
-- [Console integration (@pikku/addon-console)](#console-integration-pikkuaddon-console)
-- [Console UI (@pikku/console)](#console-ui-pikkuconsole)
 - [Report shape (SecurityAuditReport)](#report-shape-securityauditreport)
 
 ## Agent Operating Procedure
@@ -14,7 +12,7 @@
 1. The audit is a generated artifact, not live state. `pikku audit` writes the
    normalised report to `.pikku/audit.json` (config `outDir`), so it rides the
    same meta pipeline as every other codegen output — uploaded on deploy,
-   readable by the console addon and any tooling. Read it via
+   readable by any tooling. Read it via
    `metaService.readFile('audit.json')`, never by shelling out to the package
    manager from a function.
 2. One source of truth for the shape: `SecurityAuditReport` (and
@@ -81,48 +79,6 @@ the point is what the target needs. An @pikku peer the same run already brings
 forward is not reported, and an unsatisfied _optional_ peer the project never
 declared is skipped.
 
-## Console integration (@pikku/addon-console)
-
-Three RPCs, all reading/writing the same artifact via the meta service. Shared
-spawn/read helpers live in `lib/audit-exec.ts` (`readAuditReport`,
-`runPikkuAudit`, `spawnProcess`, `findBin`), alongside `lib/find-project-root.ts`
-and `lib/resolve-package-manager.ts` (`resolvePackageManager`, `installArgs`,
-`execPrefix`) — reuse them, don't re-implement. `resolvePackageManager` reads
-package.json's corepack `packageManager` field first and only falls back to
-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-auth`.
-
-- `getSecurityAudit` — reads `.pikku/audit.json`, returns the report (or `null`).
-- `runSecurityAudit` — runs `pikku audit --outdated` server-side (regenerates the
-  artifact) then returns the fresh report. Same shape as the Run Tests action.
-- `updateDependency({ package, version })` — bumps the package in `package.json`
-  (preserving the `^`/`~` range prefix), runs `bun install`, re-audits, and
-  returns the fresh report. Throws if the package is not a direct dependency.
-  NOTE: `bun install` must be scoped to a standalone project — do not run it
-  inside a yarn/bun monorepo member (it resolves the whole workspace).
-
-## Console UI (@pikku/console)
-
-- `SecurityPage` — the page: **Run audit** button (`lead`) + responsive
-  `ShellHeader` (structured `search` + `selection` for the Issues/Dependencies
-  lens; never cram raw controls into the non-collapsing `filters`/`view` escape
-  hatch). Empty state until an audit has run.
-- `SecurityAuditView` — exported presentational component. Two lenses
-  (Issues grouped by severity; Dependencies table). Each finding row carries its
-  actions **right-aligned in the row header** (`Accordion.Control` sibling, so a
-  click acts instead of toggling): "View advisory" + a per-finding
-  **remediation slot**.
-- `renderRemediation({ pkg, version, issue })` — the extension seam. OSS default
-  is `UpdateDependencyButton` (the free bump + `bun install`). Downstream
-  consoles pass their own sandbox-verified action here — replace the
-  action, keep the view.
-- Hooks: `useSecurityAudit` (read), `useRunSecurityAudit` (run),
-  `useUpdateDependency` (bump). All are `useMutation`/`useQuery` — surface
-  `mutation.error`, never hand-roll loading/error state or swallow the error.
-
 ## Report shape (SecurityAuditReport)
 
 ```ts

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

@@ -208,7 +208,7 @@ A release with neither says it holds internal changes only. Branch names are con
 while it waits to ship.
 
 Functions and wirings defined under a `scaffold/` directory or in a generated
-`*.gen.*` file are platform plumbing (auth, console, a host's injected shims)
+`*.gen.*` file are platform plumbing (auth, a host's injected shims)
 and are left out of the surface, so the same app diffs the same locally and in
 a platform's build.
 

package/skills/pikku-middleware/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: pikku-middleware
 description: >-
-  Use when adding middleware to a Pikku app: global (addGlobalMiddleware), HTTP and prefix (addHTTPMiddleware), tag-scoped (addTagMiddleware), per-wiring, session-setting middleware, and execution order and priority. Covers the pikkuMiddleware factory, where a token is resolved into a session (HTTP middleware, cron tasks), and service-to-service bearer gates.
-  TRIGGER when: user wants middleware on some or all routes, tag-scoped cross-cutting concerns, global interceptors, middleware priority or order questions, or middleware that calls setSession for a machine caller.
-  DO NOT TRIGGER when: the question is choosing or configuring an auth strategy (authBearer, authCookie, Better Auth, API keys, `pikku login`), permissions or scopes (use pikku-permissions), or deployment.
+  Middleware in a Pikku app: global (addGlobalMiddleware), HTTP/prefix (addHTTPMiddleware),
+  tag-scoped (addTagMiddleware), per-wiring, session-setting; execution order and priority; the
+  pikkuMiddleware factory; resolving a token into a session (HTTP, cron); service-to-service bearer
+  gates. TRIGGER when: middleware on some or all routes, tag-scoped concerns, global interceptors,
+  priority/order questions, or middleware calling setInitialSession for a machine caller. DO NOT TRIGGER
+  for choosing an auth strategy (authBearer, authCookie, Better Auth, API keys, `pikku login`),
+  permissions or scopes (use pikku-permissions), or deployment.
 installGroups: [core]
 ---
 
@@ -41,7 +45,8 @@ const telemetryMiddleware = pikkuMiddleware({
 The `wire` object gives you:
 
 - `wire.http` — inbound HTTP context (headers, URL, cookies)
-- `wire.setSession(session)` — set the session for this request
+- `wire.setInitialSession(session)` — establish who the caller is for this request; nothing is persisted and no cookie is re-issued. What auth middleware calls.
+- `wire.setSession(session)` / `wire.clearSession()` — sign the caller in or out: marks the session changed (so `authCookie` re-issues the cookie) and writes the session store. Same meaning as in a function body; await it.
 - `wire.getSession()` — read the current session
 - `wire.session` — the session set so far (may be undefined)
 
@@ -77,7 +82,7 @@ wireHTTP({
 Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns (e.g. telemetry) that must wrap every invocation regardless of transport.
 
 ```typescript
-import { addGlobalMiddleware } from '@pikku/core'
+import { addGlobalMiddleware } from '@pikku/core/middleware'
 import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
 
 addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })]) // wraps the full call
@@ -177,20 +182,20 @@ Within the same priority level, the collection order above is preserved. Use pri
 
 ## ⛔ MACHINE AUTH: THE TOKEN BECOMES A SESSION. ⛔
 
-**A caller that has an identity — a sandbox, a deployed stage, a pool host, a device — is authenticated ONCE, in middleware, which calls `setSession`. The function is then an ordinary `pikkuFunc` gated with `scopes`. It reads `session`. It NEVER re-derives who the caller is.**
+**A caller that has an identity — a sandbox, a deployed stage, a pool host, a device — is authenticated ONCE, in middleware, which calls `setInitialSession`. The function is then an ordinary `pikkuFunc` gated with `scopes`. It reads `session`. It NEVER re-derives who the caller is.**
 
 Either a function is sessionless (genuinely public) or it has a session. Anything in between — a token verified inside `func`, a token verified in a `permissions` check that returns `true`, an identity passed in the input schema, the same resolver memoised per request so N functions can each call it — is the anti-pattern this section exists to kill.
 
 ```typescript
 // middleware.ts — resolve the bearer ONCE, for every route
 const sandboxBearerAuth = pikkuMiddleware<SingletonServices>(
-  async ({ kysely, auth }, { http, getSession, setSession }, next) => {
+  async ({ kysely, auth }, { http, getSession, setInitialSession }, next) => {
     if (await getSession?.()) return next()
     const header = http?.request?.header?.('authorization')
     if (!header?.startsWith('Bearer ')) return next()
     const sandbox = await resolveSandboxSession(kysely, auth, header.slice(7).trim())
     if (sandbox) {
-      setSession?.({ userId: sandbox.createdByUserId ?? sandbox.sandboxInstanceId,
+      setInitialSession?.({ userId: sandbox.createdByUserId ?? sandbox.sandboxInstanceId,
         orgId: sandbox.organizationId, scopes: ['machine:sandbox'], sandbox } as UserSession)
     }
     return next()
@@ -218,17 +223,22 @@ An unresolved token leaves the session unset and the function throws `MissingSes
 
 ### It MUST be `addHTTPMiddleware`, never `addTagMiddleware`
 
-**A session set in tag middleware is invisible to the function when the call arrives over `POST /rpc/:rpcName`.** Tag middleware runs inside `runPikkuFunc`, and the RPC dispatch calls it without a `sessionService`, so `invocationWire.session` is never re-read after your `setSession` — the function sees the session the OUTER wire had, which is none. `addHTTPMiddleware('*')` runs on the `/rpc` route itself, before its handler, and that session is the one the dispatched function inherits. Tag middleware is still right for a gate that only says yes/no.
+**A session set in tag middleware is invisible to the function when the call arrives over `POST /rpc/:rpcName`.** Tag middleware runs inside `runPikkuFunc`, and the RPC dispatch calls it without a `sessionService`, so `invocationWire.session` is never re-read after your `setInitialSession` — the function sees the session the OUTER wire had, which is none. `addHTTPMiddleware('*')` runs on the `/rpc` route itself, before its handler, and that session is the one the dispatched function inherits. Tag middleware is still right for a gate that only says yes/no.
 
 ### A cron is a machine identity too — set it in the task's own middleware
 
 A scheduled task has no caller and no header, but it is still a machine principal, and without a session it cannot invoke a gated RPC or be attributed in anything it writes. Give it one the same way, in the task's own `middleware`:
 
 ```typescript
-const cronSession = pikkuMiddleware(async (_services, { scheduledTask, setSession }, next) => {
-  setSession?.({ userId: `cron:${scheduledTask?.name}`, scopes: ['machine:cron'] } as UserSession)
-  return next()
-})
+const cronSession = pikkuMiddleware(
+  async (_services, { scheduledTask, setInitialSession }, next) => {
+    setInitialSession?.({
+      userId: `cron:${scheduledTask?.name}`,
+      scopes: ['machine:cron'],
+    } as UserSession)
+    return next()
+  }
+)
 
 wireScheduler({
   name: 'tickVirtualUserSchedules',

package/skills/pikku-middleware/references/middleware-patterns.md

@@ -32,7 +32,7 @@ export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
 
 ```typescript
 const apiKeyAuth = pikkuMiddleware(
-  async ({ kysely }, { http, setSession, session }, next) => {
+  async ({ kysely }, { http, setInitialSession, session }, next) => {
     if (session) return next() // already authenticated
 
     const header = http?.request?.header?.('x-api-key')
@@ -43,7 +43,7 @@ const apiKeyAuth = pikkuMiddleware(
       .select('userId')
       .where('key', '=', header)
       .executeTakeFirst()
-    if (row) setSession?.({ userId: row.userId })
+    if (row) setInitialSession?.({ userId: row.userId })
 
     return next()
   }

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

@@ -1,14 +1,13 @@
 ---
 name: pikku-n8n-import
 description: >-
-  Use when importing an n8n workflow JSON export into a runnable Pikku workflow. Owns the whole
-  flow: run `pikku import n8n`, triage what it could not map, fill each stub, report missing
-  `@pikku/addon-*` integrations, and verify the result compiles with no surviving stubs. TRIGGER
-  when: the user says "import this n8n workflow" or "convert this n8n export to pikku", points at
-  an n8n `.json` export or a directory of them, or continues after `pikku import n8n` left throwing
-  stub functions (`STUB — generated from n8n …`, `— implement me`) or a `*.integrations.json`
-  manifest. 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).
+  Import an n8n workflow JSON export into a runnable Pikku workflow: run `pikku import n8n`, triage
+  unmapped nodes, fill each stub, report missing `@pikku/addon-*` integrations, verify it compiles
+  with no stubs left. TRIGGER when: asked to import/convert an n8n workflow, pointed at an n8n .json
+  export or directory, or continuing after the import left throwing stubs (`STUB — generated from
+  n8n …`, `— implement me`) or a `*.integrations.json` manifest. DO NOT TRIGGER for hand-written
+  addon wiring unrelated to n8n (use pikku-addon) or authoring workflows from scratch (use
+  pikku-workflow).
 installGroups: [core]
 metadata:
   version: 1.0.0

package/skills/pikku-permissions/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: pikku-permissions
 description: >-
-  Use when deciding WHO may call a function: resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes and `defineScope`, `addGlobalPermission`, the three gates, `permissionsInBody`, and where ownership belongs versus where it does not.
-  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, about to write an `if` in a function body that decides whether the caller is allowed, or hitting `MissingScopeError`.
-  DO NOT TRIGGER when: the question is how a caller proves who they are, such as sign-in, sessions, tokens, API keys or seeding a virtual user (use pikku-auth), or how to shape a paginated list (use pikku-list-query).
+  Deciding WHO may call a function: resource ownership, role gates, admin-only actions, "only their
+  own rows" rules; the `permissions` field, pikkuPermission, pikkuAuth, scopes/defineScope,
+  addGlobalPermission, permissionsInBody. TRIGGER when: writing or reviewing a function that touches
+  a user-owned row, gating on a role, building the permissions half of a contract in build PHASE 2,
+  about to write an `if` in a body deciding whether the caller is allowed, or hitting
+  MissingScopeError. DO NOT TRIGGER for how a caller proves identity: sign-in, sessions, tokens, API
+  keys, seeding a virtual user (use pikku-auth), or paginated lists (use pikku-list-query).
 installGroups: [core]
 ---
 
@@ -12,7 +16,7 @@ installGroups: [core]
 ## First: is the caller a machine with a token?
 
 Then this is NOT a permissions problem. Resolve the token in `addHTTPMiddleware('*')`
-middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with
+middleware that calls `setInitialSession`, make the function a `pikkuFunc`, and gate it with
 `scopes` (pikku-auth, `../pikku-auth/references/machine-auth.md`). A `permissions` check that verifies a
 bearer token and returns `true` is authentication wearing an authorization hat, and it
 leaves the function sessionless. The only exception is a bootstrap endpoint whose caller
@@ -54,8 +58,8 @@ user's row by passing its id. Every function that takes a row id needs BOTH: `au
 for the session, and a `permissions` entry for the ownership.
 
 Equally: do NOT write an `isSignedIn` permission that returns `!!session`. That re-checks
-authentication, which `auth: true` already did. A permission answers *may this user do
-this* — role, ownership, tier — never *is there a session*.
+authentication, which `auth: true` already did. A permission answers _may this user do
+this_ — role, ownership, tier — never _is there a session_.
 
 ## Single row vs list — where ownership actually goes
 
@@ -88,11 +92,13 @@ export const isBookOwner = pikkuPermission(
       .where('bookId', '=', bookId)
       .executeTakeFirst()
     return book?.ownerId === session?.userId
-  },
+  }
 )
 
 // Session-only: no input needed. Use for role and flag gates.
-export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
 ```
 
 ## OR and AND

package/skills/pikku-react/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: pikku-react
 description: >-
-  Use when a React frontend talks to a Pikku backend — PikkuProvider and createPikku at the app
-  root, the generated React Query hooks (usePikkuQuery, usePikkuMutation, usePikkuInfiniteQuery),
-  direct usePikkuRPC / usePikkuFetch calls, realtime subscriptions, and agent and workflow hooks. TRIGGER when: writing a React component that fetches or mutates backend
-  data, wiring PikkuProvider, paginating, running or tracking a workflow from the client. DO NOT TRIGGER when: working on the
-  backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), rendering fetched values such as
-  dates (use pikku-tailwind), or writing user-facing copy (use pikku-i18n).
+  React frontend talking to a Pikku backend: PikkuProvider/createPikku, generated React Query hooks
+  (usePikkuQuery, usePikkuMutation, usePikkuInfiniteQuery), usePikkuRPC/usePikkuFetch, realtime
+  subscriptions, agent and workflow hooks. TRIGGER when: writing a React component that fetches or
+  mutates backend data, wiring PikkuProvider, paginating, or running/tracking a workflow from the
+  client. DO NOT TRIGGER for backend work (use pikku-wiring), defining the workflow (use
+  pikku-workflow), rendering fetched values such as dates (use pikku-tailwind) or user-facing copy
+  (use pikku-i18n).
 installGroups: [client]
 ---
 

package/skills/pikku-realtime/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: pikku-realtime
 description: >-
-  Use when making a view live in a Pikku app — a board, shared list, dashboard, ticker, bidding
-  room, live count — or when adding two-way chat or presence. Covers the default event-hub SSE path
-  (`eventHub.publish` on the backend, `PikkuRealtime.subscribeToTopic` on the client) and the
-  two-way WebSocket channel. TRIGGER when: the user wants live updates, realtime, "update without
-  refresh", a live board/feed/ticker/room, presence or chat, or data that more than one signed-in
-  user can change should reflect to others. DO NOT TRIGGER when: a one-shot query/refetch is enough
-  (data only one user changes, or a manual refresh is acceptable), for background jobs (use
-  pikku-workflow, or pikku-wiring's queue and scheduler references), or for the full wiring
-  reference of channels, SSE routes and the `/events` scaffold (use pikku-wiring).
+  Making a view live in a Pikku app (board, shared list, dashboard, ticker, bidding room, live
+  count) or adding two-way chat/presence: the default event-hub SSE path (`eventHub.publish`,
+  `PikkuRealtime.subscribeToTopic`) and the WebSocket channel. TRIGGER when: asked for live updates,
+  realtime, "update without refresh", presence or chat, or data several signed-in users can change
+  should reflect to others. DO NOT TRIGGER when a one-shot refetch is enough, for background jobs
+  (use pikku-workflow, or pikku-wiring's queue/scheduler references), or for the full
+  channel/SSE/`/events` wiring reference (use pikku-wiring).
 installGroups: [core, client]
 ---
 
@@ -115,8 +113,15 @@ import { pikkuChannelFunc, wireChannel } from '#pikku/channel'
 
 export const onMessage = pikkuChannelFunc<{ text: string }>({
   func: async ({ eventHub }, input, { channel, session }) => {
-    const message = { id: crypto.randomUUID(), text: input.text, userId: session!.userId }
-    await eventHub.publish('room', channel.channelId, { topic: 'room', data: message })
+    const message = {
+      id: crypto.randomUUID(),
+      text: input.text,
+      userId: session!.userId,
+    }
+    await eventHub.publish('room', channel.channelId, {
+      topic: 'room',
+      data: message,
+    })
     return message
   },
 })

package/skills/pikku-report/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: pikku-report
 description: >-
-  Use when pikku itself cost you time — wrong generated types, a check that passes when it should
-  not, output that is quietly wrong, a skill that misled you — or when the user asks you to report
-  a framework bug or file a finding. Owns `pikku cloud report` (a finding is about pikku, not the
-  app), the product-vs-harness kinds, the workaround-first ladder, and asking the user at hand-over
-  whether to send what was filed. TRIGGER when: the framework fought you, codegen produced
-  something broken, a skill told you to run something that does not exist, the user says "report
-  this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug
-  is in the app you are building (fix it there), you are debugging a deployed stage,
-  or you are tempted to patch pikku's source (never do that from an app).
+  Reporting Pikku itself when it cost you time (wrong generated types, a check that passes when it
+  should not, quietly wrong output, a misleading skill) or when asked to file a framework bug:
+  `pikku cloud report`, product-vs-harness kinds, the workaround-first ladder, asking the user at
+  hand-over whether to send findings. TRIGGER when: the framework fought you, codegen is broken, a
+  skill told you to run something that does not exist, the user says "report this to pikku" / "file
+  a finding", or you are handing over a build. DO NOT TRIGGER for bugs in the app you are building,
+  debugging a deployed stage, or patching pikku's source (never from an app).
 installGroups: [core]
 ---
 
@@ -62,7 +60,7 @@ baseline noise that was already failing before you started.
 - `--kind harness` — a skill misled you: it told you to run something that does
   not exist, described a flag that is spelled differently, or contradicted what
   the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
-  section>"`. This is the most useful kind to file, because it is fixable
+section>"`. This is the most useful kind to file, because it is fixable
   immediately — so file it even when the cost was small.
 
 ## The command