@pikku/skills 0.12.58 → 0.12.60

package/skills/pikku-knowledge/SKILL.md

@@ -1,16 +1,14 @@
 ---
 name: pikku-knowledge
 description: >-
-  Use when writing, reading, reorganising or validating a project's knowledge/ directory — the
-  notes that say what the app is, in the language its users use. Covers the Open Knowledge Format
-  note (path-as-identity markdown, only `type` required), the sections (entities, decisions,
-  questions, wishlist), how notes become changes (`pikku knowledge
-  gaps`), the `resource:` URI scheme tying a note to its code, and `pikku knowledge validate|index|gaps`. TRIGGER when: user asks to write down a decision,
-  requirement, entity or open question; asks what the app does or is; asks about knowledge/
-  notes or a diagram, callout or decision block; or hands over a product brief to record. DO NOT TRIGGER when: user asks what functions, routes, tables or permissions exist
-  (`pikku meta` / `pikku info`, never a note), wants a scenario test (use pikku-scenario), writes a
-  changeset plan (use pikku-architect), or extracts a `.knowledge/` blueprint from a legacy repo
-  (use pikku-software-archaeology).
+  Write, read, reorganise or validate a project's knowledge/ directory: Open Knowledge Format notes
+  (path-as-identity markdown, only `type` required), sections (entities, decisions, questions,
+  wishlist), notes becoming changes (`pikku knowledge gaps`), the `resource:` URI scheme, `pikku
+  knowledge validate|index|gaps`. TRIGGER when: asked to record a decision, requirement, entity or
+  open question, what the app does or is, a knowledge note/diagram/callout, or a product brief. DO
+  NOT TRIGGER for what functions/routes/tables exist (`pikku meta`/`pikku info`), scenarios (use
+  pikku-scenario), changeset plans (use pikku-architect) or legacy blueprint extraction (use
+  pikku-software-archaeology).
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -21,7 +19,6 @@ agent:
     verify:
       - id: knowledge-consistent
         command: pikku knowledge validate
-
 ---
 
 # Pikku Knowledge
@@ -72,14 +69,14 @@ worse than one of them losing access mid-session.
 
 Frontmatter fields:
 
-| Field         | Meaning                                                                                                                 |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Field         | Meaning                                                                                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `type`        | **The only required field.** One of `entity`, `decision`, `note`, `overview`. Lowercase — every gate compares it literally, so a near-miss is a note no command can see. |
-| `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
-| `description` | One line, used as the note's subtitle in a section index.                                                               |
-| `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
-| `tags`        | Flow list (`[a, b]`) or a `- item` block; both are read.                                                                |
-| `timestamp`   | When it was written, if it matters.                                                                                     |
+| `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                                                                  |
+| `description` | One line, used as the note's subtitle in a section index.                                                                                                                |
+| `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                                                                             |
+| `tags`        | Flow list (`[a, b]`) or a `- item` block; both are read.                                                                                                                 |
+| `timestamp`   | When it was written, if it matters.                                                                                                                                      |
 
 `index.md` and `log.md` are **reserved**: an `index.md` maps a directory, a `log.md` is an append-only record. Neither is ever listed as a note by an index.
 
@@ -109,13 +106,13 @@ knowledge/
 
 Each section answers exactly one question, which is what lets a reader find a note without an index of indexes:
 
-| Section               | The question it answers                                            |
-| --------------------- | ------------------------------------------------------------------ |
-| `entities/`           | What is this thing, in the words users use for it?                 |
-| `decisions/`          | What was chosen, and what does that rule out?                      |
-| `decisions/security/` | Who may do what?                                                   |
-| `questions/`          | What has been asked and not yet answered?                          |
-| `wishlist/`           | What does somebody want that nobody has asked to be built?         |
+| Section               | The question it answers                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `entities/`           | What is this thing, in the words users use for it?         |
+| `decisions/`          | What was chosen, and what does that rule out?              |
+| `decisions/security/` | Who may do what?                                           |
+| `questions/`          | What has been asked and not yet answered?                  |
+| `wishlist/`           | What does somebody want that nobody has asked to be built? |
 
 **Create a section the turn you have a note for it** — never a scaffold of empty directories, and never a section without its own `index.md`. A section index says in one line what belongs in it; that sentence is the reason the file exists, so `pikku knowledge index` writes only the note listing and leaves your prose alone.
 
