@pikku/skills 0.12.21 → 0.12.25

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

@@ -0,0 +1,218 @@
+# Pikku i18n (Paraglide JS)
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Every user-facing string in a frontend is a message. Never hardcode display text — add a key to `messages/en.json` and render `m.the__key()`. This holds even when the app ships only English; the messages are the seam a second language slots into later.
+2. One `messages/<locale>.json` per language at the app root (NOT under `src/`), declared in `project.inlang/settings.json`. English (`en`) is `baseLocale` and the only locale until someone adds another. **`baseLocale` stays `en` whatever language the product speaks** — see [The product's language is not the code's language](#the-products-language-is-not-the-codes-language), which is the first thing to read if the brief says the app is not in English.
+3. Messages compile to typed ESM functions in `src/paraglide/` (generated, self-gitignored — never edit or commit it). The Vite plugin compiles during `dev`/`build` with HMR on message edits; run the CLI compile only when you need `tsc` before Vite has ever run.
+4. Validate with the app's own `tsc` then its `build`. The deploy pipeline compiles Paraglide and runs each frontend's `tsc` before building it — an i18n mistake blocks the deploy.
+
+## The product's language is not the code's language
+
+A brief that says "the entire UI is German, no English strings visible anywhere"
+is a statement about **one** of three separate things, and reading it as a
+statement about the codebase is the single most expensive mistake available in
+this skill. Three axes:
+
+| Axis            | What it covers                                                                                          | What sets it                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; database tables and columns                                   | Nothing — always English, no setting                            |
+| **Meta**        | `description` / `name` / `title` / `template` authored inside the code, which the Pikku Console renders | `metaLocale` in `pikku.config.json`, default `en`                   |
+| **Product UI**  | Every string the app shows a user                                                                       | `messages/<locale>.json` + `defaultLocale` — **this axis only** |
+
+A non-English product moves the third row and nothing else.
+
+### `baseLocale` stays `en`
+
+`baseLocale` in `project.inlang/settings.json` does not mean "the language the
+app is in". It names the message **source** — the catalogue every other locale is
+cloned from and translated against. Setting it to the product's language looks
+like it works, because the app does come up in that language, and then:
+
+- there is no `en.json`, so `--add-locale` has no catalogue to translate from
+- the app can never gain a second language without re-authoring every key
+- a message missing from a locale falls back to a catalogue nobody wrote
+
+The setting that actually decides what a first-time visitor sees is
+`defaultLocale`, held in `apps/app/src/i18n/active.json` in the Fabric app
+template and read by `src/i18n/config.ts`. It is deliberately a separate file
+from `settings.json` for exactly this reason — the source language and the
+served language are different questions.
+
+So a German medical portal is **three** settings, not one:
+
+```jsonc
+// project.inlang/settings.json — the source catalogue is English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "metaLocale": "de" }
+```
+
+In the Fabric template both of the first two have a command, so you rarely edit
+them by hand:
+
+```sh
+fabric i18n --add-locale de       # adds "de" to locales, seeds messages/de.json from en.json
+fabric i18n --default-locale de   # writes active.json — the app now OPENS in German
+```
+
+### The failure this is written from
+
+A real build, from this template. The brief said the UI was German; the agent
+set `baseLocale: "de"` with `locales: ["de"]` and no `en.json`, then carried the
+same reading into the code — RPC functions `getUebersicht` and
+`getPatientendetail`, components `Zeitstrahl` and `AufmerksamkeitStreifen`,
+helpers `datumDeutsch` and `voraussichtlichFertig`, database tables `vorgang`
+and `ereignis` with German columns.
+
+The German UI it was asked for needed none of that. It needed German **values**
+in a catalogue whose keys and source stayed English. What it got instead was a
+project that cannot add a second language and cannot be picked up by anyone who
+does not read German.
+
+If you find a project in this state, say so plainly rather than working around
+it: `baseLocale` cannot be repointed without re-keying every message, so it is a
+migration someone has to agree to, not a fix to slip in.
+
+## The moving parts (starter-template layout)
+
+- `messages/en.json` — flat keys, `{param}` interpolation, inlang message-format:
+  ```json
+  {
+    "$schema": "https://inlang.com/schema/inlang-message-format",
+    "auth__login__title": "Sign in",
+    "auth__login__description": "Welcome back to {name}."
+  }
+  ```
+  Key convention: lower snake_case, `__` (double underscore) between namespace segments, `_` within a segment — `auth__login__title`, `common__email_placeholder`.
+- `project.inlang/settings.json` — `baseLocale`, `locales`, the `@inlang/plugin-message-format` module, `pathPattern: "./messages/{locale}.json"`.
+- `vite.config.ts` — `paraglideVitePlugin({ project: './project.inlang', outdir: './src/paraglide' })` from `@inlang/paraglide-js` (devDependency), FIRST in the plugins array.
+- `src/paraglide/` — compiled output (`messages.js`, `runtime.js`, per-locale `messages/*.js`). Generated; it writes its own `.gitignore`.
+- `src/i18n/config.ts` — locale plumbing, and the ONLY hand-written i18n module: `supportedLocales`/`defaultLocale` (re-exported from `../paraglide/runtime.js`), `detectLocale`, `localeDir` (RTL for ar/he/fa/ur), a reactive locale store (`overwriteGetLocale` bridged to `useSyncExternalStore`), `setActiveLocale`, `useLocale()`. This is not a wrapper over messages — Paraglide's `getLocale()` is a module global with no React reactivity, and this bridges it. Wire `overwriteGetLocale` or `m.*()` will resolve a different locale than the app thinks is active.
+- `tsconfig.json` — `"allowJs": true, "checkJs": false` so `tsc` can consume Paraglide's JSDoc-typed JS output.
+
+## Using messages in components
+
+```tsx
+import { m } from '../paraglide/messages.js'
+import { useLocale } from '@/i18n/config'
+
+function LoginPage() {
+  useLocale() // subscribe: re-render m.*() when the locale switches
+  return (
+    <>
+      <Title>{m.auth__login__title()}</Title>
+      <Text>{m.auth__login__description({ name: m.app__name() })}</Text>
+    </>
+  )
+}
+```
+
+- Params: `{name}` in the JSON → `m.auth__login__description({ name })`. Params are typed per message.
+- Any component that renders `m.*()` calls `useLocale()` (bare call is enough); it also returns `{ locale, dir, setLocale }` for switchers.
+- Non-component helpers (formatters, status maps) call `m.some__key()` directly — the functions are plain ESM, no hook needed; the render-time subscription lives in the component that displays the result.
+- Locale switching: the root route persists to localStorage, sets `<html lang dir>` (`localeDir`), and calls `setActiveLocale` — in-SPA re-render, no page reload. Mirror `routes/__root.tsx` in the starter template.
+
+## Keys only known at runtime (enum labels, status maps)
+
+A DB value picking a label is the one case a generated message can't express.
+Paraglide's README (§ "What about dynamic or CMS-driven keys?") is explicit: use
+an **explicit mapping from value to message function**. Key it on the enum type,
+never `string`:
+
+```ts
+import { m } from '../paraglide/messages.js'
+
+const DOCUMENT_STATUS_LABEL: Record<DocumentStatus, () => string> = {
+  completed: m.enum__document_status__completed,
+  in_progress: m.enum__document_status__in_progress,
+  required: m.enum__document_status__required,
+}
+
+// call site — no fallback, because there is no missing case
+DOCUMENT_STATUS_LABEL[status]()
+```
+
+`Record<DocumentStatus, …>` is exhaustive: add a value to the enum without a
+label and the build fails. That is the entire point.
+
+**Don't write these maps by hand.** `@pikku/paraglide` generates them from the
+`enum__<group>__<member>` keys in the catalog and types each one against the DB
+enum it mirrors, so a migration adding a status is a compile error rather than a
+map someone forgot. Use the namespace above (singular `enum`, `__` between
+segments) so the generator picks the group up, and read `references/enum-labels.md` before
+adding one.
+
+Do NOT write `Record<string, () => string>` with a `?? status` fallback, and do
+NOT index the namespace with a computed key (`m[\`enums__${name}__${value}\`]`).
+Both compile, both render the raw identifier to users when a label is missing,
+and both reintroduce exactly the silent-fallback failure Paraglide exists to
+eliminate. If you find yourself writing a `resolveDynamicKey(key: string)`
+helper, stop — that helper IS the bug.
+
+## Type safety — and why deploys block on i18n
+
+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.
+
+## Compile step
+
+- **Dev/build:** the Vite plugin compiles automatically; editing `messages/*.json` under a running dev server recompiles + HMRs.
+- **Standalone `tsc` before Vite has run** (fresh clone, CI):
+  ```sh
+  npx @inlang/paraglide-js compile --project ./project.inlang --outdir ./src/paraglide
+  ```
+  This is exactly what the deploy CI does before the per-app `tsc`.
+
+## Adding a second language
+
+1. `messages/fr.json` mirroring `en.json`'s keys (translate the values, keep `{param}` names identical).
+2. Add `"fr"` to `locales` in `project.inlang/settings.json`. **Leave `baseLocale` at `en`** — step 1 only works because there is an English catalogue to mirror.
+3. Recompile (restart/`vite dev` or the CLI compile). A locale file missing keys falls back to the base locale per message.
+4. Content is reachable via the `/<lang>` URL prefix (`detectLocale` already resolves it); the base locale needs no prefix. Expose the switcher via `useLocale().setLocale`.
+5. Only if the app should **open** in the new language rather than merely offer it: set `defaultLocale` (`active.json` / `fabric i18n --default-locale fr`). Adding a locale and changing the default are different asks — do the second only when asked.
+
+## 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.
+
+**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:
+
+1. A script generates `messages/zz.json` from `en.json`, replacing `\S` with `█` while leaving `{placeholders}` intact (they are message inputs — mangling them changes the compiled signature). Run it before `paraglide-js compile`; gitignore the output.
+2. Add `"zz"` to `locales` in `project.inlang/settings.json`.
+3. Switch to it in the locale bridge:
+   ```ts
+   overwriteGetLocale(() => (isI18nDebug() ? 'zz' : activeLocale))
+   ```
+
+Keep `zz` out of the app's own `supportedLocales` — that drives URL prefixes, hreflang and any backend `locale` param, none of which should see it.
+
+Generate the catalogue in dev only. With `messages/zz.json` absent, Paraglide compiles `zz` to an alias of the base locale (`const zz_x = en_x` — one line per message, no duplicated strings), so a production bundle carries the locale at effectively zero cost.
+
+Both the generator and the store bridge are being upstreamed (pikkujs/pikku#1036, #1035).
+
+The wrapper alternative — a module that walks the namespace and pipes each message through a `mask()` — is what this replaces. It defeats tree-shaking (touching every export), adds a check on every call, and forces every component to import `m` from the wrapper instead of Paraglide.
+
+## What NOT to do
+
+- Don't hardcode display strings "just for now" — the message is the work.
+- Don't set `baseLocale` to anything but `en`, whatever language the product speaks. It names the source catalogue, and a project without one can never add a language. Set `defaultLocale` instead.
+- 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.
+
+  `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.
+
+  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message _function_ and call it — the map is type-checked, a string is not.
+
+- Don't re-resolve messages by string key or re-implement `{param}` interpolation. A key-string resolver turns a missing key back into silent runtime text, surrendering the type safety that is the entire reason to use Paraglide.
+- Don't reach for i18next/react-i18next or a runtime-fetch translation loader — Paraglide's compiled functions are the whole delivery mechanism.
+- Don't tokenize backend error messages or logs here — those are not frontend display strings.

package/skills/{pikku-rtl/SKILL.md → pikku-i18n/references/rtl.md}

@@ -1,12 +1,6 @@
----
-name: pikku-rtl
-description: 'Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.'
-installGroups: [client]
----
-
 # Pikku RTL (Arabic + English)
 
-This skill sits **on top of** `pikku-i18n`. That skill compiles a locale's
+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
 `messages/ar.json` listed in `project.inlang/settings.json`, plus the document
@@ -23,7 +17,7 @@ _layout_ code — directional icons still need one manual step, covered below.
 ## Agent Operating Procedure
 
 1. **Messages first.** Every visible string is already an `m.*()` message via
-   `pikku-i18n`. Arabic copy goes in `messages/ar.json`, mirroring `en.json`'s
+   `references/messages.md`. Arabic copy goes in `messages/ar.json`, mirroring `en.json`'s
    keys with the `{param}` names kept identical.
 2. **Add the direction helper** to the i18n config (one home for locale→dir):
    ```ts
@@ -219,5 +213,5 @@ left` with the flow-relative equivalent; revert any manual `row-reverse`.
 - Don't set `dir` on individual components — it belongs on `<html>` so the whole
   document (and Mantine) agrees.
 - Don't translate Arabic copy outside the message system; an RTL language is a
-  normal locale, governed by `pikku-i18n`. There is no `t()` and no i18next in 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

@@ -242,6 +242,20 @@ pikku knowledge index --check   # report stale indexes without writing (CI gate)
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 
+### The milestone plan
+
+A milestone note says what the app must DO. Its **plan** — JSON beside the note, not prose — says what has to exist for it, and is what a finished build is measured against:
+
+```bash
+pikku knowledge plan schema                        # the format, in full
+pikku knowledge plan set <milestone> <file>        # validate and write it
+pikku knowledge plan show <milestone> --for-build  # the ordered work a build follows
+pikku knowledge plan progress <milestone>          # what it still owes, read from .pikku/
+pikku knowledge plan defer <milestone> <item> -r "<why>"
+```
+
+`progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. Writing a plan is its own seat: read `pikku-architect`. Building against one is `pikku-build`.
+
 ## Profiles built on this one
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.

package/skills/pikku-kysely/SKILL.md

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

package/skills/pikku-meta/SKILL.md

@@ -1,139 +1,67 @@
 ---
 name: pikku-meta
 description: >-
-  Read and change a Pikku project's declarations without grepping or hand-editing — functions
-  (with their transport, middleware and permissions), schemas, workflows, wires, tags, middleware
-  and permission definitions, plus `pikku meta apply` to set config on them. TRIGGER when: user
-  asks "what functions exist?", "show me the project structure", "list routes/middleware/
-  permissions", needs a function's input/output shape, or wants to add a permission, retag a
-  function, or change a declaration's config. DO NOT TRIGGER when: user is writing a NEW function
-  or wiring (use the specific wiring skill) or asking about Pikku concepts (use pikku-concepts).
+  Use to inspect or evolve a project you did not just write — `pikku meta` and `pikku info` for
+  what the project declares (functions, schemas, wires, workflows, middleware, permissions) and
+  `pikku meta apply` to change it, `pikku versions` / `pikku semver` for contract hashes,
+  breaking-change detection and the semver a release should get, and `pikku audit` / `pikku
+  update` for dependency advisories and moving Pikku forward. TRIGGER when: user asks what
+  functions or routes exist, wants a function's input/output shape, wants to retag a function or
+  set config on a declaration, asks about API versioning, breaking changes, what semver a release
+  deserves, dependency vulnerabilities, the console Security screen, or upgrading Pikku. DO NOT
+  TRIGGER when: user is writing a new function or wiring (use the wiring skill) or asking about
+  Pikku concepts (use pikku-concepts).
 installGroups: [core]
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku info *)
-argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply]'
+argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply|versions|semver|audit|update]'
 ---
 
 # Pikku Project Metadata
 
