@pikku/skills 0.12.52 → 0.12.54

package/skills/pikku-fabric/references/deploy.md

@@ -0,0 +1,179 @@
+# Deploying a Fabric app
+
+## Contents
+
+- Deploy commands and organization targeting
+- Rebuilding a disposable stage: `--reset`
+- Exit codes, the approval gate, CI splitting, GitHub adoption and the upstream guard (inside Deploy commands)
+- The first user on a deployed stage
+- Opening a private stage
+
+## Deploy commands and organization targeting
+
+```bash
+pikku fabric login              # opens a browser; needs a human, wait for it
+pikku fabric init https://github.com/<owner>/<repo>
+pikku fabric validate           # must pass clean
+pikku fabric deploy apply --production -y
+```
+
+`init` and `link` import into whichever organization your session is in. When
+you belong to several — a personal one and a company one, say — name the target
+with `--organization`, taking a slug, a display name or an id:
+
+```bash
+pikku fabric link --organization vlandor
+```
+
+You have to be a member of the organization you name, and its GitHub account
+has to be connected already: importing a `github.com/<owner>/<repo>` repo needs
+the Fabric GitHub App installed on `<owner>` _and_ linked to that organization,
+or the import refuses by name.
+
+The branch is positional and defaults to the checked-out one, and `-y` is the
+short form of `--auto-approve`, so a one-shot deploy is:
+
+```bash
+pikku fabric deploy apply -y            # the branch you are standing on
+pikku fabric deploy apply my-branch -y  # a named one
+```
+
+`-y` answers the prompts and nothing more. It does **not** approve migrations
+that drop or rewrite data — that stays `--allow-destructive`, typed out on
+purpose.
+
+## Rebuilding a disposable stage: `--reset`
+
+A non-production stage whose migration history or schema has drifted (an app's
+`develop` branch) can be wiped and rebuilt in one deploy:
+
+```bash
+pikku fabric deploy apply develop --reset      # asks first, naming app + stage
+pikku fabric deploy apply develop --reset -y   # prints the warning, skips the prompt
+```
+
+It is the deployed counterpart of `pikku db reset`: **all data on that stage is
+deleted**, every migration is re-applied and `db/<engine>-dev-seed.sql` is
+loaded. It is refused for `--production`, for `main`, and with `--deployment-id`
+(it only applies to a deploy it creates). It needs a fabric server that reports
+the reset back on the deployment; against one that does not, the command fails
+naming the deployment it created without a reset, and wipes nothing. `-y` does
+not imply `--allow-destructive`.
+
+Inferring the branch is safe because the git safety check refuses any branch
+without an upstream or out of sync with it, so it cannot ship an unpushed
+commit; the branch it picked is printed before the build starts. A detached
+HEAD is refused by name rather than travelling on as a branch called `HEAD`.
+
+There is no `deploy plan` subcommand — `apply` runs the same auth, git-safety
+and ref resolution itself, and fabric produces the real plan server-side.
+
+`apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
+it refuses rather than hangs. `--auto-approve` (`-y`) supplies that confirmation;
+drop it only when a human is at a real terminal.
+
+`apply` waits for a terminal state and exits non-zero unless the deployment went
+live. `--detach` opts out — it queues the deploy, prints the deployment id and
+returns 0, which tells you nothing about whether it worked:
+
+| exit | meaning                                                                 |
+| ---- | ----------------------------------------------------------------------- |
+| 0    | live (or queued, under `--detach`)                                      |
+| 1    | the command could not run — not logged in, unsafe git state, bad flags  |
+| 2    | the deployment failed, errored, timed out server-side, or was cancelled |
+| 3    | the deployment is blocked and nothing the CLI can do will unblock it    |
+| 4    | the wait hit `--timeout` with the deployment still in flight            |
+
+On a failure or timeout, `apply` prints the tail of the builder's own log (and
+carries `buildLog` / `imageBuildLog` on the `--json` result). Read it before
+touching code: `fabric logs` serves the running stage, not the build. When the
+builder recorded nothing, the CLI says so — that is usually fabric-side, so run
+`pikku fabric smoke` before assuming the project is broken.
+
+Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
+Why it parked is the whole story, and it is `statusReason`, not `status`:
+
+- `awaiting_approval` — the plan is fine, a human has to publish it.
+  `-y` does that; without it you get exit 3 and the command to run.
+  One exception: if fabric marked any pending migration **destructive** — a
+  drop, a truncate, a rewrite — `-y` alone declines and exits 3,
+  because a standing yes was given before anyone knew the plan dropped a table.
+  The CLI lists the migrations and fabric's reasons; `--allow-destructive`
+  accepts them for that deploy, and `-y` implies it.
+- `needs_config` — a declared secret or variable has no value covering the
+  stage. The CLI names them. `-y` will **not** force this through;
+  set the values and re-attach — `pikku fabric secrets set <name>` for a
+  declared secret, `pikku fabric variables set <name> --value <v>` for a declared
+  variable. They are separate stores: a secret is sealed to the stage and cannot
+  be read back, a variable is stored plainly and can (`variables get`). `set`
+  reads the value as JSON when it parses, so `--value true` is the boolean on a
+  stage exactly as it is from `.env`, and `--value '"true"'` is the string.
+- `needs_attention` — the plan is red. Nothing to approve.
+
+The wait defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
+it prints the deployment id and the re-attach command rather than lying about
+the outcome.
+
+Splitting kick-off from waiting across two CI jobs is the reason
+`--deployment-id` exists, and what `--detach` is for — the first job here has to
+return the id and exit rather than wait:
+
+```bash
+id=$(pikku fabric deploy apply --production -y --detach --json | jq -r 'select(.event=="result").deploymentId')
+# …later, in another job…
+pikku fabric deploy apply --deployment-id "$id" -y
+```
+
+`--deployment-id` skips the git safety check entirely (the deployment already
+pins a sha, and the checkout is allowed to have moved on) and refuses to be
+combined with a branch or `--production`, which would let the two disagree.
+
+Under `--json`, the wait emits one NDJSON event per line — `created`/`attached`,
+`status` on each transition, `blocked`, `approved` — and the last line is the
+terminal result object, tagged `"event": "result"`.
+
+`init` adopts a **GitHub** repo, and adoption goes through the Pikku Fabric
+GitHub App — the app has to be installed on the account or org that owns the
+repo, and if it is installed with "selected repositories" this one must be in
+the selection. There is no CLI flag that works around a missing installation:
+`init` returns "Connect the GitHub account '<owner>'". Send the user to install
+it, or create the project in the console instead (which provisions a Fabric-hosted
+git repo you push to) and clone it — the remote links the checkout, or put
+the id in `fabric.projectId` in `pikku.config.json`.
+
+Deploy refuses to run unless the target branch equals its upstream — the guard
+compares `main` against `main@{upstream}`. So the remote you pushed to must be
+the one the branch tracks; a stale `origin` left over from scaffolding blocks
+the deploy with "local HEAD … ≠ remote …" even though your code is pushed.
+`git branch --set-upstream-to=<remote>/main main` before deploying.
+
+## The first user on a deployed stage
+
+When sign-up is off, the first account has to come from outside the app.
+`pikku fabric user add <email>` is the CLI form of the console's Add user:
+
+```bash
+pikku fabric user add ada@example.com --name Ada          # prompts; blank generates one
+pikku fabric user add ada@example.com --password '<pw>' -b staging
+```
+
+It mints a short-lived operator token for the stage and calls the stage's own
+`admin:createUser`, so the stage must wire `@pikku/addon-admin` as `admin` —
+a 404 is refused by name and nothing is created. A generated password is printed
+once; one you passed is never echoed. With no TTY, pass `--password` or pipe it.
+
+## Opening a private stage
+
+A non-production stage is private: without a link it answers "This preview is
+private". `pikku fabric stage link` prints the link that opens it:
+
+```bash
+pikku fabric stage link access -b develop --route /login   # use the stage
+pikku fabric stage link changes -b develop                 # use it with the changes panel
+pikku fabric stage visibility public -b develop            # or: private
+```
+
+A stage has one live link of each kind, so asking again returns the same one
+until it expires. A `changes` link turns the panel on first; if that needs a
+deploy, the command says so. `visibility public` opens the stage to anyone with
+its URL — hand out an `access` link instead when that is all you need.

package/skills/pikku-guide/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: pikku-guide
 description: >-
-  Use when writing, rewriting or regenerating a Pikku project's user guide — the end-user
-  documentation built from the scenario suite with `pikku scenario guide`. Pages are hand-written
-  markdown, one section per task, each followed by a `<!-- pikku:guide feature=… scenario=… -->`
-  marker that pulls in the screenshot and recording that scenario filed. Covers planning pages
-  from the suite, writing task prose in the app's language, per-section markers, the capture step,
-  seed data that appears on camera, `.guide.lock` staleness, `document: false`, and the traps that
-  make a guide come out empty, refused, or as a wall of videos. TRIGGER when: user asks for a user
-  guide, help pages, docs with screenshots, "document the app", or complains that the /docs pages
-  are bad, thin, or all videos. DO NOT TRIGGER when: user asks about API reference docs, README
-  files, or writing the scenarios themselves (use pikku-scenario).
+  Use when writing, rewriting or regenerating a Pikku project's end-user guide, built from the
+  scenario suite with `pikku scenario guide`. Pages are hand-written markdown, one section per
+  task, each followed by a `pikku:guide` HTML-comment marker (feature and scenario attributes) that
+  pulls in the screenshot and recording that scenario filed. Covers planning pages from the suite,
+  writing task prose in the app's language, per-section markers, the capture step, seed data that
+  appears on camera, `.guide.lock` staleness, `document: false`, and the traps that make a guide
+  come out empty, refused, or as a wall of videos. TRIGGER when: user asks for a user guide, help
+  pages, docs with screenshots, "document the app", or complains that the /docs pages are bad,
+  thin, or all videos. DO NOT TRIGGER when: user asks about API reference docs, README files, the
+  Pikku framework's own documentation site, or writing the scenarios themselves (use pikku-scenario).
 installGroups: [core]
 ---
 

package/skills/pikku-i18n/SKILL.md

@@ -2,9 +2,9 @@
 name: pikku-i18n
 description: >-
   Use when writing user-facing text in a Pikku frontend, or making one speak another language.
-  Covers Paraglide JS message functions compiled from messages/<locale>.json, adding a second
-  language, generated enum-label maps with @pikku/paraglide, and right-to-left support for Arabic,
-  Hebrew, Farsi and Urdu. TRIGGER when: scaffolding or editing a frontend and writing display
+  Covers Paraglide JS message functions compiled from per-locale messages JSON files, adding a second
+  language, generated enum-label maps with @pikku/paraglide, and right-to-left support (document direction, flow-relative
+  styles) for Arabic, Hebrew, Farsi and Urdu. TRIGGER when: scaffolding or editing a frontend and writing display
   text, asked to make copy translatable, adding a language, labelling an enum/status/role value,
   or asked to support RTL / mirror the layout. DO NOT TRIGGER for backend functions, error
   messages thrown from functions, or log output — none of those are display strings.
@@ -46,10 +46,10 @@ the app is in. Set `defaultLocale` instead.
 
 ## Direction is one setting, not per-component work
 
-Set `dir` once at the document root from the active locale and the browser (and
-Mantine) mirror everything — provided every custom style is flow-relative
-(`margin-inline-start`, `text-align: start`, Mantine `ms`/`me`) rather than
-physical (`margin-left`, `text-align: left`, `ml`/`me`'s physical twins). Write
+Set `dir` once at the document root from the active locale and the browser
+mirror everything — provided every custom style is flow-relative
+(`margin-inline-start`, `text-align: start`, Tailwind `ms-*`/`me-*`) rather than
+physical (`margin-left`, `text-align: left`, `ml-*`/`mr-*`). Write
 logical properties from the start even in an English-only app; that discipline
 is what makes an RTL language just another locale file.
 

package/skills/pikku-i18n/references/enum-labels.md

@@ -1,5 +1,14 @@
 # Pikku Paraglide enum labels
 
+## Contents
+
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [The rules that don't change](#the-rules-that-dont-change)
+- [The generated module](#the-generated-module)
+- [Reconciliation against the database](#reconciliation-against-the-database)
+- [Wiring](#wiring)
+- [What NOT to do](#what-not-to-do)
+
 ## Agent Operating Procedure
 
 Use this as an execution checklist, not reference material.

package/skills/pikku-i18n/references/messages.md

@@ -1,5 +1,18 @@
 # Pikku i18n (Paraglide JS)
 
+## Contents
+
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [The product's language is not the code's language](#the-products-language-is-not-the-codes-language)
+- [The moving parts (starter-template layout)](#the-moving-parts-starter-template-layout)
+- [Using messages in components](#using-messages-in-components)
+- [Keys only known at runtime (enum labels, status maps)](#keys-only-known-at-runtime-enum-labels-status-maps)
+- [Type safety — and why deploys block on i18n](#type-safety--and-why-deploys-block-on-i18n)
+- [Compile step](#compile-step)
+- [Adding a second language](#adding-a-second-language)
+- [i18n debug mode (find inlined strings)](#i18n-debug-mode-find-inlined-strings)
+- [What NOT to do](#what-not-to-do)
+
 ## Agent Operating Procedure
 
 Use this skill as an execution checklist, not reference material.
@@ -160,7 +173,7 @@ helper, stop — that helper IS the bug.
 
 A message IS a function: a typo'd or deleted key (`m.auth__login__titel()`) is a missing export — a **TypeScript error**, not a silent runtime fallback string. Params are typed too. The deploy pipeline compiles Paraglide then runs each frontend's `tsc` (`"tsc": "tsc --noEmit"` script — keep it in every frontend's `package.json`) **before** building; a type error aborts the deploy. `vite build` does not type-check on its own, so this gate is the only thing standing between a broken message and production.
 
-The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/mantine` `I18nNode` prop typing catches those: a raw string literal fails to compile on a gated prop, because `I18nString` is a branded type a bare `string` can't satisfy. Between the two, `tsc` is the whole safety net — there is no runtime fallback to inspect, by design.
+The gate catches _invalid_ messages but not _inlined_ strings. The starter template's `I18nNode` prop typing catches those: a raw string literal fails to compile on a gated prop, because `I18nString` is a branded type a bare `string` can't satisfy. Between the two, `tsc` is the whole safety net — there is no runtime fallback to inspect, by design.
 
 ## Compile step
 
