@pikku/skills 0.12.35 → 0.12.38

package/skills/pikku-changes/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: pikku-changes
+description: 'Work a project''s changes queue — the todo list someone filed by walking a deployed stage. Covers `pikku fabric changes list|claim|show|ask|shot|done`, when to ask a question instead of guessing, and how to offer options as images. TRIGGER when: the user says "work the changes", "pick up the changes queue", names a change by its #number, or you are otherwise idle in a repo that has a pikkufabric.config.json. DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
+installGroups: [fabric]
+---
+
+# Working a changes queue
+
+Someone walked the deployed app and circled twenty things. Each one is a row with their
+words, a picture of what they were looking at, and the elements the circle enclosed. You
+have the repo and the app running locally. Your job is to empty the queue without making
+them regret filing.
+
+## The loop
+
+Every argument is a flag; nothing is positional. `--json` works on any of them. The
+project comes from the local `pikkufabric.config.json`, so `--project-id` is only needed
+when you are not in the checkout.
+
+```bash
+pikku fabric changes list --pickup-only --json
+pikku fabric changes claim --change-ids <id>,<id> --title "Checkout pass" --claimed-by claude-code
+pikku fabric changes show --change-id <id>
+pikku fabric changes ask --change-id <id> --question "…" --option "…" --option "…" --author-name claude-code
+pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
+pikku fabric changes done --change-id <id> --note "What you did"
+```
+
+`list --pickup-only` is the one a harness wants: it skips items still inside the grace
+window, so a batch someone is mid-way through typing is picked up together rather than item
+by item as it lands.
+
+Deciding what belongs together is yours: `claim` with `--change-ids` and no `--group-id`
+forms the group. Claim an existing one with `--group-id`.
+
+Claim before working. The lease expires (30 minutes by default, `--lease-minutes` to
+change it), so an abandoned claim returns to the queue rather than parking the work
+forever — but a second harness picking up something you are halfway through is the failure
+this prevents.
+
+## Reading an item
+
+`show` gives you four things, in descending order of trustworthiness:
+
+1. **Their words.** The title and body are the requirement. Everything else is evidence.
+2. **The screenshot.** What they actually saw, at their width, with their data. When the
+   other addresses disagree with the picture, the picture is right.
+3. **The circled elements** — a testid, a source anchor, a CSS path. The testid greps
+   straight to a component because it is the i18n message key.
+4. **The source anchor**, printed as `src/routes/app.orders.tsx:42 as of a91c4e2`. That line
+   number is where the JSX was **at that commit**. Read it as a starting point and find
+   today's equivalent; never edit line 42 of today's file because the anchor said 42.
+
+Resolution is a guess and the panel says so. If the circle and the anchor point at
+different things, believe the circle.
+
+## When to ask
+
+Ask when the item admits more than one reasonable implementation and you would be **picking
+for them**. Do not ask to confirm something the item already says.
+
+Ask:
+- "Make the total stand out" — bigger, bolder, coloured, or moved above the fold?
+- "This should be faster" — is it the spinner, the request, or the number of steps?
+- Anything that changes what data is stored, what an existing user sees, or what something costs.
+
+Do not ask:
+- "Should I use flexbox or grid?" — that is yours.
+- "Do you want me to fix the typo?" — they filed it; fix it.
+- "Can you confirm you want the button blue?" — they said blue.
+
+A question costs them a context switch, not typing. That is the budget you are spending.
+
+## What a good question looks like
+
+One decision. Their vocabulary, not the codebase's. And the choices in `--option`, not in
+the sentence.
+
+> **Bad:** "How would you like me to handle the ambiguity in the checkout total component's
+> emphasis requirement?"
+>
+> **Good:** `--question "Make the total stand out — which way?"`
+> `--option "Bigger" --option "Move it above the delivery line"`
+
+**A choice written into the prose is not a choice.** Every `--option` becomes a button in
+the panel and the console, and clicking one records the answer; a question that says
+"(a) build it, (b) leave existing bookings, (c) hold" makes them re-type in free text what
+they should have been able to click, and leaves you parsing prose to find out which one
+they meant. If you can enumerate them in the sentence, you can pass them as flags.
+
+Pass them even when there are only two, and even when one is "hold until I check" — that
+last one is a real option and it is the one most often left off. The filer can always
+choose "say something else", so the list constrains nothing.
+
+Batch per group. Three questions about one checkout flow go out together; three separate
+asks about the same screen is three interruptions for one context switch.
+
+Then **park it**. `ask` flips the item to `needs_answer` and you move to the next item. Do
+not sit waiting — pick answers up on your next `show`, and bound your polling so an
+unanswered item does not spin forever.
+
+## When to show instead of ask
+
+If the answer is visual and you can build it, build all of them and attach images:
+
+```bash
+pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
+pikku fabric changes shot --change-id <id> --label "Above the line" --kind option --image b.png
+```
+
+The panel turns a set of `option` attachments into a pick-one they open full-screen, and
+picking one writes the choice into the thread. Capture every variant in **one pass at one
+width**, including the baseline — variants shot at different sizes are not comparable, and
+comparing is the whole point.
+
+`--kind evidence` is the other use: a picture that proves something, rendered inline rather
+than as a choice.
+
+## Committing
+
+One item, one commit. `done` records a single `head_commit`, and that sha is what a human
+reverts when they change their mind — so an item folded in with three others cannot be
+undone without taking the other three with it. Land unrelated work separately.
+
+The subject carries the short id the way a GitHub issue number does, and the uuid goes in a
+trailer so `git log --grep` has an exact handle:
+
+```
+feat(login): #4 make the sign-in heading brown
+
+Change-Id: 0f3c8a12-9b44-4d2e-8f01-27c6a1d9e5b3
+```
+
+Both ids come from `show`. The type and scope are the usual conventional-commit ones —
+`feat`, `fix`, `style`, `refactor` — with the scope naming the screen or area they were
+looking at, not the file you edited.
+
+More:
+
+```
+fix(booking): #7 stop the date picker closing on the first click
+style(nav): #12 tighten the spacing around the logo
+```
+
+Reverting one later is then:
+
+```bash
+git revert $(git log --grep="Change-Id: <uuid>" --format=%H -1)
+```
+
+## Finishing
+
+`done` records the branch and commit that closed it, which is what strikes the item through
+on the page it was filed on and tells them where the fix landed. Both default to the
+checkout you are standing in, so run it from there and let it read git:
+
+```bash
+pikku fabric changes done --change-id <id> \
+  --note "What you did, for whoever reads the thread later"
+```
+
+`--branch` and `--head-commit` override them, for the case where the fix landed somewhere
+other than where you are. Never type a sha by hand — one that does not exist points the
+filer at nothing.
+
+An item you decided not to do is not `done`. Say why in the thread and leave it for a human
+to dismiss.
+
+## Scope
+
+Writes need the `changes:project:write` scope on your bearer. `list` and `show` are reads.
+The project comes from the local `pikkufabric.config.json`, so run these from the checkout.

