@pikku/skills 0.12.21 → 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.
 
 ---
 
@@ -516,9 +490,9 @@ an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
 in as the personas the deployment provisioned when it started and refuses
 everything else (`No actor account exists for that address`), so holding the
 secret on such a stage does not let anyone invent identities. Those rows are
-written by `provisionPersonas` from `@pikku/better-auth`, called in the server's
-own lifecycle, so provisioning needs no actor secret and works on a stage whose
-endpoint is shut.
+written by the fabric plugin when an operator asks to act as an address the
+stage has no account for, so provisioning needs no actor secret and works on a
+stage whose endpoint is shut.
 
 **`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
 persona.** Provisioning grants declared roles to actor accounts, so an
@@ -544,30 +518,46 @@ This is the endpoint `pikku scenario` signs its actors in through, and the one
 the frontend dev switcher posts to — see `pikku-scenario` for declaring the
 actors and `pikku-react` for `useDevActors()`.
 
-### Provisioning personas (`provisionPersonas`)
+### Provisioning personas
 
-Anywhere but `pikku dev`, the accounts have to exist before anyone signs in.
-The deployment creates them itself, from its own lifecycle:
+Anywhere but `pikku dev`, the accounts have to exist before anyone signs in. The
+stage creates them itself, from the personas you hand `pikkuFabric`:
 
 ```ts
-import { provisionPersonas } from '@pikku/better-auth'
+import { pikkuFabric } from '@pikku/better-auth'
 import {
   personaConfigs,
   personaEnvironments,
 } from '#pikku/pikku-personas.gen.js'
 
-await provisionPersonas(singletonServices, {
-  personas: personaConfigs,
-  environments: personaEnvironments,
+pikkuFabric({
+  publicKey,
+  audience,
+  scopeService,
+  personas: {
+    personas: personaConfigs,
+    environments: personaEnvironments,
+  },
 })
 ```
 
-It runs where the database already is, which is the point: the CLI has no
-connection to a deployed environment's database — it resolves one from the local
-project config — so a `pikku persona sync staging` that wrote rows would write
-them to whatever database the checkout happened to point at. `pikku persona sync
-<environment>` still exists, and reports who that environment will provision and
-why anyone was skipped, which is what you run _before_ the deploy.
+There is nothing else to call and nothing to schedule. The plugin's operator
+endpoint resolves the address the caller wants to act as; a miss provisions the
+declaration and looks again. On a stage that already holds the persona that is
+one query, and the pass only runs when there is genuinely something absent to
+create.
+
+**Do not reach for `pikkuServerLifecycle`'s `afterStart` for this.** That hook is
+invoked by `pikku serve` and `pikku dev` and by nothing else — no deploy runtime
+calls it — so a stage on Workers or a serverless target that provisioned from
+`afterStart` provisioned nothing, and every persona signed in holding no roles.
+
+Provisioning runs where the database already is, which is the point: the CLI has
+no connection to a deployed environment's database — it resolves one from the
+local project config — so a `pikku persona sync staging` that wrote rows would
+write them to whatever database the checkout happened to point at. `pikku persona
+sync <environment>` still exists, and reports who that environment will provision
+and why anyone was skipped, which is what you run _before_ the deploy.
 
 It creates missing accounts as `actor: true`, applies the roles each persona
 declares, and is additive — it never revokes. `PIKKU_ENV` (or an explicit
@@ -583,10 +573,15 @@ open. By default provisioning warns about those accounts and changes nothing.
 `orphans: 'ban'` shuts them:
 
 ```ts
-await provisionPersonas(singletonServices, {
-  personas: personaConfigs,
-  environments: personaEnvironments,
-  orphans: 'ban',
+pikkuFabric({
+  publicKey,
+  audience,
+  scopeService,
+  personas: {
+    personas: personaConfigs,
+    environments: personaEnvironments,
+    orphans: 'ban',
+  },
 })
 ```
 

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
 
@@ -58,7 +39,7 @@ Use for checks that read the session but need no request data — and that asser
 something **beyond** merely having a session (a flag, a tier, a claim).
 
 ```typescript
-import { pikkuAuth } from '#pikku/function'
+import { pikkuAuth } from '#pikku/auth'
 
 // Good: a real gate on the session's contents, not just its existence.
 export const isVerified = pikkuAuth(
@@ -89,7 +70,7 @@ A permission answers "_may this user do this?_" (role, ownership, tier) — neve
 Use when authorization depends on the actual request data (e.g., resource ownership).
 
 ```typescript
-import { pikkuPermission } from '#pikku/function'
+import { pikkuPermission } from '#pikku/auth'
 
 export const isBookOwner = pikkuPermission(
   async ({ db }, { bookId }, { session }) => {
@@ -139,7 +120,7 @@ export const deleteBook = pikkuFunc({
 A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever _narrow_ access — it never grants access a function's own `permissions` would deny.
 
 ```typescript
-import { addGlobalPermission } from '#pikku/function'
+import { addGlobalPermission } from '#pikku/auth'
 
 addGlobalPermission([isEmployee]) // every function now also requires an employee session
 ```
@@ -248,7 +229,7 @@ declared, inspectable, and reusable.
 
 ```typescript
 // src/permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/function'
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
 
 export const isVerified = pikkuAuth(
   async (_services, session) => !!session?.emailVerified

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
 
@@ -62,7 +42,7 @@ Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '#pikku/middleware'
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
@@ -118,7 +98,7 @@ response.
 
 ```typescript
 // permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/function'
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
 
 export const isAuthenticated = pikkuAuth(
   async (_services, session) => !!session
@@ -129,7 +109,7 @@ export const isVerified = pikkuAuth(
 
 // wirings/auth.wiring.ts
 import { authCookie } from '#pikku/middleware'
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 
 addHTTPMiddleware('*', [
   authCookie({

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.