-`pikku meta` is the machine-readable view of the project and the write path to it.
-`pikku info` is the same ground as human-readable tables. Prefer `meta` when you are
-going to act on the output; prefer `info` when a person is going to read it.
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Change a declaration's config with `pikku meta apply`, not by hand-editing the file.
-4. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-5. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-6. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-## Reading
-
-| Command                         | What it answers                                                                                                                  |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `pikku meta context`            | Everything a planner needs in one call — functions, wires, middleware, permissions, workflows, capabilities, layout. Start here. |
-| `pikku meta functions get <id>` | One function's input/output schema names, source file, tags, expose/readonly                                                     |
-| `pikku meta schemas get <name>` | One generated JSON schema                                                                                                        |
-| `pikku meta workflows get <id>` | One workflow's steps                                                                                                             |
-| `pikku meta permissions list`   | What permissions exist and where they are defined                                                                                |
-| `pikku meta middleware list`    | What middleware exists                                                                                                           |
-| `pikku meta wires list`         | Wires by transport (http, channel, scheduler, queue, trigger)                                                                    |
-| `pikku meta clients`            | Exposed RPCs/workflows/channels with their type names — what a frontend can call                                                 |
-
-`list` is the default for each group, so `pikku meta functions` and `pikku meta functions list`
-are the same call.
-
-A function's input/output shape comes from here. Do not infer it by reading the
-function body, and do not cast a call site to make it compile — the schema is the type.
-
-## Changing
-
-`pikku meta apply` applies a batch of edits to your own source. Pass JSON as a file
-or on stdin:
-
-```bash
-pikku meta apply ops.json
-```
-
-```json
-{
-  "operations": [
-    {
-      "kind": "functionConfig",
-      "sourceFile": "src/functions/todos.functions.ts",
-      "exportedName": "listTodos",
-      "changes": { "title": "List Todos", "tags": ["todos", "read"] }
-    },
-
-    {
-      "kind": "functionConfig",
-      "sourceFile": "src/functions/todos.functions.ts",
-      "exportedName": "listTodos",
-      "changes": {
-        "permissions": {
-          "functionLevel": {
-            "name": "isTodoOwner",
-            "from": "../permissions.js"
-          }
-        }
-      }
-    }
-  ]
-}
-```
-
-Three kinds: `functionConfig`, `agentConfig`, `functionBody`. Every operation names
-a `sourceFile` and the `exportedName` declared in it.
-
-`functionConfig` changes: `title`, `description`, `summary`, `tags`, `errors`,
-`expose`, `remote`, `mcp`, `readonly`, `approvalRequired`, `permissions`.
-`agentConfig` changes: `name`, `description`, `instructions`, `role`, `personality`,
-`goal`, `model`, `maxSteps`, `temperature`, `toolChoice`, `tools`, `tags`.
-
-`null` removes a property. Edits are spliced into the original text, so formatting,
-comments and JSDoc survive.
-
-`permissions` and `tools` are written as identifiers rather than literals, so each
-one carries the module it comes from (`{"name": "isTodoOwner", "from": "../permissions.js"}`)
-and the missing import is added for you — widening an existing import from that
-module rather than adding a second one.
-
-### Why batch
-
-The whole batch either lands or it does not: every operation is resolved before
-anything is written, so a failure leaves every file untouched and names the
-operation that caused it. Batching is also what makes one codegen pass correct —
-**run `pikku all` once after the batch**, not once per property. The response tells
-you whether it is needed:
-
-```json
-{
-  "schemaVersion": "meta-apply.v1",
-  "applied": 2,
-  "files": ["src/functions/todos.functions.ts"],
-  "generatedMetaIsStale": true
-}
-```
-
-## Human-readable tables (`pikku info`)
-
-Four subcommands only — `functions`, `tags`, `middleware`, `permissions`. Routes,
-channels, schedulers and queues are not subcommands; they are the _transport_ column
-of `info functions --verbose`.
-
-```bash
-yarn pikku info functions --verbose --silent
-yarn pikku info tags --silent
-yarn pikku info middleware --verbose --silent
-yarn pikku info permissions --verbose --silent
-```
-
-`--silent` suppresses the banner and inspector diagnostics. It works, but it is not
-declared as an option, so every run also prints `Warning: Unknown option: --silent
-(ignored)` — the warning is wrong. Ignore that one line.
-
-`--limit N` caps rows (default 50); the footer says how many were withheld.
-On `tags`, `--verbose` swaps counts for names; elsewhere it adds columns.
+The project already knows what it declares. Ask it rather than grepping for it,
+and change it through the write path rather than by hand.
+
+## Pick the reference
+
+| You are… | Read |
+| --- | --- |
+| Asking what exists, or setting config on a declaration | `references/meta.md` |
+| Versioning a contract, or deciding a release's semver | `references/versioning.md` |
+| Chasing a dependency advisory, or upgrading Pikku | `references/audit.md` |
+
+## Start with `pikku meta context`
+
+It answers in one call what a planner needs — functions, wires, middleware,
+permissions, workflows, capabilities, layout. Reach for `pikku meta` when you
+are going to act on the output and `pikku info` when a person will read it;
+they are the same ground in two shapes.
+
+## Direction decides whether a change is breaking
+
+An input is contravariant (the caller writes it) and an output is covariant (the
+caller reads it), so the same edit is not the same event on both. Adding a
+required field breaks an input and is compatible on an output; making a field
+optional is the reverse. `pikku semver` reads the generated JSON Schemas with
+that asymmetry built in, so let it decide rather than eyeballing a diff.
+
+## What NOT to do
+
+- **Do not infer a function's input or output by reading its body**, and do not
+  cast a call site to make it compile. The schema is the type; `pikku meta
+  functions get <id>` has it.
+- **Do not expect an unversioned function to be promoted for you.** Without an
+  explicit `version: 2` it is version 1 of its contract, collides with the
+  pinned `@v1`, and `pikku versions check` reports the published contract as
+  modified.
+- **Do not reach for `override` by default.** The contract key already drops a
+  matching `V<n>` suffix from the export name, so `getBookV1` keys under
+  `getBook`. `override` is for an export that cannot follow that convention.
+- **Do not shell out to the package manager from a function.** The audit is a
+  generated artifact — read `.pikku/audit.json` through
+  `metaService.readFile('audit.json')`.
+- **Do not redeclare the audit report's shape.** `SecurityAuditReport` and its
+  companions come from `@pikku/core`; the CLI writes it, the addon reads it, the
+  UI renders it.
+- **Do not treat a failed audit run as a clean one.** `bun audit` exits non-zero
+  when it *finds* advisories and still writes its payload, so non-zero with
+  output is data; non-zero with no output throws on purpose.

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

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