package/skills/pikku-concepts/SKILL.md

@@ -20,7 +20,7 @@ Use this skill as an execution checklist, not reference material.
 1. Discover before editing. Run `pikku doc --ai` for the installed API surface, and the relevant `pikku meta ... --json` for what this project has wired.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+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.
 
 Pikku is a TypeScript framework that separates business logic from transport mechanisms. You define a function once, then wire it to HTTP, WebSocket, queues, schedulers, MCP, CLI, or RPC — without the function knowing how it's being called.
@@ -286,62 +286,22 @@ Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI doc
 
 ## Server Bootstrap
 
-There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+Two ways to start a Pikku app, and the choice is whether you need to own the HTTP server.
 
-**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+**Let Pikku own it** — `pikku dev` and `pikku serve` create the config and singleton services,
+start the server and shut it down cleanly, so you write no bootstrap code at all. Startup and
+shutdown work goes in one exported `pikkuServerLifecycle` (`beforeStart` / `afterStart` /
+`beforeStop`). **Only `dev` and `serve` invoke those hooks** — no deploy runtime does, so anything
+a Workers or serverless stage needs done belongs on the request path that needs it.
 
-`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+**Bootstrap it yourself** — required for Express, Fastify, uWS, Lambda, Cloudflare and Next.js,
+where Pikku is embedded in a server you own. Lifecycle hooks do not run on this path; do the
+startup work in the entrypoint.
 
-```typescript
-// src/lifecycle.ts
-import { pikkuServerLifecycle } from '@pikku/core'
-import type { SingletonServices } from '../types/application-types.js'
-
-export const lifecycle = pikkuServerLifecycle<SingletonServices>({
-  beforeStart: async ({ kysely }) => {
-    await runMigrations(kysely)
-  },
-  afterStart: async ({ logger }) => {
-    logger.info('accepting traffic')
-  },
-  beforeStop: async ({ queueService }) => {
-    await queueService.drain()
-  },
-})
-```
-
-Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
-
-**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
-
-**2. Bootstrap it yourself (required for a specific runtime)**
+`pikku validate` warns when a project starts a server by hand *and* depends on no runtime adapter,
+because that means the first path was available and unused.
 
-Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
-
-```typescript
-import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-// Pick your runtime:
-const server = new PikkuFastifyServer(
-  config,
-  singletonServices,
-  createWireServices
-)
-// or: new PikkuExpressServer(config, singletonServices, createWireServices)
-// or: pikkuAWSLambdaHandler(singletonServices)
-// or: PikkuCloudflareHandler(singletonServices)
-// or: pikkuNextHandler(singletonServices)
-
-await server.init()
-await server.start()
-```
-
-**Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
-
-`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
+**`references/bootstrap.md`** has both entrypoints in full.
 
 ## Code Generation
 