@@ -193,19 +190,19 @@ It is a **summary, not the note** — the argument continues in prose underneath
 
 **Every kind resolves.** That is the whole design: a kind that cannot be checked lets notes accumulate references nothing validates, and the graph rots into fiction exactly where it looks most authoritative.
 
-| Kind        | An id is                                           | Where it resolves                                                                          |
-| ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `func:`     | a function id                                      | generated function meta                                                                    |
-| `workflow:` | a workflow name                                    | generated workflow meta                                                                    |
-| `schema:`   | a schema name                                      | generated schemas                                                                          |
-| `http:`     | a route, `method:route`, or the function behind it | generated http wirings                                                                     |
-| `queue:`    | a queue name                                       | generated queue wirings                                                                    |
-| `cron:`     | a scheduled task name                              | generated scheduler wirings                                                                |
-| `channel:`  | a channel name                                     | generated channel meta                                                                     |
-| `table:`    | a table name                                       | the generated db schema                                                                    |
-| `addon:`    | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                                  |
-| `scope:`    | a scope name                                       | the `scopes:` a function gates itself with, plus the scopes a `defineSystemRole()` confers |
-| `virtualUser:`  | a virtual user name                                     | `defineVirtualUsers()`                                                                         |
+| Kind           | An id is                                           | Where it resolves                                                                          |
+| -------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `func:`        | a function id                                      | generated function meta                                                                    |
+| `workflow:`    | a workflow name                                    | generated workflow meta                                                                    |
+| `schema:`      | a schema name                                      | generated schemas                                                                          |
+| `http:`        | a route, `method:route`, or the function behind it | generated http wirings                                                                     |
+| `queue:`       | a queue name                                       | generated queue wirings                                                                    |
+| `cron:`        | a scheduled task name                              | generated scheduler wirings                                                                |
+| `channel:`     | a channel name                                     | generated channel meta                                                                     |
+| `table:`       | a table name                                       | the generated db schema                                                                    |
+| `addon:`       | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                                  |
+| `scope:`       | a scope name                                       | the `scopes:` a function gates itself with, plus the scopes a `defineSystemRole()` confers |
+| `virtualUser:` | a virtual user name                                | `defineVirtualUsers()`                                                                     |
 
 Ids are case-sensitive: `createEntry` is not `createentry`.
 
@@ -217,14 +214,14 @@ There is no kind for a service, a middleware or a component. Say it in prose ins
 
 These are all things that exist somewhere better, so a note is always the copy that drifts:
 
-| Do not write                        | Because it lives in                                        |
-| ----------------------------------- | ---------------------------------------------------------- |
-| a `virtual users/` section               | `defineVirtualUsers()` in the project's own code               |
+| Do not write                        | Because it lives in                                          |
+| ----------------------------------- | ------------------------------------------------------------ |
+| a `virtual users/` section          | `defineVirtualUsers()` in the project's own code             |
 | a `scenarios/` section              | the `scenarios` of the plan for the changeset that builds it |
-| a `permissions/` section            | a decision note under `decisions/security/`                |
-| a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema        |
-| a changelog                         | `CHANGELOG.md` at the repo root                            |
-| **secrets or credentials**          | a secrets service. Never here — `knowledge/` is committed. |
+| a `permissions/` section            | a decision note under `decisions/security/`                  |
+| a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema          |
+| a changelog                         | `CHANGELOG.md` at the repo root                              |
+| **secrets or credentials**          | a secrets service. Never here — `knowledge/` is committed.   |
 
 And two shapes that look like a knowledge base but are not:
 

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