@pikku/skills 0.12.22 → 0.12.25

package/skills/pikku-auth/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: pikku-auth
+description: >-
+  Use for anything about identity in a Pikku app — authenticating a caller (login, logout,
+  sessions, cookies, bearer tokens, API keys, JWT, OAuth/social providers, MFA, Better Auth) and
+  authorizing one (pikkuPermission, pikkuAuth, scopes, defineScope, global permissions). Covers
+  which of the two a problem actually is, the built-in auth strategies, machine-to-machine auth
+  and `pikku login`, and the JWT service. TRIGGER when: user asks about login, logout, session,
+  cookie auth, bearer tokens, API keys, JWT, Better Auth, social providers, restricting who may
+  call a function, resource ownership, roles, scopes, or hits MissingScopeError or
+  InvalidSessionError. DO NOT TRIGGER when: user asks about middleware mechanics with no identity
+  involved (use pikku-middleware) or about secrets and env vars (use pikku-services).
+installGroups: [core]
+---
+
+# Pikku Auth
+
+Signatures and option keys come from `pikku doc` — run `pikku doc --ai` for the
+installed surface. This skill is the part the compiler cannot tell you: which of
+the two problems you actually have, and what goes wrong in each.
+
+## First: authentication or authorization?
+
+They are separate gates, and confusing them is the most common mistake in a
+Pikku app.
+
+**Authentication** answers _who is calling_. It happens in middleware, before the
+function runs, and ends in a call to `setSession`.
+
+**Authorization** answers _may this caller do this_. It is declared on the
+function — `scopes` and `permissions` — never checked inside its body.
+
+A `permissions` entry that verifies a bearer token and returns `true` is
+authentication wearing an authorization hat: it leaves the function sessionless,
+so every body still has to work out who called it. Resolve the credential in
+middleware instead.
+
+## Pick the reference
+
+| You are… | Read |
+| --- | --- |
+| Restricting who may call a function — ownership, roles, scopes | `references/permissions.md` |
+| Reading or setting the session, or wiring `authBearer`/`authCookie`/`authAPIKey` | `references/sessions.md` |
+| Standing up user sign-in — OAuth, email+password, MFA, organizations | `references/better-auth.md` |
+| Authenticating a CLI, agent, sandbox or worker — API keys, `pikku login` | `references/machine-auth.md` |
+| Configuring the JWT service, or rotating a signing secret | `references/jose.md` |
+
+## All authentication goes through `@pikku/better-auth`
+
+There is no second auth story. A hand-rolled user table, a bespoke password
+hash, a custom OAuth dance — all of them are the wrong answer, and the console
+will not work against them. `references/better-auth.md` has the setup; the
+built-in strategies in `references/sessions.md` are how a resolved credential
+becomes a Pikku session, not a replacement for it.
+
+## The three gates
+
+Authorization is three independent gates, all of which must pass, in this order:
+
+1. **Scopes** (`scopes`) — AND'd, checked before input validation, fails closed.
+2. **Global permissions** (`addGlobalPermission`) — AND'd, an app-wide baseline.
+3. **The function's own `permissions`** — OR'd groups of AND'd entries.
+
+They are independent: a broad global gate can never satisfy a function's own
+requirement, and a scope can only ever narrow access, never grant it.
+
+## What NOT to do
+
+- **Do not check authorization inside `func`.** The `permissions` field is
+  visible to the inspector; a check in the body is invisible to `pikku info
+  permissions` and to an audit. The one sanctioned exception is
+  `permissionsInBody`, which is purely declarative — see
+  `references/permissions.md`.
+- **Do not write an "is signed in" permission.** `auth: true` (the default on
+  `pikkuFunc`) already requires the session. A checker returning `!!session`
+  gates nothing.
+- **Do not put `scopes` on a `pikkuSessionlessFunc`.** Scopes fail closed and an
+  anonymous caller holds none, so it would reject every caller it exists to
+  serve. Gate those with `permissions`, which receive an optional session.
+- **Do not expect the built-in strategies to authenticate a non-HTTP caller.**
+  `authBearer`, `authCookie` and `authAPIKey` all step aside when there is no
+  HTTP request — a queue job, a scheduled task or a channel message needs its
+  session set another way.
+- **Do not share one header between the human and machine paths.**
+  `Authorization: Bearer` is the human session; `x-api-key` is the machine key.
+  Merging them reintroduces the ambiguity the split exists to remove.
+- **Do not reach for wire-, tag- or route-level permissions.** They were removed
+  in #972. Permissions live on the function, plus the optional global gate; tags
+  are organizational only.

package/skills/{pikku-better-auth/SKILL.md → pikku-auth/references/better-auth.md}