@@ -392,91 +352,26 @@ src/
 
 ## What Language You Write In
 
-Three different things in a Pikku project have a human language, and they are
-**not** the same language. Collapsing them is the mistake this section exists to
-prevent, and it has already shipped in a real product — the failure is at the
-bottom.
-
-| Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
-| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
-| **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
-
-### Identifiers are English, and nothing changes that
-
-Not the product's market, not the team's working language, and **not `metaLocale`**.
-A German medical practice, an Arabic marketplace and a Japanese logistics tool
-all get `getOverview`, `AttentionStripe`, `case`, `event`.
-
-This is not linguistic preference, it is mechanics. Identifiers are the surface
-every other tool binds to: the generated `#pikku/*` clients, `pikku info` and
-`pikku meta`, the RPC map a scenario's `actor.invoke` is typed over, the
-generated SQL types, every skill and every agent that ever picks the project up.
-A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone who
-did not name it, and unlike a string it cannot be translated later — renaming an
-identifier is a migration, not an edit.
-
-### Meta follows `metaLocale`, and that is what the field is for
-
-```json
-{ "metaLocale": "de" }
-```
-
-Meta is the one part of a project the **Pikku Console** renders back to a human.
-A team reviewing their own functions, features and scenario reports in the
-Console is reading meta and nothing else, so a team whose working language is
-German should be able to read their Console in German. That is the entire reason
-the field exists.
-
-Read it before you author meta, and write descriptions, titles and templates in
-it. Absent, it is `en`. It is a BCP-47 tag (`en`, `de`, `pt-BR` — a hyphen, not
-an underscore), and the CLI rejects anything else by name.
-
-`metaLocale` is **not** licence to rename anything. `metaLocale: "de"` buys a German
-`description: 'Zeigt die Arbeitsliste'` on a function still called
-`getWorklist`.
-
-### Product UI language lives in the catalogue, and only there
-
-What the app says to its users is a translation concern, not a code concern. It
-belongs in `messages/<locale>.json`; `pikku-i18n` owns the details. The one rule
-worth repeating here: **`baseLocale` in `project.inlang/settings.json` stays
-`en`.** It names the message _source_ — the catalogue every other language is
-cloned from and translated against — so a project that sets it to anything else
-has no English catalogue to translate from and can never gain a second language
-without re-authoring every key.
-
-### The failure this comes from
-
-An agent was asked to build a doctor's portal for a German practice. The brief
-said "the entire UI is German, no English strings visible anywhere". The agent
-read one sentence about the product's users as an instruction about the
-codebase, and produced:
-
-- `project.inlang/settings.json` with `baseLocale: "de"` and `locales: ["de"]`,
-  no `en.json` at all — which silently broke `--add-locale` forever
-- RPC functions `getUebersicht` and `getPatientendetail`
-- React components `Zeitstrahl` and `AufmerksamkeitStreifen`
-- database tables `vorgang` and `ereignis`, with German columns
-
-Every one of those is wrong, and the brief was satisfied by none of them: a
-German UI needs German _messages_. What that project actually wanted was three
-settings, each on its own axis:
-
-```jsonc
-// project.inlang/settings.json — the message source stays English
-{ "baseLocale": "en", "locales": ["en", "de"] }
-
-// apps/app/src/i18n/active.json — what a first-time visitor opens in
-{ "defaultLocale": "de" }
-
-// pikku.config.json — the language the team reads their Console in
-{ "metaLocale": "de" }
-```
-
-Identifiers stay English throughout. When a brief tells you the product speaks a
-language, it is telling you about axis three and nothing else.
+Three different things in a Pikku project have a human language, and they are **not** the same
+language. Collapsing them has already shipped in a real product:
+
+| Axis            | Covers                                                                        | Decided by                                     |
+| --------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; tables and columns; commit messages | Nothing. **Always English.** There is no setting |
+| **Meta**        | Prose authored inside the code — `description`, `title`, step `template`      | `metaLocale` in `pikku.config.json` (default `en`) |
+| **Product UI**  | Every string the app shows a user                                             | `messages/<locale>.json`, and `active.json`'s `defaultLocale` |
+
+Identifiers are the surface every other tool binds to — the generated clients, the RPC map a
+scenario is typed over, the SQL types — and unlike a string an identifier cannot be translated
+later: renaming one is a migration. `metaLocale` exists so a team can read their own Console in
+their own language; it is not licence to rename anything. And `baseLocale` in
+`project.inlang/settings.json` stays `en`, because it names the message *source* every other
+language is cloned from.
+
+**When a brief tells you the product speaks a language, it is telling you about the third axis and
+nothing else.** `references/language.md` has the three settings that satisfy such a brief, and the
+build that read one sentence about a product's users as an instruction about its codebase — German
+RPC names, German tables, and no English catalogue to ever translate from.
 
 ## Environment Variables
 