@@ -181,7 +194,7 @@ The gate catches _invalid_ messages but not _inlined_ strings. The `@pikku/manti
 
 ## i18n debug mode (find inlined strings)
 
-`tsc` catches invalid messages, and the `@pikku/mantine` gate catches raw strings on gated props — but neither sees a hardcoded string in plain JSX, an `aria-label`, `alt`, `document.title`, or anything passed to a non-Mantine component. Debug mode covers that gap: render every message as block glyphs (`█`), and whatever is still readable never went through a message.
+`tsc` catches invalid messages, and the template's `I18nNode` gate catches raw strings on gated props — but neither sees a hardcoded string in plain JSX, an `aria-label`, `alt`, `document.title`, or anything passed to a component that does not gate its text. Debug mode covers that gap: render every message as block glyphs (`█`), and whatever is still readable never went through a message.
 
 **Build it as a generated locale, never as a runtime wrapper.** Masked text is text, and rendering different text per locale is what Paraglide already does:
 
@@ -207,7 +220,7 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 - Don't let a non-English UI reach the identifiers. Functions, components, types, files, tables and columns are English in every project; the product's language lives in `messages/*.json` and nowhere else.
 - Don't translate message **keys**. `auth__login__title` stays English in `de.json`; only the value changes.
 - Don't edit or commit anything under `src/paraglide/` — it's regenerated; change `messages/*.json` instead.
-- **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the `@pikku/mantine` `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
+- **Don't wrap `m`.** No re-export module, no branding layer, no resolver. Components import `m` from `../paraglide/messages.js` and call it. `@pikku/react`'s `I18nString` is declared as `string & { readonly __brand: 'LocalizedString' }` — deliberately identical to Paraglide's own `LocalizedString` — so `m.some__key()` satisfies the template's `I18nNode` gate natively. A wrapper adds nothing and costs per-message tree-shaking.
 
   `packages/console` is the one place in this repo that still wraps it, in `src/i18n/messages.ts`, to keep the debug mask (`█`) it carried over from i18next. That wrapper is a leftover, not a pattern — the generated-locale approach above is how a new app gets the same masking without touching every export. Don't copy it.
 

package/skills/pikku-i18n/references/rtl.md

@@ -1,5 +1,16 @@
 # Pikku RTL (Arabic + English)
 
+## Contents
+
+- [The one idea](#the-one-idea)
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [Flow-relative, not physical — the rules that make it mirror](#flow-relative-not-physical--the-rules-that-make-it-mirror)
+- [Applying direction at the root](#applying-direction-at-the-root)
+- [Directional icons — the manual bit](#directional-icons--the-manual-bit)
+- [Arabic typography niceties](#arabic-typography-niceties)
+- [Adding Arabic to an existing app — checklist](#adding-arabic-to-an-existing-app--checklist)
+- [What NOT to do](#what-not-to-do)
+
 This reference sits **on top of** `references/messages.md`. That one compiles a locale's
 messages into typed `m.*()` functions; this one adds the second axis: a locale
 also has a **direction**. Arabic is not special-cased — it is just another
@@ -9,7 +20,7 @@ being told it is `rtl`.
 ## The one idea
 
 Set `dir` **once at the document root** from the active locale, then let the
-browser and Mantine mirror everything — _provided_ every custom style is written
+browser mirror everything — _provided_ every custom style is written
 **flow-relative** (start/end), never **physical** (left/right). Get those two
 things right and Arabic, Hebrew, Farsi and Urdu all work with zero per-component
 _layout_ code — directional icons still need one manual step, covered below.
@@ -51,14 +62,14 @@ Use the **inline-axis logical** property; never the physical one:
 | `border-top-left-radius`     | `border-start-start-radius`                  |
 | `float: left/right`          | `float: inline-start / inline-end`           |
 
-In **Mantine**, use the logical style props — they emit the logical CSS above:
+In **Tailwind**, use the logical utilities — they emit the logical CSS above:
 
 | Don't       | Do          |
 | ----------- | ----------- |
-| `ml` / `mr` | `ms` / `me` |
-| `pl` / `pr` | `ps` / `pe` |
+| `ml-*` / `mr-*` | `ms-*` / `me-*` |
+| `pl-*` / `pr-*` | `ps-*` / `pe-*` |
 
-Mantine's own components already use logical properties internally, so once the
+shadcn's own components already use logical properties, so once the
 direction is set they mirror automatically — you only have to be disciplined in
 **your** styles.
 
@@ -70,40 +81,9 @@ logical order; let `dir` handle the visual order.
 
 ## Applying direction at the root
 
-### Mantine app (e.g. environment-template)
-
-Mantine ships first-class RTL: wrap the tree in `DirectionProvider` and set the
-matching `dir` on `<html>`.
-
-```tsx
-import { DirectionProvider, MantineProvider } from '@mantine/core'
-import { detectLocale, localeDir } from './i18n/config'
-
-const locale =
-  typeof window !== 'undefined' ? detectLocale(window.location.pathname) : 'en'
-const dir = localeDir(locale)
-
-if (typeof document !== 'undefined') {
-  document.documentElement.lang = locale
-  document.documentElement.dir = dir // Mantine + browser read this
-}
-
-root.render(
-  <DirectionProvider initialDirection={dir}>
-    <MantineProvider theme={theme} defaultColorScheme="dark">
-      {/* …app… */}
-    </MantineProvider>
-  </DirectionProvider>
-)
-```
-
-To flip direction live (a language switcher) call
-`document.documentElement.setAttribute('dir', localeDir(next))` and Mantine's
-`useDirection().setDirection(dir)`; both read the same value.
-
 ### Plain Vite SPA (kanban, test-harness vite-spa)
 
-No Mantine — just put `dir`/`lang` on `<html>` at bootstrap, after the locale is
+Put `dir`/`lang` on `<html>` at bootstrap, after the locale is
 detected (the same `detectLocale` the i18n config uses):
 
 ```ts