@@ -1,18 +1,3 @@
----
-name: pikku-better-auth
-description: >-
-  Use when integrating Better Auth with a Pikku app. Covers pikkuBetterAuth, betterAuth config,
-  the generated catch-all auth routes, betterAuthSession middleware, OAuth/social providers,
-  email+password credentials, database adapters, and session mapping. TRIGGER when: code uses
-  pikkuBetterAuth, betterAuth, betterAuthSession, createAuthHandler, user asks about Better Auth,
-  OAuth/social providers, MFA, organizations, login/logout, or @pikku/better-auth. TRIGGER when: user asks
-  about the actor plugin, /sign-in/actor, signing in as a scenario persona, or SCENARIO_ACTOR_SECRET. TRIGGER when:
-  user asks about ANY form of authentication, login, logout, sessions, or user identity — always
-  answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security)
-  or custom session services (use pikku-services).
-installGroups: [fabric]
----
-
 # Pikku Better Auth Integration
 
 ## ⚠️ MANDATORY RULE — READ FIRST
@@ -30,17 +15,6 @@ The only acceptable auth implementation in a Pikku app is the one described in t
 
 ---
 
-## 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`, or build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated.
-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. Do not edit generated files.
-
-`@pikku/better-auth` provides [Better Auth](https://better-auth.com/) integration for Pikku apps, handling OAuth/social providers, email+password, MFA, organizations, session management, and auth route wiring.
 
 ## Installation
 
@@ -61,7 +35,7 @@ You do NOT hand-write routes, the session middleware, or the secret wiring — `
 
 ### The console requires Better Auth
 
-The Pikku console (`@pikku/addon-console`, enabled via `scaffold.console` in `pikku.config.json`) is an admin surface: **every console RPC now requires an authenticated session** (the functions are `pikkuFunc`; unauthenticated calls return `403`). So `scaffold.console` alone is **no longer the minimum** — you also need an auth strategy, and Better Auth is the supported one. `pikku all` **throws** if `scaffold.console` is set but no `pikkuBetterAuth(...)` is found in the project. Baseline is "must be logged in"; finer policy (admin-only, org scoping) is layered host-side via tag/HTTP middleware. See `pikku-deps` for the console's Security screen.
+The Pikku console (`@pikku/addon-console`, enabled via `scaffold.console` in `pikku.config.json`) is an admin surface: **every console RPC now requires an authenticated session** (the functions are `pikkuFunc`; unauthenticated calls return `403`). So `scaffold.console` alone is **no longer the minimum** — you also need an auth strategy, and Better Auth is the supported one. `pikku all` **throws** if `scaffold.console` is set but no `pikkuBetterAuth(...)` is found in the project. Baseline is "must be logged in"; finer policy (admin-only, org scoping) is layered host-side via tag/HTTP middleware. See `pikku-meta` for the console's Security screen.
 
 ---
 

package/skills/{pikku-jose/SKILL.md → pikku-auth/references/jose.md}

@@ -1,27 +1,5 @@
----
-name: pikku-jose
-description: >-
-  Use when setting up JWT authentication with the jose library in a Pikku app. Covers
-  JoseJWTService constructor, secret rotation, token encoding/decoding/verification. TRIGGER when:
-  code uses JoseJWTService, user asks about JWT setup, token signing, token verification, or
-  @pikku/jose. DO NOT TRIGGER when: user asks about session middleware (use pikku-security) or
-  general service setup (use pikku-services).
-installGroups: [fabric]
----
-
 # Pikku Jose (JWT Service)
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `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/jose` provides JWT signing, verification, and decoding using the [jose](https://github.com/panva/jose) library. Implements the `JWTService` interface from `@pikku/core`.
 
 ## Installation
 
@@ -86,7 +64,7 @@ await jwt.init()
 A signing key is a secret, so it comes from the secrets service rather than
 `process.env` — and because `getSecrets` is a function called on demand, reading
 it there (not once at construction) is what makes the re-init-on-unknown-kid path
-above actually see a rotated key. See `pikku-config`.
+above actually see a rotated key. See `pikku-services`.
 
 ### Secret Rotation
 

package/skills/{pikku-machine-auth/SKILL.md → pikku-auth/references/machine-auth.md}

@@ -1,17 +1,3 @@
----
-name: pikku-machine-auth
-description: >-
-  Use when authenticating a CLI/agent/service against a Pikku server, adding machine-to-machine
-  (M2M) auth, issuing scoped API keys for sandboxes/agents/workers, or wiring better-auth sessions
-  into Pikku middleware. Covers `pikku login` (device-authorization), the better-auth API Key
-  plugin, machine identities, and `betterAuthSession` with the api-key branch. TRIGGER when: user
-  asks about CLI login, `pikku login`, machine agents, service-to-service auth, API keys, client
-  credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO
-  NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the
-  app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).
-installGroups: [fabric]
----
-
 # Pikku Machine Auth
 
 Unified authentication for humans **and** machines against a Pikku + better-auth
@@ -29,15 +15,6 @@ Both resolve to a Pikku `UserSession` through one middleware:
 > better-auth's oidc-provider. The API Key plugin gives the same capability (a
 > baked secret a service presents for scoped access), not the wire protocol.
 
-## Agent Operating Procedure
-
-1. Discover before editing — inspect the app's `betterAuth({ plugins: [...] })`
-   config and existing middleware wiring before adding anything.
-2. Server changes go in the auth factory + a middleware wiring file; never put
-   auth checks in a function body (use `permissions`).
-3. The API Key plugin contributes an `apikey` table — add the matching SQL
-   migration and regenerate DB types before relying on it.
-4. Validate with the narrowest command, then `pikku all`.
 
 ## Human path — `pikku login`
 

package/skills/{pikku-permissions/SKILL.md → pikku-auth/references/permissions.md}

@@ -1,21 +1,8 @@
----
-name: pikku-permissions
-description: >-
-  Use when adding authorization checks to Pikku functions — pikkuPermission, pikkuAuth, scopes and
-  defineScope, per-function permissions, global permissions, or understanding the scope/OR/AND
-  gating logic. TRIGGER when: user wants to restrict who can call a function, check resource
-  ownership, add role-based or scope-based access, declares or grants scopes, hits
-  MissingScopeError, or asks where permission checks belong. DO NOT TRIGGER when: user asks about
-  middleware or request interception (use pikku-middleware), authentication strategies (use
-  pikku-security), or session management.
-installGroups: [core]
----
-
 # Pikku Permissions
 
 ## ⛔ FIRST: is the caller a machine with a token? ⛔
 
-**Then this is NOT a permissions problem.** Resolve the token in `addHTTPMiddleware('*')` middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with `scopes`. A `permissions` check that verifies a bearer token and returns `true` is authentication wearing an authorization hat — and it leaves the function sessionless, so every body still has to work out who called it. See the machine-auth section of `pikku-middleware`. The only exception is a bootstrap endpoint whose caller has no identity yet (a shared-secret registration, a login): that one is sessionless and declares its gate here.
+**Then this is NOT a permissions problem.** Resolve the token in `addHTTPMiddleware('*')` middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with `scopes`. A `permissions` check that verifies a bearer token and returns `true` is authentication wearing an authorization hat — and it leaves the function sessionless, so every body still has to work out who called it. See `references/machine-auth.md`. The only exception is a bootstrap endpoint whose caller has no identity yet (a shared-secret registration, a login): that one is sessionless and declares its gate here.
 
 ## The Rule
 
@@ -43,12 +30,6 @@ export const deleteBook = pikkuFunc({
 })
 ```
 
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info permissions --verbose` and `pikku info functions --verbose` to understand what permissions are already defined and applied.
-2. Define permission checkers in a `src/permissions.ts` or domain-specific `src/lib/*-permissions.ts` file.
-3. Apply them via the `permissions` field on the function. For an app-wide baseline that every function must additionally satisfy, use `addGlobalPermission`.
-4. Validate: run `pikku all --tsc` to confirm permission checker signatures are correct.
 
 ## Permission Factories
 

package/skills/{pikku-security/SKILL.md → pikku-auth/references/sessions.md}

@@ -1,25 +1,5 @@
----
-name: pikku-security
-description: >-
-  Use when adding authentication or session management to a Pikku app — pikkuAuth, session
-  lifecycle (setSession/clearSession), built-in auth strategies (authBearer, authCookie,
-  authAPIKey), or JWT setup. TRIGGER when: user asks about login, logout, session, bearer tokens,
-  cookie auth, API keys, or JWT. DO NOT TRIGGER when: user asks about middleware (use
-  pikku-middleware), permissions/authorization checks (use pikku-permissions), or secrets/env vars
-  (use pikku-config).
-installGroups: [core]
----
-
 # Pikku Security (Authentication & Sessions)
 
-## Agent Operating Procedure
-
-1. Discover before editing. Run `pikku info middleware --verbose` and `pikku info functions --verbose` to understand existing auth setup.
-2. Auth strategies live in wirings files — do not put `addHTTPMiddleware` calls inside function bodies.
-3. Validate with `pikku all --tsc` after changes — it regenerates and then type-checks in one pass, and fails on type errors. Use `--tsc-summary` for a compact one-line-per-error report.
-
-For **middleware** (including tag middleware and service-to-service bearer auth) see `pikku-middleware`.
-For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see `pikku-permissions`.
 
 ## Session Management
 

package/skills/pikku-build/SKILL.md

@@ -0,0 +1,87 @@
+---
+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]'
+---
+
+# 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,7 +258,7 @@ 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
@@ -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

@@ -102,7 +102,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