package/skills/pikku-concepts/references/bootstrap.md

@@ -0,0 +1,58 @@
+# Server bootstrap
+
+There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+
+**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+
+`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+
+```typescript
+// src/lifecycle.ts
+import { pikkuServerLifecycle } from '@pikku/core'
+import type { SingletonServices } from '../types/application-types.js'
+
+export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+  beforeStart: async ({ kysely }) => {
+    await runMigrations(kysely)
+  },
+  afterStart: async ({ logger }) => {
+    logger.info('accepting traffic')
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain()
+  },
+})
+```
+
+Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
+
+**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
+
+**2. Bootstrap it yourself (required for a specific runtime)**
+
+Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
+
+```typescript
+import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+// Pick your runtime:
+const server = new PikkuFastifyServer(
+  config,
+  singletonServices,
+  createWireServices
+)
+// or: new PikkuExpressServer(config, singletonServices, createWireServices)
+// or: pikkuAWSLambdaHandler(singletonServices)
+// or: PikkuCloudflareHandler(singletonServices)
+// or: pikkuNextHandler(singletonServices)
+
+await server.init()
+await server.start()
+```
+
+**Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
+
+`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.

package/skills/pikku-concepts/references/concept-mapping.md

@@ -2,6 +2,22 @@
 
 Authoritative mapping table plus side-by-side code examples showing how common backend patterns translate to Pikku.
 