@@ -211,7 +191,7 @@ left` with the flow-relative equivalent; revert any manual `row-reverse`.
 - Don't fake RTL with `flex-direction: row-reverse`, reversed DOM order, or
   per-locale `if (rtl)` layout branches. Set `dir` once; let layout follow.
 - Don't set `dir` on individual components — it belongs on `<html>` so the whole
-  document (and Mantine) agrees.
+  document agrees.
 - Don't translate Arabic copy outside the message system; an RTL language is a
   normal locale, governed by `references/messages.md`. There is no `t()` and no i18next in a
   Pikku frontend — the string comes from `m.some__key()`.

package/skills/pikku-knowledge/SKILL.md

@@ -3,15 +3,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, YAML frontmatter, only `type` required), the app-project
-  profile's sections (entities, decisions, questions, wishlist) and what each answers, how notes
-  become changes (`pikku knowledge gaps`), the changeset plan, the `resource:` URI scheme tying a
-  note to its code, what is NOT a knowledge base, 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, an index.md, 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 (that is `pikku meta` / `pikku info`, never a note), or to write a
-  scenario test (use pikku-scenario).
+  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).
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -31,7 +30,7 @@ The knowledge base is `knowledge/` at the repo root: markdown notes about **what
 
 Not to be confused with `.knowledge/` — the dot-prefixed JSON blueprint that `pikku-software-archaeology` extracts from a legacy repo. Different directory, different format, different purpose.
 
-## Agent Operating Procedure
+## Operating procedure
 
 1. **Read `knowledge/index.md` first**, then the section index for whatever you are about to touch. It is the cheapest way to learn what the app already claims about itself.
 2. Before writing a note, ask whether `pikku meta` already answers it. If it does, do not write the note — see _What never goes in a note_.

package/skills/pikku-kysely/SKILL.md

@@ -1,32 +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, aggregates + groupBy/having, returning, sql template, expression builder, $if,
-  transactions, jsonArrayFrom relation helpers), 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 services, secret services, AI storage, deployment services). TRIGGER when: writing any
-  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, a function body
-  awaits more than one query, or the user asks about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
-  services (use pikku-service-backends).
+  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).
 installGroups: [core]
 ---
 
 # Pikku Kysely (SQL Database Services)
 
-## 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 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.
-
 ## Writing Queries — the Kysely query builder
 
 In a Pikku function body the injected `kysely` IS the `Kysely<DB>` instance — query it directly. Every connection factory below wires the **CamelCasePlugin** by default, so you write **camelCase everywhere in TS** (columns, aliases) and raw **snake_case ONLY inside a ` sql` `` literal**. If a project opted out (`createNodeSqliteKysely({ camelCase: false })`), that inverts — check how the instance was built before assuming. Kysely is a query builder, NOT an ORM — there are no relations; shape nested data with the JSON helpers below. Never hand-roll SQL strings; never annotate the return type (in Pikku the output zod schema IS the type).

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

@@ -1,9 +1,9 @@
 ---
 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.
+  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 (e.g. a settings page with 5 items) — a plain pikkuFunc + usePikkuQuery returning a full array is simpler and correct there.
+  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).
 installGroups: [core, client]
 ---
 

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

@@ -1,5 +1,14 @@
 # Pikku Dependency Audit
 
+## Contents
+
+- [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
 
 1. The audit is a generated artifact, not live state. `pikku audit` writes the

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

@@ -1,5 +1,11 @@
 # Pikku Project Metadata
 
+## Contents
+
+- [Reading](#reading)
+- [Changing](#changing)
+- [Human-readable tables (`pikku info`)](#human-readable-tables-pikku-info)
+
 `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.

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

