@pikku/skills 0.12.22 → 0.12.26

package/skills/pikku-build/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: pikku-build
+description: >-
+  Use to build on Pikku — turning a fresh scaffold into a working app (quick spike, real product,
+  or a showcase that exercises every surface), adding a feature to an app that already exists, and
+  the one-off cleanup right after a template is cloned. Covers the knowledge base, personas and
+  roles, milestone planning, the scenario that proves each one, theming, multi-app layouts and
+  deploying. TRIGGER when: the user asks for an app to be built on Pikku, a freshly scaffolded
+  project needs turning into a product, the user asks to add a feature or wire up a new endpoint
+  in a working app, or a template was just cloned or scaffolded. DO NOT TRIGGER when: the user
+  asks for a one-off edit to an existing function, asks about Pikku concepts (use pikku-concepts),
+  or wants one specific surface explained rather than built (use that surface's skill).
+allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
+argument-hint: '[feature description]'
+installGroups: [core]
+---
+
+# Build on Pikku
+
+## Which mode
+
+| The situation | Read |
+| --- | --- |
+| A template was just cloned or scaffolded, and the tree still looks like one | `references/post-clone.md` first, then come back |
+| A real product, meant to be picked up by someone else | `references/app.md` — the default |
+| A spike, a throwaway demo, an idea nobody has committed to | `references/quick.md` |
+| A showcase meant to exercise every Pikku surface | `references/platform.md`, which is a delta on top of `references/app.md` |
+| A feature added to an app that already has its knowledge base and milestones | `references/feature.md` |
+
+**App is the default.** A small or toy-sounding app does not make it Quick;
+only an explicit signal of speed or throwaway-ness does. Platform is not "App
+plus more effort" — it is App plus a deliberate surface checklist, so read the
+base first and follow it in full rather than blending the two into one plan.
+
+The supporting references belong to whichever mode sends you to them:
+`references/multi-app.md` (a second frontend), `references/theming.md`
+(authoring the theme), `references/ship.md` (deploying, and the Fabric-readiness
+contract).
+
+## Bootstrap before anything else
+
+```sh
+bunx --bun pikku bootstrap
+```
+
+Once, now — not later when you start building. It wires the `#pikku` alias the
+generated code depends on, and on a fresh scaffold **every command that touches
+codegen fails until it has run**, including ones you would reasonably reach for
+while still planning. Those failures look alarming and are nothing but this.
+
+## What holds in every mode
+
+- **The branch and the diff are the contract.** There is no plan JSON. A
+  reviewer sees real, compiled, working code: apply is a merge, reject is a
+  `git branch -D`.
+- **Discover before editing.** `yarn pikku meta context --json` returns
+  functions, wires, middleware, permissions, workflows, `capabilities` and
+  `layout` in one call. Fall back to targeted `meta` commands only for a full
+  schema or a workflow's steps.
+- **`metaLocale` in `pikku.config.json` is the language of authored meta** —
+  every `description`, `title` and step `template` the console renders.
+  Identifiers stay English whatever it says, and the product's own language
+  lives in `messages/*.json`.
+- **`pikku all` is the gate.** Run it after touching functions, wirings or
+  schemas, and treat its criticals as real.
+- **A milestone is planned by a different seat than the one that builds it.**
+  The plan — tables, functions, wires, roles, scopes, screens, scenarios, in
+  passes — is written through `pikku knowledge plan set` by `pikku-architect`,
+  and `pikku knowledge plan progress` measures the build against it from the
+  generated meta. A builder who writes its own plan is grading itself.
+
+## What NOT to do
+
+- **Do not skip ahead in App mode.** Knowledge, then people, then milestones,
+  then one milestone at a time — planned, built, proven by a scenario, and
+  closed against its plan before the next starts. The order is the method.
+- **Do not close a milestone your plan says is unfinished.** Build the missing
+  item, or defer it with a reason through `pikku knowledge plan defer`. Never
+  edit the plan to match what you built, and never drop an item silently.
+- **Do not let a Quick build be mistaken for a real one.** It skips
+  `knowledge/`, milestone planning, design direction and refusal scenarios — say
+  so out loud to the user when you finish, and point at the way out.
+- **Do not introduce a wire of a type whose `capabilities.<type>` is `false`**
+  unless the user asked for it.
+- **Do not hand-edit generated files** — `.pikku/`, `*.gen.*` or the SDK. Fix the
+  source and regenerate.
+- **Do not invent a role.** An invented role becomes invented screens; build only
+  the roles the user named.

package/skills/{pikku-build-app/SKILL.md → pikku-build/references/app.md}

@@ -1,17 +1,3 @@
----
-name: pikku-build-app
-description: >-
-  Build a real product on open-source Pikku using the full Fabric workflow, run locally — knowledge
-  base first, personas and roles, milestones planned then built one at a time, each proven by a
-  scenario, with a design pass. The default build mode, and the one that stays importable into
-  Fabric later. TRIGGER when: the user asked for an app to be built on Pikku and picked "App" (or
-  did not pick), a freshly scaffolded pikku project needs turning into a product, or the user says
-  "build this properly / so someone can pick it up". DO NOT TRIGGER when: the user asked for
-  something quick or throwaway (use pikku-build-quick), wants every platform surface demonstrated
-  (use pikku-build-platform), or is adding one feature to an app that already has its knowledge
-  base and milestones (use pikku-feature).
----
-
 # Build a product on open-source Pikku
 
 You have a scaffolded project with skills installed. This skill owns everything
@@ -272,14 +258,14 @@ definePersonas({
   live with them.
 - **Roles are what a permission check reads, not where it lives.** The check goes
   in the function's `permissions` field (§6), never in the body. Read the
-  `pikku-permissions` skill.
+  `pikku-auth` skill.
 
 `pikku persona list` shows who is declared and `pikku roles audit` reports roles
 the database still holds that code no longer declares — both need §0's bootstrap
 to have run, and both are worth a look once it has.
 
 **One warning about the scaffold's own notes:** `knowledge/index.md` may claim
-the people live in `pikku.config.json`, put there by a `fabric persona` command.
+the people live in `pikku.config.json`, put there by a persona command.
 That is stale. In this template they live in `personas.ts` as above, and
 `pikku.config.json` carries no personas key at all — only `scenarios.emailDomain`.
 Trust the file you can read over the note describing it.
@@ -365,17 +351,45 @@ Number the files (`01-…`, `02-…`) so the order is visible in the tree. Then
 **Show the user the list before building.** This is the last cheap moment to
 reorder — after §6 the migrations are numbered and the order is concrete.
 
+## 5a. The technical plan — one milestone at a time, before you build it
+
+The milestone note says what the app must DO. The **plan** says what has to
+exist for it: the tables, functions, wires, roles, scopes, screens and
+scenarios, split into passes. It is JSON, it lives beside the note, and
+`pikku knowledge plan progress` measures the finished build against it.
+
+**Read `pikku-architect` and follow it.** The plan is the denominator the
+completion check divides by, so a builder who writes their own plan can build a
+fraction, plan only that fraction, and certify itself complete. Fabric answers
+that by giving the plan its own seat; here the defence is the ORDER, and it only
+holds if you keep it: the plan is written against the note in its own turn,
+before any of the code it measures exists, and is never edited afterwards to
+match what you ended up building. An item that will not land is deferred with
+its reason — `plan defer` — not quietly rewritten. Write it before you open a
+migration:
+
+```sh
+pikku knowledge plan schema                        # the only spec there is
+pikku knowledge plan set <milestone> /tmp/plan.json
+pikku knowledge plan show <milestone> --for-build  # what you then build
+```
+
+**Plan one milestone at a time, at the moment you are about to build it** — not
+all of them here. A plan written against a note that later moves is worse than
+no plan, and everything after the current milestone is still allowed to move.
+
 ---
 
 ## PHASE 4 — Build
 
 ## 6. Implement milestones, one at a time
 
-**Per milestone** — set its note to `status: dispatched`, do the six steps,
-set it to `built`. Do not start the next one until §7 is green for this one *and
-§7a shows its functions covered*. A stack of half-milestones cannot be reviewed
-and cannot be handed over, and an uncovered function is a half-milestone whether
-or not the note says `built`.
+**Per milestone** — plan it (§5a), set its note to `status: dispatched`, do the
+six steps, close it out (§6a), set it to `built`. Do not start the next one
+until §6a passes, §7 is green for this one *and §7a shows its functions
+covered*. A stack of half-milestones cannot be reviewed and cannot be handed
+over, and an uncovered function is a half-milestone whether or not the note says
+`built`.
 
 1. **Migration.** SQL in `db/sqlite/` at the project root, numbered on from the
    ones already there. Apply with `bunx --bun pikku db migrate`, which also
@@ -475,6 +489,44 @@ it is worth writing as a browser step on §7's scenario and running
 `pikku scenario run local --spawn --run browser`: same clicks, same assertions,
 in the repo, green or red on every future run.
 
+## 6a. Close the milestone against its plan, not against your memory
+
+```sh
+pikku knowledge plan progress <milestone>
+```
+
+It reads §5a's plan and reconciles it against the generated meta under
+`.pikku/` — the function exists or it does not, the route is wired or it is not,
+the `pikkuScenario` export is there or it is not. Nothing it reports comes from
+what anyone claimed, which is the whole reason it replaced a todo list. It exits
+non-zero while anything in the first pass is missing.
+
+Three things it says, and what each one asks of you:
+
+- **MISSING** — the first pass owes it and the meta cannot see it. Either build
+  it, or, if it genuinely belongs to later work, move it out with a reason on
+  the record:
+
+  ```sh
+  pikku knowledge plan defer <milestone> function:sendReminder \
+    -r "The email service it needs is the next milestone."
+  ```
+
+  **A deferral is capped at two per plan.** Past that, the plan was wrong and the
+  milestone is two milestones — say so to the user rather than deferring again.
+  What you may never do is drop the item silently: the plan is what the next
+  person reads to know what this milestone was for.
+- **PROBLEMS** — something exists but does not do what was planned. A function
+  planned as restricted whose meta says `auth: false`; a `cascade` no migration
+  declares; a browser scenario that opens a page and asserts it is still on it.
+  These are never deferred. Fix the app.
+- **DEFERRED to a later pass** — already accounted for. Reported so it is
+  visible, never blocking.
+
+**Do not set the note to `built` while this exits non-zero**, and do not edit the
+plan to match what you built — `plan set` is the architect's seat, and a builder
+rewriting its own denominator is exactly what the split exists to stop.
+
 ## 7. Prove it — scenarios
 
 A scenario is a user journey run as one of your personas, over the real
@@ -685,7 +737,7 @@ cheaper to honour than to retrofit:
   that needs it
 - `references/theming.md` — authoring the theme (§8a)
 - `references/ship.md` — deploying, and the Fabric-readiness contract (§9)
-- Sibling skills: `pikku-knowledge` (§2), `pikku-permissions` (§3),
-  `pikku-scenario` (§7, §7a), `pikku-deploy-cloudflare` and `pikku-fabric` (§9)
+- Sibling skills: `pikku-knowledge` (§2), `pikku-auth` (§3),
+  `pikku-scenario` (§7, §7a), `pikku-deploy` and `pikku-fabric` (§9)
 - Project conventions written by the template: `AGENTS.md`
-- Doing less than this: `pikku-build-quick`. Doing more: `pikku-build-platform`.
+- Doing less than this: `references/quick.md``. Doing more: `references/platform.md``.

package/skills/{pikku-feature/SKILL.md → pikku-build/references/feature.md}

@@ -1,10 +1,3 @@
----
-name: pikku-feature
-description: 'Drive create-a-feature work inside a Pikku project that already exists: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
-allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
-argument-hint: '<feature description>'
----
-
 # Pikku Create-a-Feature
 
 ## Agent Operating Procedure
@@ -137,7 +130,7 @@ in-app features don't.
   zod schema for type-safe access. Read variables with
   `services.variables.get('NAME')`. Secrets are **not available in functions** —
   read them in `services.ts` with `secrets.getSecret('NAME')` and pass the value
-  into the service the function uses. See the **pikku-config** skill for the full
+  into the service the function uses. See the **pikku-services** skill for the full
   pattern (including OAuth2 credentials). This applies even in `config.ts`.
 
 ### Conventions to copy from neighbours

package/skills/{pikku-build-app → pikku-build}/references/multi-app.md

@@ -8,6 +8,61 @@ leaves `pikkufabric.config.json` pointing at an app nobody has designed yet.
 If the split is "one app with paths", you never need this file — add route
 segments under `/app` and give each audience its own entries in `useNavItems()`.
 
+## Deciding it is two apps, not one
+
+The split you are acting on should already be recorded, but this is the reasoning
+behind it — and the place people get it wrong is the third case at the bottom.
+
+**A group that comes in through its own front door gets its own app.** A role
+*inside* an app is not that: it changes which nav items and which buttons a person
+sees, and lives in `useNavItems()` and the `permissions` on the function, not in a
+route subtree.
+
+**The test is which side of the counter they are on.** Colleagues share one app and
+differ by nav — the mechanic, the person on the counter, the bookkeeper. Someone
+across the counter with an account of their own gets their own — the customer, the
+tenant, the patient. One app is a real answer and often the right one.
+
+**The asymmetry that forces a split is sign-up.** Where staff accounts are created
+*for* people and customers create their own, the two need different sign-up, different
+onboarding and different session shape, and bending one app around both costs more
+than the second app does. Do not collapse two audiences into one app to save a build.
+
+Never invent a person the notes do not name in order to reach two.
+
+### The group that never signs in
+
+Some people use the product with no account at all — ordering from a menu, booking a
+table, opening an invitation. They are not a third case, and **they do not get their
+own frontend**: an app is built around the personas who sign into it. What they get is
+the public route space every app already has.
+
+- **`/app/*` is the signed-in application.** One `beforeLoad` on `/app` bounces a
+  signed-out visitor to the login. There is no per-route exception.
+- **Every other route is public** — `/`, `/menu`, `/book`, `/r/$code`. No gate, no
+  session.
+- **`/` is a landing page and you must write it.** A starter that forwards `/` to
+  `/app` does so only because it ships no homepage. Leave the forward in and the
+  product's front door is a sign-in form: the anonymous visitor arrives at a login it
+  has no account for and never reaches the thing it came for — **while every check
+  still passes**, because everything that looks at the app signs in first. This is the
+  failure this section exists for.
+
+So a screen whose users have no account goes at `/menu`, never `/app/menu`.
+
+### The frontend guard is UX and proves nothing
+
+The bundle is on the origin and the nav is a client-side decision; anyone can read
+both. The security boundary is the `permissions` field on the function — see
+pikku-permissions. Hiding a nav item keeps people out of screens that would confuse
+them; it never protects data. Never let a hidden UI be the only thing between a user
+and someone else's record: if the invoices nav item is hidden but `listAllInvoices`
+has no `permissions`, the app is wide open and the nav is decoration.
+
+Worth a scenario each, because they are two different claims: that a mechanic cannot
+*see* the invoices nav item, and that their call to an invoices RPC is *refused*. The
+second is the one that catches a `permissions` field nobody wired.
+
 ## The clone
 
 ```bash
@@ -102,7 +157,7 @@ rewritten to the pikku dev server).
   the permission check exists. The refusal scenario is the evidence.
 - **In production on two subdomains**, the session cookie needs a parent domain
   (`.example.com`) or each app gets its own login. Decide which, set it per the
-  `pikku-better-auth` skill, and record it in `knowledge/decisions/security/`.
+  `pikku-auth` skill, and record it in `knowledge/decisions/security/`.
 - **Never hardcode a host or port.** The API base resolves to same-origin `/api`.
 
 ## Building the second app's screens

package/skills/{pikku-build-platform/SKILL.md → pikku-build/references/platform.md}

@@ -1,25 +1,12 @@
----
-name: pikku-build-platform
-description: >-
-  Build an app that exercises every Pikku surface — workflows, schedules, queues, an AI agent,
-  realtime, MCP, multiple locales, contract versioning and scenario coverage — on top of the full
-  pikku-build-app workflow. For proving what the platform does, not for shipping the smallest
-  thing that works. TRIGGER when: the user picked "Platform", asked for a showcase or reference
-  app, or asked to demonstrate what Pikku can do. DO NOT TRIGGER when: the user wants a product
-  built (use pikku-build-app), something quick (use pikku-build-quick), or one specific surface
-  wired into an existing app — a single workflow, cron job or agent (use that surface's own skill,
-  e.g. pikku-workflow, pikku-schedule, pikku-agent).
----
-
 # Build a platform showcase on Pikku
 
-**This skill is a delta. `pikku-build-app` is the base — read it and follow it in
+**This skill is a delta. `references/app.md` is the base — read it and follow it in
 full.** Everything there applies: knowledge base first, personas and roles,
 milestones planned then built one at a time, scenarios, design pass, deploy
 gates, Fabric-readiness. This file adds the surfaces that turn an app into a
 demonstration of the platform, and says where each one slots into that workflow.
 
-Read `pikku-build-app` now, then come back. Do not blend the two into one plan —
+Read `references/app.md` now, then come back. Do not blend the two into one plan —
 the phases below hang off its phases by number.
 
 ## What "platform" means here
@@ -32,7 +19,7 @@ proves it.** A cron job that logs "tick" is not a schedule — it is a comment.
 Budget the extra surfaces at one milestone each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
 
-## Choosing surfaces — during `pikku-build-app` §5 (planning)
+## Choosing surfaces — during `references/app.md` §5 (planning)
 
 When you plan milestones, each surface below becomes its own milestone note in
 `knowledge/milestones/`, ordered after the spine it depends on.
@@ -85,11 +72,11 @@ on a human or a timer and must survive a restart.
   gap in the middle? If every operation completes in one request, you do not need
   workflows and forcing one is noise.
 - **Prove it:** a scenario that starts the workflow, advances it as a second
-  persona, and asserts the end state. `pikku-workflows-client` covers driving it
+  persona, and asserts the end state. `pikku-react` covers driving it
   from the UI.
 - Three workflows ship with the template. Read them before writing yours.
 
-### Schedules — `pikku-schedule`
+### Schedules — `pikku-wiring`
 
 Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
 
@@ -99,7 +86,7 @@ Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
 - **Prove it:** invoke the scheduled function directly in a scenario and assert
   its effect. Do not test by waiting.
 
-### Queues — `pikku-queue`
+### Queues — `pikku-wiring`
 
 Work that must happen but not now, and may retry: email fan-out, image
 processing, third-party calls that fail.
@@ -108,7 +95,7 @@ processing, third-party calls that fail.
   fails in ways worth retrying.
 - **Prove it:** enqueue in one scenario step, assert the effect in a `then`.
 
-### An AI agent — `pikku-agent`, `pikku-ai-vercel`
+### An AI agent — `pikku-agent`
 
 The template ships agent wiring and `@ai-sdk/openai`. An agent that answers
 questions over the app's own data is the showcase; a general chatbot is not.
@@ -124,7 +111,7 @@ questions over the app's own data is the showcase; a general chatbot is not.
   matching `defineSecret`, never `process.env`, or deploy has nothing to
   provision (PKU951).
 
-### Realtime and events — `pikku-realtime`, `pikku-websocket`
+### Realtime and events — `pikku-wiring`
 
 `pikku enable events` gives a realtime channel plus an SSE stream, and the
 generated typed client.
@@ -134,20 +121,20 @@ generated typed client.
 - **Prove it:** a browser scenario is the only honest proof — assert the second
   persona's screen changed without a reload.
 
-### MCP — `pikku-mcp`
+### MCP — `pikku-wiring`
 
 Exposes functions as Model Context Protocol tools, so an outside agent can drive
 the app. Cheap once functions exist, and a genuine differentiator to show.
 
-### Triggers and webhooks — `pikku-trigger`, `pikku enable webhook`
+### Triggers and webhooks — `pikku-wiring`, `pikku enable webhook`
 
 Inbound triggers and outgoing webhook delivery. This is where `wireHTTP` is
 correct rather than a smell: a third-party caller needs a real REST shape.
 
-### Locales — `pikku-i18n`, `pikku-paraglide`
+### Locales — `pikku-i18n`
 
-`pikku-build-app` already requires every string to be a key. **Here, ship three
-locales, and make one of them RTL** (`pikku-rtl`). Two LTR locales prove the
+`references/app.md` already requires every string to be a key. **Here, ship three
+locales, and make one of them RTL** (`pikku-i18n`). Two LTR locales prove the
 plumbing; an RTL one proves the layout, and it will find real bugs — mirrored
 icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
 
@@ -159,7 +146,7 @@ every added locale is cloned from, so three locales is `locales: ["en", …]` an
 never a repointed base. Shipping locales is also not a reason for anything in
 the code to stop being English: identifiers are English in every project, and
 the language of `description`/`title`/`template` is `metaLocale` in
-`pikku.config.json`. See `pikku-build-app` §1a.
+`pikku.config.json`. See `references/app.md` §1a.
 
 ### Emails — `pikku-emails`
 
@@ -168,7 +155,7 @@ localised like every other string. The base workflow asks for one; **a showcase
 sends three** — a welcome, a transactional confirmation, and one sent from a
 schedule or queue rather than a request, because that is the interesting path.
 
-### Contract versioning — `pikku-versioning`
+### Contract versioning — `pikku-meta`
 
 ```sh
 bunx --bun pikku versions init
@@ -186,7 +173,7 @@ the domain has a piece that genuinely belongs to no single app.
 
 ## Coverage — where the bar is higher than the base workflow
 
-`pikku-build-app` §7a already has the mechanics and the per-milestone habit:
+`references/app.md` §7a already has the mechanics and the per-milestone habit:
 run the server instrumented, run the scenarios against it, read
 `coverage/scenario-coverage.json`, and triage every gap as a missing scenario, a
 function that should not exist, or a documented deferral. Do all of that here.
@@ -205,7 +192,7 @@ Two things change in a showcase:
 
 ## The full gate
 
-Everything in `pikku-build-app` §9, plus the checks a showcase should be able to
+Everything in `references/app.md` §9, plus the checks a showcase should be able to
 survive:
 
 ```sh
@@ -227,7 +214,7 @@ bunx --bun pikku scenario run local --spawn --run browser
 
 ## Deploy
 
-`pikku-build-app` §9 covers the open-source paths (`--provider standalone`,
+`references/app.md` §9 covers the open-source paths (`--provider standalone`,
 `cloudflare`, `aws`). One thing specific to this mode: **the extra surfaces are
 extra deploy units.** Workflow workers, queue workers, schedules and the events
 channel each appear in `pikku deploy plan` as their own entries. Read the plan
@@ -236,10 +223,8 @@ built.
 
 ## Reference
 
-- Base workflow: `pikku-build-app` — read it first, follow it in full
-- Per-surface skills: `pikku-workflow`, `pikku-schedule`,
-  `pikku-queue`, `pikku-agent`, `pikku-ai-vercel`, `pikku-realtime`,
-  `pikku-websocket`, `pikku-mcp`, `pikku-trigger`, `pikku-i18n`, `pikku-rtl`,
-  `pikku-emails`, `pikku-versioning`, `pikku-addon`, `pikku-security`,
-  `pikku-audit`
+- Base workflow: `references/app.md` — read it first, follow it in full
+- Per-surface skills: `pikku-workflow`, `pikku-wiring`, `pikku-agent`,
+  `pikku-i18n`, `pikku-emails`,
+  `pikku-meta`, `pikku-addon`, `pikku-auth`, `pikku-services`
 - Every feature, end to end: https://pikkufabric.com/llm-all-features.txt

package/skills/{pikku-template-clone/SKILL.md → pikku-build/references/post-clone.md}

@@ -1,9 +1,3 @@
----
-name: pikku-template-clone
-description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `npm create pikku`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
-allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
----
-
 # Pikku Template Post-Clone Cleanup
 
 ## Agent Operating Procedure

package/skills/{pikku-build-quick/SKILL.md → pikku-build/references/quick.md}

@@ -1,19 +1,3 @@
----
-name: pikku-build-quick
-description: >-
-  Build a working app on open-source Pikku fast — scaffold to running screens, skipping the
-  knowledge base and the milestone ladder. For spikes, throwaway demos, and ideas nobody has
-  committed to yet. TRIGGER when: the user asked for something quick, a prototype, a spike, a
-  demo of an idea, or "just get it running", or picked "Quick" from the build-mode question. DO
-  NOT TRIGGER when: the request is an unqualified "build me an X on Pikku" with no signal of
-  speed or throwaway-ness — App is the default and small or toy-sounding apps do not change that
-  (use pikku-build-app); the user wants a real product someone else will pick up (use
-  pikku-build-app); the user wants a demo of Pikku itself — one that shows off surfaces like
-  workflows, queues, realtime or i18n (use pikku-build-platform); or the user is adding a feature
-  to an app that already exists rather than building one from a fresh scaffold (use
-  pikku-feature).
----
-
 # Build an app on Pikku, fast
 
 You have a scaffolded project with skills installed. Get it to working, seeded,
@@ -58,7 +42,7 @@ Identifiers are English in every project, whatever the product's market;
 `template`, which the Console renders) stays `en` unless the user already told
 you otherwise. If the request says the app's UI is not English, that is the
 message catalogue only: add the locale and set `defaultLocale`, and leave
-`baseLocale` at `en`. `pikku-build-app` §1a has the three axes in full; getting
+`baseLocale` at `en`. `references/app.md` §1a has the three axes in full; getting
 them confused is how a project ends up unable to add a second language.
 
 ## 2. Personas — 60 seconds, not optional
@@ -191,7 +175,7 @@ taller than the viewport. It is the most likely width your demo gets opened at.
 If you have five spare minutes, `npx impeccable install` (Node 22.18+) scores
 each screen against interaction heuristics and names what is wrong. Feed it
 screenshots, not source. It will polish the default look; it will not give the
-app a look — that is `pikku-build-app` §8a.
+app a look — that is `references/app.md` §8a.
 
 ## 5. One smoke scenario
 
@@ -235,7 +219,7 @@ that this is a quick build — no knowledge base, no milestones, no design pass,
 access control clicked-through rather than proven.
 
 **Upgrading to a real build is additive, not a rewrite.** If they want it, switch
-to `pikku-build-app` and do this, in order:
+to `references/app.md` and do this, in order:
 
 1. Write `knowledge/` for what already exists — `entities/` for what you built,
    `decisions/` for what you chose silently, `questions/` for what you guessed
@@ -244,7 +228,7 @@ to `pikku-build-app` and do this, in order:
    its gherkin block.
 3. Write the refusal scenarios — the ones proving one persona cannot reach
    another's rows. This is the gap that matters most.
-4. Then pick up `pikku-build-app` at its §4 (apps) or §5 (milestones) for
+4. Then pick up `references/app.md` at its §4 (apps) or §5 (milestones) for
    anything new.
 
 Nothing built here has to be thrown away to do that — which is the whole reason

package/skills/{pikku-build-app → pikku-build}/references/ship.md

@@ -16,7 +16,7 @@ bunx --bun pikku deploy apply --provider standalone --runtime bun
 bundles the project into a single unit and emits either a `bundle.js` you run
 with Node, or a self-contained executable compiled with `bun build --compile`.
 `cloudflare` (the default) and `aws` are the other providers — read the
-`pikku-deploy-cloudflare` skill before using it, as it ships the handler
+`pikku-deploy` skill before using it, as it ships the handler
 factories the deploy codegen expects, and hand-rolling an `ExportedHandler` is
 how a worker deploy fails at runtime instead of at build.
 
@@ -74,13 +74,19 @@ Everything above is open source. This is the contract that keeps
 - **`pikkufabric.config.json` describes reality.** Every app has an entry with
   the right `cwd`, `port`, `kind` and `dev.command`; exactly one is `primary`;
   `serves` and `personas` name real personas from the personas section. Leave `projectId` as
-  `__PROJECT_ID__` — that placeholder means "unlinked", and `fabric init` writes
-  the real one. Do not invent a value to make it look configured.
+  `__PROJECT_ID__` — that placeholder means "unlinked", and linking the project
+  writes the real one. Do not invent a value to make it look configured.
 - **One `definePersonas` call**, every persona reachable through exactly one
   frontend. Fabric materialises these as its virtual users; a persona nobody
   serves imports as a person with no way in.
 - **`knowledge/` passes `validate`, with every milestone at `built`.** This is
   the part Fabric itself reads and continues from.
+- **Every `built` milestone passes `pikku knowledge plan progress`.** A note that
+  says `built` is a claim; the plan reconciled against the generated meta is the
+  check. Anything the first pass still owes is either built now or deferred with
+  its reason on the record; anything the check calls a problem — something that
+  exists and does not do what was planned — is fixed, whatever pass it came from,
+  because deferring it defers a hole rather than the work.
 - **Every milestone has a passing scenario**, including its refusals.
 - **Permissions live in the `permissions` field**, not in function bodies and not
   in the frontends. A check hidden in a component does not survive a new client.