+- [Quick Reference Table](#quick-reference-table)
+- [Route Handler / Controller → pikkuFunc](#route-handler--controller--pikkufunc)
+- [Route Parameters → Merged into Data](#route-parameters--merged-into-data)
+- [Middleware → pikkuMiddleware](#middleware--pikkumiddleware)
+- [Auth Guard → Built-in Auth Middleware](#auth-guard--built-in-auth-middleware)
+- [Authorization / Role Checks → pikkuPermission](#authorization--role-checks--pikkupermission)
+- [DTO / Request Validation → Standard Schema](#dto--request-validation--standard-schema)
+- [Dependency Injection → Service Factories](#dependency-injection--service-factories)
+- [WebSocket Handlers → wireChannel](#websocket-handlers--wirechannel)
+- [Job Queue Workers → wireQueueWorker](#job-queue-workers--wirequeueworker)
+- [Cron / Scheduled Tasks → wireScheduler](#cron--scheduled-tasks--wirescheduler)
+- [Module / Feature Grouping → Tags + File Organization](#module--feature-grouping--tags--file-organization)
+- [Error Handling → Typed Errors](#error-handling--typed-errors)
+- [Session Management](#session-management)
+- [API Client Generation](#api-client-generation)
+
 ## Quick Reference Table
 
 | Generic Backend Concept                 | Pikku Equivalent                                                | Skill             |

package/skills/pikku-concepts/references/language.md

@@ -0,0 +1,87 @@
+# What language you write in
+
+Three different things in a Pikku project have a human language, and they are
+**not** the same language. Collapsing them is the mistake this section exists to
+prevent, and it has already shipped in a real product — the failure is at the
+bottom.
+
+| Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
+| **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
+
+## Identifiers are English, and nothing changes that
+
+Not the product's market, not the team's working language, and **not `metaLocale`**.
+A German medical practice, an Arabic marketplace and a Japanese logistics tool
+all get `getOverview`, `AttentionStripe`, `case`, `event`.
+
+This is not linguistic preference, it is mechanics. Identifiers are the surface
+every other tool binds to: the generated `#pikku/*` clients, `pikku info` and
+`pikku meta`, the RPC map a scenario's `actor.invoke` is typed over, the
+generated SQL types, every skill and every agent that ever picks the project up.
+A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone who
+did not name it, and unlike a string it cannot be translated later — renaming an
+identifier is a migration, not an edit.
+
+## Meta follows `metaLocale`, and that is what the field is for
+
+```json
+{ "metaLocale": "de" }
+```
+
+Meta is the one part of a project the **Pikku Console** renders back to a human.
+A team reviewing their own functions, features and scenario reports in the
+Console is reading meta and nothing else, so a team whose working language is
+German should be able to read their Console in German. That is the entire reason
+the field exists.
+
+Read it before you author meta, and write descriptions, titles and templates in
+it. Absent, it is `en`. It is a BCP-47 tag (`en`, `de`, `pt-BR` — a hyphen, not
+an underscore), and the CLI rejects anything else by name.
+
+`metaLocale` is **not** licence to rename anything. `metaLocale: "de"` buys a German
+`description: 'Zeigt die Arbeitsliste'` on a function still called
+`getWorklist`.
+
+## Product UI language lives in the catalogue, and only there
+
+What the app says to its users is a translation concern, not a code concern. It
+belongs in `messages/<locale>.json`; `pikku-i18n` owns the details. The one rule
+worth repeating here: **`baseLocale` in `project.inlang/settings.json` stays
+`en`.** It names the message _source_ — the catalogue every other language is
+cloned from and translated against — so a project that sets it to anything else
+has no English catalogue to translate from and can never gain a second language
+without re-authoring every key.
+
+## The failure this comes from
+
+An agent was asked to build a doctor's portal for a German practice. The brief
+said "the entire UI is German, no English strings visible anywhere". The agent
+read one sentence about the product's users as an instruction about the
+codebase, and produced:
+
+- `project.inlang/settings.json` with `baseLocale: "de"` and `locales: ["de"]`,
+  no `en.json` at all — which silently broke `--add-locale` forever
+- RPC functions `getUebersicht` and `getPatientendetail`
+- React components `Zeitstrahl` and `AufmerksamkeitStreifen`
+- database tables `vorgang` and `ereignis`, with German columns
+
+Every one of those is wrong, and the brief was satisfied by none of them: a
+German UI needs German _messages_. What that project actually wanted was three
+settings, each on its own axis:
+
+```jsonc
+// project.inlang/settings.json — the message source stays English
+{ "baseLocale": "en", "locales": ["en", "de"] }
+
+// apps/app/src/i18n/active.json — what a first-time visitor opens in
+{ "defaultLocale": "de" }
+
+// pikku.config.json — the language the team reads their Console in
+{ "metaLocale": "de" }
+```
+
+Identifiers stay English throughout. When a brief tells you the product speaks a
+language, it is telling you about axis three and nothing else.

package/skills/pikku-deploy/SKILL.md

@@ -21,7 +21,7 @@ Use this skill as an execution checklist, not reference material.
 1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
+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.
 
 Signatures and option keys come from `pikku doc` — run `pikku doc --ai` for the

package/skills/pikku-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-fabric
-description: 'Build, convert and debug apps on the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, the pikku-verify workflow, and reading logs, traces and metrics from a deployed stage. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, asking about Fabric deployment, database or project conventions, asking about a `pikku fabric validate` finding including app-missing-actor-quick-login, or a deployed stage is erroring, timing out or behaving differently than local ("why is prod failing", "check the logs"). DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy instead — or the failure reproduces locally, which is where to debug it.'
+description: 'Build, convert and debug apps on the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `pikkufabric.config.json`, the `pikku all` + `tsc` verification loop, and reading logs, traces and metrics from a deployed stage. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, asking about Fabric deployment, database or project conventions, asking about a `pikku fabric validate` finding including app-missing-actor-quick-login, or a deployed stage is erroring, timing out or behaving differently than local ("why is prod failing", "check the logs"). DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy instead — or the failure reproduces locally, which is where to debug it.'
 installGroups: [fabric]
 ---
 
@@ -18,7 +18,7 @@ Use this skill as an execution checklist, not reference material.
 2. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 3. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.
+5. Validate with the narrowest relevant command first, then run `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.
 
 Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-wiring`, `pikku-services`, etc.
@@ -31,20 +31,20 @@ Always run project discovery first:
 yarn pikku meta context --json
 ```
 
-Call the `pikku-meta` tool before grepping or editing a Fabric app.
+Run `pikku meta` before grepping or editing a Fabric app.
 
-- Use `section: "context"` for the project map: functions, wires, workflows, capabilities, and source files.
-- Use `section: "clients"` before frontend/RPC work.
-- Use `section: "functions"` to list function ids, then `section: "function", id: "<functionId>"` for one function.
-- Use `section: "schemas"` to list schema names. Only request full JSON Schema bodies with `schemas: ["SchemaName"]` for the specific schemas needed.
+- `pikku meta context --json` for the project map: functions, wires, workflows, capabilities, and source files.
+- `pikku meta clients --json` before frontend/RPC work.
+- `pikku meta functions --json` to list function ids, then `pikku meta functions get <id> --json` for one function.
+- `pikku meta schemas --json` to list schema names. Only request a full schema body with `pikku meta schemas get <name> --json` when you need it.
 
 Do not load every schema body by default; that wastes context and usually makes the model worse.
 
 For database work:
 
-- Use `pikku-db` for the actual attached Fabric database state: tables, columns, foreign keys, and applied migrations.
-- Use `pikku-meta` `section: "schemas"` for code-level JSON Schema contracts, not database introspection.
-- Do not inspect database credentials or connect to the database directly; Fabric Control already exposes the safe introspection surface.
+- Use `pikku fabric db schema [--branch <branch>]` for the actual attached Fabric database state: tables and columns.
+- Use `pikku meta schemas` for code-level JSON Schema contracts, not database introspection.
+- Do not inspect database credentials or connect to the database directly; Fabric already exposes the safe introspection surface.
 
 ## Database: SQLite via libSQL
 
@@ -437,16 +437,16 @@ the deploy with "local HEAD … ≠ remote …" even though your code is pushed.
 
 Functions with `expose: true` are versioned via `versions.pikku.json`. When you change a function's input or output schema, you must bump its version number — otherwise `pikku all` will report a breaking change and callers' generated clients become stale.
 
-The `pikku-verify` tool catches this automatically.
+`pikku all` catches this automatically.
 
 ## After every code change
 
-Always call the `pikku-verify` tool after modifying functions, wirings, or schemas. It runs:
+Run `pikku all` after modifying functions, wirings, or schemas, then `tsc --noEmit`:
 
 1. `pikku all` — regenerates all codegen, checks version compliance
 2. `tsc --noEmit` — validates TypeScript types
 
-The output card shows whether any breaking changes were detected.
+Breaking changes are reported by the version check in step 1.
 
 ### `app-missing-actor-quick-login-<app>`