@@ -1,5 +1,15 @@
 # Pikku Function Versioning
 
+## Contents
+
+- [Before You Start](#before-you-start)
+- [Function Versioning](#function-versioning)
+- [Version Manifest (`versions.pikku.json`)](#version-manifest-versionspikkujson)
+- [CLI Commands](#cli-commands)
+- [The `pikku release` command](#the-pikku-release-command)
+- [CI Integration](#ci-integration)
+- [Complete Example](#complete-example)
+
 ## Before You Start
 
 ```bash

package/skills/pikku-middleware/SKILL.md

@@ -1,24 +1,15 @@
 ---
 name: pikku-middleware
 description: >-
-  Use when adding any middleware to a Pikku app — global HTTP middleware, tag-scoped middleware
-  (including service-to-service bearer auth), per-route middleware, session-setting middleware, or
-  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, sessions or auth strategies like authBearer/authCookie (use
-  pikku-auth), or deployment.
+  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.
 installGroups: [core]
 ---
 
 # Pikku Middleware
 
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info tags --json` to understand the existing middleware and tag landscape.
-2. Identify the source files that own the behavior — wirings files, not generated output.
-3. Register middleware at module load time — in a `wirings/*.ts` file, never inside a function body.
-4. Validate: run `pikku all --tsc` after adding or changing middleware — it regenerates and then confirms type safety in one pass.
+Register middleware at module load time in a `wirings/*.ts` file, never inside a function body. After a change, run `pikku all --tsc`.
 
 ## The `pikkuMiddleware` Factory
 
@@ -223,7 +214,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-auth`).
+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`).
 
 ### It MUST be `addHTTPMiddleware`, never `addTagMiddleware`
 
@@ -255,13 +246,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-auth`).
+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`).
 
 ## 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-auth`), 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-permissions`), 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

@@ -1,6 +1,14 @@
 ---
 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).'
+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).
 installGroups: [core]
 metadata:
   version: 1.0.0

package/skills/pikku-n8n-import/references/addon-mapping.md

@@ -1,5 +1,11 @@
 # Integration stub → Pikku addon
 
+## Contents
+
+- Inputs
+- Per entry, in order
+- Never
+
 Translate n8n integration nodes (`gmailTool`, `slackTool`, `googleSheetsTool`, plain
 `gmail` / `slack` action nodes, etc.) that the importer left as throwing stubs into
 real `ref('<addonRpc>')` references pointing at functions in **installed**

package/skills/pikku-n8n-import/references/code-translation.md

@@ -1,5 +1,12 @@
 # n8n Code node → Pikku function
 
+## Contents
+
+- Process
+- Rubric
+- Example
+- Report
+
 Replace a Code-node stub's `throw new Error(...)` body with a faithful TypeScript
 reimplementation. The original JS is preserved verbatim in the JSDoc above the
 function. Keep the signature and JSDoc intact; only widen the Zod input/output if