@pikku/skills 0.12.57 → 0.12.59

package/skills/pikku-build/references/app.md

@@ -1,45 +1,24 @@
 # Build a product on open-source Pikku
 
-## Contents
-
-- Agent Operating Procedure
-- 0. Bootstrap, before anything else
-- 1. One more round of questions — then stop asking
-- 1a. Three languages, and you must not collapse them
-- PHASE 1 — What the app is
-- 2. Write the knowledge graph — before any code
-- PHASE 2 — Who it is for, and what it is made of
-- 3. Declare the people — virtual users and roles
-- 4. Declare the apps — one API, several frontends
-- PHASE 3 — The plan
-- 5. File the work as changes
-- 5a. The technical plan — per changeset, before you build it
-- PHASE 4 — Build
-- 6. Build each changeset
-- 6a. Close the changeset against its plan, not against your memory
-- 7. Prove it — scenarios
-- 8. Make it look like someone designed it
-- 9. Ship it, and stay deploy-ready
-- Reference
-
 You have a scaffolded project with skills installed. This skill owns everything
 from here: no hosted account, no card, no hosted build — while keeping the
 project shaped so a hosting platform can adopt it later with zero rework.
 
-**Four phases, and you do not skip ahead:**
+**Five phases, and you do not skip ahead.** This file is the index: read it,
+then open each phase file when you reach that phase, not before. Section
+numbers (§0-§9) are stable and are cited elsewhere as "app §N".
 
-1. Write the knowledge graph — what the app IS, before any code
-2. Declare the people and the apps — virtual users, roles, frontends
-3. File the work as changes — grouped into changesets, in dependency order
-4. Build them one changeset at a time — each proven by a scenario before it merges
+| Phase                                                          | Sections                                                            | Read                                    |
+| -------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------- |
+| 1. What the app is — write the knowledge graph before any code | §0 bootstrap, §1 questions, §1a three languages, §2 knowledge graph | `references/phase-1-what-it-is.md`      |
+| 2. Who it is for — virtual users, roles, frontends             | §3 people, §4 apps                                                  | `references/phase-2-people-and-apps.md` |
+| 3. The plan — file the work as changes, in dependency order    | §5 changes, §5a technical plan                                      | `references/phase-3-plan.md`            |
+| 4. Build, one changeset at a time                              | §6 build, §6a close against the plan, §6b feed back                 | `references/phase-4-build.md`           |
+| 5. Prove it, make it look designed, ship it                    | §7 scenarios, §7a coverage, §8 look and theme (§8a, §8b), §9 ship   | `references/phase-5-prove-and-ship.md`  |
 
-The sections below follow those phases in order, and are meant to be worked
-through rather than searched: §0 bootstrap, §1-§1a the last questions and the
-three languages, §2 the knowledge graph, §3-§4 virtual users and apps, §5-§5a the
-changes and each changeset's technical plan, §6-§6a building and closing one,
-§7-§7a proving it, §8 design, §9 ship. Four of them have their own reference —
-scenarios, design, multi-app and ship, each listed in SKILL.md — to read at the
-point you need it.
+Work through them in order rather than searching. Each changeset repeats §5a,
+§6-§7a; §8 and §9 run when the queue is empty (design is read before the first
+screen, though — see below).
 
 ## Agent Operating Procedure
 
@@ -54,800 +33,20 @@ point you need it.
    wirings, schemas or generated clients may have changed.
 4. If validation fails, fix the source cause and rerun. Do not paper over
    generated errors by editing generated files.
-5. Report at the person's level (SKILL.md, "Who you are talking to"): a console
-   link for everything the console can show, and no code unless they are a
-   developer.
-
-## 0. Bootstrap, before anything else
-
-```sh
-bunx --bun pikku bootstrap
-```
-
-One command, run once, now — not later when you start building. It wires the
-`#pikku` import alias the generated code depends on. On a fresh scaffold `.pikku/`
-is empty, so **every command that touches codegen fails until this has run** —
-including ones you would reasonably reach for while still planning, like
-`pikku virtual-user list`. Those failures look alarming (`Cannot find module
-'#pikku/workflow/pikku-workflow-types.gen.js'`, `Schema generation failed for 16
-schemas`) and they are nothing but this missing step.
-
-`pikku knowledge index` and `knowledge validate` work without it — which is why
-the planning phases below are safe either way.
-
-## 1. One more round of questions — then stop asking
-
-Ask **three to five** questions that actually change the schema or the screens,
-in one message. Then stop; do not interview the user.
-
-- **Who uses it — who are the distinct kinds of people?** Ask this however small
-  the app is. The answer becomes §3's virtual users and roles, and you build only the
-  roles they name.
-- **What are the two or three core objects?**
-- **What is the main thing someone does on their first visit?** This answer
-  becomes the second changeset, not the tenth.
-- **One app or several?** Separate apps on separate hosts, or one app with paths.
-  Cheap to answer now, expensive after the routes exist.
-- **What should it look like?** The template ships one theme — "Neutral", a
-  deliberately unopinionated monochrome scaffold — and **nothing in the
-  open-source toolchain will ever replace it for you.** Accept any of: keep
-  Neutral (fine for an internal tool, but say so out loud); a direction in words;
-  a reference (brand guide, screenshots, a site whose register they want); or
-  their own design agent/prompt, whose output you take as the direction.
-- **Do they want to see the screens before you build them?** Offer it here, in
-  this same round, with yes marked recommended, in the words of
-  the design reference (see SKILL.md) — "a picture of the main screens so you can say 'yes,
-  like that' or 'no, move this'", never "mock" or "wireframe". Behind it is one
-  HTML page mocking the main screens, a few minutes of work. On a yes, or no
-  answer at all, the design reference (see SKILL.md) owns what to make and what it then binds — the
-  approved page becomes source of truth for the screens, and the theme is written
-  before it so what they approve is what ships. Only an explicit no skips it.
-- **May I write test records into the system it talks to?** Ask only when the
-  app reads a live system through an addon (an ERP, a CRM) and a changeset needs
-  data that isn't there yet: an unpaid invoice, a closed ticket. Say what you
-  would create and that it will be marked "Test". A no means building those
-  screens against their empty states.
-- **What language should the app speak, and what language does the team work
-  in?** Two answers, not one — see §1a, which is where they go. Ask only if the
-  request is not obviously English; a brief written in English about an English
-  product answers both.
-
-Skip anything you can decide yourself. If nobody answers, assume one app with
-paths, the roles implied by the request, Neutral, English — and say so.
-
-## 1a. Three languages, and you must not collapse them
-
-A brief saying "the entire UI is German" is about **one** of these. Getting this
-wrong has already shipped a project that can never add a second language, so
-settle all three explicitly before you write code.
-
-| Axis            | What it covers                                                                                                                      | Where it goes                                                                        |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                                   | Nowhere — **always English**, no setting, not negotiable                             |
-| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and virtual user descriptions | `metaLocale` in `pikku.config.json`, default `en`                                    |
-| **Product UI**  | Every string the app shows a user                                                                                                   | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
-
-**Identifiers are English.** The product's market does not change this and
-neither does `metaLocale`. Identifiers are the surface the generated `#pikku/*`
-clients, `pikku info`, the typed RPC map and the Kysely types all bind to, and
-unlike a string an identifier cannot be translated later — renaming one is a
-migration. A German practice management tool gets `getWorklist`, `case`,
-`event`, not `getUebersicht`, `vorgang`, `ereignis`.
-
-**Meta follows `metaLocale`.** Write the team's answer into `pikku.config.json` in
-this phase, before there is any meta to be wrong:
-
-```json
-{ "metaLocale": "de" }
-```
-
-It exists for the Pikku Console. Meta is the one part of a project the Console
-renders back to a human, so a team working in German reads their own functions,
-features and scenario reports in German. Default `en` and do not ask when the
-project is obviously English. **On every later run, read this field first and
-author descriptions, titles and step templates in it** — a project whose
-`metaLocale` you ignored reports half in one language and half in another.
-
-**Product UI is the message catalogue.** `messages/<locale>.json` via
-`pikku-i18n`, with `defaultLocale` deciding what a visitor opens in.
-`baseLocale` in `project.inlang/settings.json` **stays `en`**: it names the
-message source, the catalogue every other language is cloned from, so a project
-that repoints it has nothing to translate from and `--add-locale` is broken
-forever.
-
-A German medical portal, correctly:
-
-```jsonc
-// project.inlang/settings.json
-{ "baseLocale": "en", "locales": ["en", "de"] }
-// apps/app/src/i18n/active.json
-{ "defaultLocale": "de" }
-// pikku.config.json
-{ "metaLocale": "de" }
-```
-
-Record the two non-obvious answers as a `decisions/` note in §2 — neither is
-discoverable from code, and the next agent will otherwise re-derive them wrong.
-
----
-
-## PHASE 1 — What the app is
-
-## 2. Write the knowledge graph — before any code
-
-`knowledge/` is not documentation you write at the end. It is the record of what
-the app IS, in the words its users use, and it is the one part of the project
-another agent picks up and continues from. **Nothing gets built until there is a
-note saying what it is.**
-
-Read `knowledge/index.md` and the `pikku-knowledge` skill, then write the notes
-for what the user just told you. A project whose `knowledge/` is still only the
-shipped index is a project nobody can resume.
-
-Four sections, each answering exactly one question:
-
-- `entities/` — what a thing IS, in the words users use for it
-- `decisions/` — what was chosen and what that rules out.
-  `decisions/security/` for who may reach what, `decisions/design/` for how it
-  looks and behaves
-- `questions/` — what you asked and never got an answer to
-- `wishlist/` — what someone wants that nobody has asked you to build
-
-Rules that make it a graph rather than a pile of files:
-
-- **A note's path is its identity.** Markdown, YAML frontmatter, `type` required.
-  Cross-link notes with plain markdown links — that is what makes it a graph.
-- **Create a section the turn you have a note for it**, with its own `index.md`
-  written in the same turn. Never scaffold empty directories, and never leave
-  notes flat at the root: a `product.md` and a `glossary.md` at `knowledge/` is
-  not a knowledge base, and it leaves the project unbuildable.
-- **A note says what the app is, never what is left to do.** No status, no
-  todo list: the work is filed as changes in §5, and `pikku knowledge gaps`
-  says which notes no change builds yet.
-- **Record only what pikku cannot tell you.** Tables, columns, function
-  signatures, routes, wirings, permissions and roles are all discoverable with
-  `pikku info` / `pikku meta`. Copying them into a note gives you a second copy
-  that goes stale. Knowledge is the why: decisions, constraints, what a thing
-  means.
-
-Three decisions belong here on day one, because every later choice leans on them
-and none is discoverable from code:
-
-- **How the product is split into apps**, and why (§4) — `decisions/`
-- **What each kind of person may reach**, in domain language — `decisions/security/`
-- **What the app should look like** — the direction from §1 (§8) — `decisions/design/`
-
-Then keep it honest — both must pass, and `validate` is a real gate:
-
-```sh
-bunx --bun pikku knowledge index
-bunx --bun pikku knowledge validate
-```
-
----
-
-## PHASE 2 — Who it is for, and what it is made of
-
-## 3. Declare the people — virtual users and roles
-
-The answer to "who uses it" becomes code, in one file:
-`packages/functions/src/virtual-users.ts`. It ships with a single `visitor`; add the
-people the user named, and the roles they imply.
-
-```typescript
-import { defineVirtualUsers } from '#pikku/scopes/pikku-virtual-users.gen.js'
-import { defineSystemRole } from '#pikku/scopes'
-
-defineSystemRole({
-  owner: {
-    displayName: 'Owner',
-    description: 'Runs their own properties — sees only what they own',
-    scopes: [],
-  },
-  tenant: {
-    displayName: 'Tenant',
-    description: 'Lives in one unit — sees only their own tenancy',
-    scopes: [],
-  },
-})
-
-defineVirtualUsers({
-  visitor: {
-    name: 'Visitor',
-    jobTitle: 'Synthetic health-check user',
-    account: {},
-  },
-  amina: {
-    name: 'Amina',
-    jobTitle: 'Property owner',
-    personality: 'Checks arrears first, every single time',
-    roles: ['owner'],
-    account: {},
-  },
-  bilal: {
-    name: 'Bilal',
-    jobTitle: 'Property owner',
-    personality:
-      'A second owner — exists so "you see yours, not theirs" is testable',
-    roles: ['owner'],
-    account: {},
-  },
-  chidi: {
-    name: 'Chidi',
-    jobTitle: 'Tenant',
-    personality: 'Reports the boiler, wants to know it was seen',
-    roles: ['tenant'],
-    account: {},
-  },
-})
-```
-
-- **Keep `visitor`.** The shipped scenarios name `virtualUsers.visitor`, and PKU677
-  requires a browser step's virtual user to be a literal `virtualUsers.<name>`. Removing it
-  stops `virtualUsers.visitor` type-checking, which fails `pikku all`, and nothing you
-  write after that registers.
-- **One `defineVirtualUsers` call for the whole project.** Codegen builds the
-  `VirtualUserId` union from it, materialises one scenario virtual user per person, and
-  seeds a user row each. A second call site is a second answer to "who uses this
-  app".
-- **`roles` is typechecked against `defineSystemRole`.** An undeclared role is a
-  build error rather than a runtime surprise.
-- **Never write an email address.** Each is derived from the virtual user id and
-  `scenarios.emailDomain` in `pikku.config.json` — `visitor@virtualuser.local`.
-  Hand-writing one is how a run signs in as somebody who was never created.
-- **Declare a second person of the same kind** whenever the rule is ownership
-  (`bilal` above). "You see yours, not theirs" is not testable with one owner,
-  and §7 is where it gets caught.
-- **Build the roles the user's answer produces, no more.** An invented role
-  becomes invented screens and invented rules, and it is the user who has to
-  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-auth` skill.
-
-`pikku virtual-user 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 virtual user command.
-That is stale. In this template they live in `virtual-users.ts` as above, and
-`pikku.config.json` carries no virtual users key at all — only `scenarios.emailDomain`.
-Trust the file you can read over the note describing it.
-
-## 4. Declare the apps — one API, several frontends
-
-### The rule that makes it cheap
-
-**One backend, many frontends. Never fork `packages/functions`.**
-
-Every app imports the same generated SDK (`@project/functions-sdk`) and calls the
-same RPCs. What differs is which screens exist and what the shell looks like.
-What must NOT differ is the data layer: two copies of a `listProperties` function
-is two places for the permission check to be wrong.
-
-**The app split is presentation, not security.** A tenant app that simply never
-renders the arrears screen is not access control — it is a hidden button.
-Security is the `permissions` field on the function, and it holds whether the
-caller arrived from the admin origin, the tenant origin, curl, or the generated
-client. Build the split for clarity, and prove the boundary with a refusal
-scenario in §7.
-
-### Choosing the split
-
-- **Separate apps on separate hosts** (`admin.example.com`, `portal.example.com`)
-  — when the two audiences share almost no screens, when they should not see each
-  other's brand register, or when one may later ship independently.
-- **One app with paths** (`/app/admin/*`, `/app/portal/*`) — when they share most
-  of the shell and the difference is a handful of screens. Cheaper, and honest:
-  two nav trees in one app is still two apps to a user.
-
-Either way, write the choice and its reason into `knowledge/decisions/`.
-
-### Adding a second frontend — later, not now
-
-Recording the decision is Phase 2 work. **Creating the directory is not.**
-Cloning `apps/app` materialises a folder of copied screens, so it belongs to the
-changeset that first needs the second app, not to planning.
-
-When you get there, read the multi-app reference (see SKILL.md). It carries the clone, the
-`package.json` edits, the `frontends` map in `pikku.config.json`, the dev-runner
-change that otherwise silently never starts your second app, the per-frontend
-scenario environments, and how sessions behave across two origins.
-
-What Phase 2 owes you now is only this: the split, its reason, and who each app
-serves, written into `knowledge/decisions/`.
-
----
-
-## PHASE 3 — The plan
-
-## 5. File the work as changes
-
-Turn the app into changes on the project's queue — the pikku-changes skill.
-`pikku knowledge gaps` lists every note no change builds yet; file each as one
-or more changes with `pikku changes file`, one commit's worth each, and
-end every body with the gap's `Knowledge:` line so it is not filed twice.
-
-What a change is:
-
-- **One commit's worth.** "The owner sees this month's arrears" is a change,
-  or a few. "Add the database schema" is not; it is a step inside one.
-- **It ends in something a person can do**, in a browser, signed in as a named
-  virtual user. If you cannot say what they see when it is done, that is a
-  `questions/` note, not a change.
-
-If §1's screen mock was made — approved, or drawn because nobody answered —
-every screen on that page belongs to some change, and a screen no change builds
-is a hole in this plan.
-
-How they group into changesets, in order:
-
-1. **The spine first.** The one object everything else hangs off, and the screen
-   that proves the app exists at all.
-2. **Then the loop the user named as "the main thing someone does on their first
-   visit."** That answer from §1 is the second changeset, not the tenth.
-3. **Then each audience's own surface**, one at a time. With two apps, finish one
-   app's spine before starting the other's — a half-built app in each is worse
-   than one working app.
-4. **Refusals ride along with the changeset that creates the thing being
-   refused**, never as a "permissions" changeset at the end.
-
-**One approval, then build to the end.** Show the picture of the screens and
-the changes together, in one message, as the plan. That is the only approval you
-ask for. Once they approve it, or don't answer, run `pikku changes next --exec <harness>
---loop`: it hands each changeset to a fresh agent, merges it, and moves on. Post
-one line as each changeset merges, and carry on. Stop only for what is theirs to
-decide: a credential you don't have, spending money, posting in public, deleting
-or overwriting their data, or a finding that changes the plan.
-
-## 5a. The technical plan — per changeset, before you build it
-
-`pikku changes claim` decides whether a changeset needs a **plan**: one
-that creates or alters a table always does, and the judge decides the rest. The
-plan says what has to exist: the tables, functions, wires, roles, scopes,
-screens and scenarios, split into passes. It is JSON at
-`knowledge/plans/<changeset>.plan.json`, committed on the changeset's branch,
-and `pikku knowledge plan progress` measures the finished build against it.
-
-**Read `pikku-architect` and follow it.** The plan is written 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:
-
-```sh
-pikku knowledge plan schema                        # the only spec there is
-pikku knowledge plan set <changeset> /tmp/plan.json
-pikku knowledge plan show <changeset> --for-build  # what you then build
-```
-
----
-
-## PHASE 4 — Build
-
-## 6. Build each changeset
-
-**Per changeset** — claim it, plan it if the claim says so (§5a), do the six
-steps one commit per change, close it out (§6a), mark its changes done. Do not
-mark the last one done until §6a passes, §7 is green for it _and §7a shows its
-functions covered_; `changes done` refuses a planned changeset's last change
-while the plan is short.
-
-1. **Migration.** SQL in `db/sqlite/` at the project root (`db/postgres/` or
-   `db/mysql/` when `createConfig` sets `postgresUrl` or `mysqlUrl`), numbered on from the
-   ones already there. Apply with `bunx --bun pikku db migrate`, which also
-   regenerates the Kysely types your functions import. **Neither `pikku all` nor
-   restarting `pikku dev` applies a migration** — so a new column reads as
-   `TS2353 … does not exist in type 'InsertExpression<DB, "…">'` on the function
-   that writes it. An unapplied migration is the usual cause and the cheapest to
-   rule out, so run `db migrate` first — but the same error is what a misspelt
-   column or a stale generated type looks like, so if it survives the migration,
-   go and read the SQL.
-2. **Seed.** Demo rows in `db/sqlite-dev-seed.sql`. **There is no seed command** —
-   `bunx --bun pikku db reset` is the only thing that applies the file, and it
-   wipes, migrates and seeds in one go (`--no-seed` stops after the migration,
-   for working on an empty state the test data would hide). Because reset always
-   arrives at a database it just wiped, **the seed file is plain `INSERT`s** — no
-   `ON CONFLICT DO NOTHING`, no `INSERT OR IGNORE`. Nothing ever applies it
-   twice, so it never has to defend itself. It is also **local only** — no deploy
-   applies it, so anything the app would be broken without in production is
-   configuration and belongs in a migration, not here.
-   Do this generously and do it now: an empty app demos badly and critiques
-   badly, and you cannot judge a screen's hierarchy, overflow, or truncation
-   against zero rows. Seed rows each virtual user sees differently — with an ownership
-   rule that means seeding rows for the _second_ owner too.
-3. **Functions.** One `pikkuFunc` per `*.function.ts`. Mark it `expose: true` and
-   Pikku generates the typed RPC client and the React Query hooks the UI calls;
-   you do NOT write an HTTP route for it. Add `wireHTTP` only for a real REST
-   shape (a third-party webhook).
-4. **Regenerate:** `bunx --bun pikku all`
-5. **UI.** Pages in `<app>/src/pages/`, one route file each in `<app>/src/routes/`,
-   calling functions through the generated `usePikkuQuery` / `usePikkuMutation`
-   hooks from `@project/functions-sdk/pikku/api.gen`. One component per `.tsx`
-   file. Compose the kit from `@/components/<Name>` rather than hand-rolling
-   controls — and **add to that kit**: the component that draws the thing this
-   product is actually about, and the furniture you would otherwise copy-paste
-   into eight pages. The kit is where you start, not where you stop; an app whose
-   every screen is `Card` + `Stack` + `Text` composed the inventory rather than a
-   design. Register the screen in `useNavItems()` — that one file feeds both the
-   desktop sidebar and the phone navigation.
-   **Read the design reference (see SKILL.md) before you write the first screen.** You commit
-   to a design direction there and are then accountable to it — it hands you no
-   layouts, because the design is yours to make. What you build here is then
-   judged at step 7, at the end of this changeset rather than once at §8, where
-   the only affordable fix is a repaint of eight screens.
-6. **Scenario** (§7).
-7. **Look at it.** Screenshot every screen this changeset touched, at both
-   widths, with the seed in place, and look at the images. This is a gate, the
-   same as the scenario: a changeset whose screens nobody has seen is not built,
-   it is unproven at the one layer scenarios cannot reach. the design reference
-   carries how to take the shot when no browser tool is wired up, and what to
-   look for. Then close it against its plan (§6a) — `pikku knowledge plan
-progress` has to exit zero before the last change is done — and only then
-   mark it done, saying in the `--note` what you looked at and what it made you
-   change.
-
-Rules that are not optional:
-
-- A function's input and output types come from its `input:`/`output:` zod
-  schemas. Never pass generic type params, never annotate the return type inline.
-  The schema is the type. (Generics XOR schemas — never both.)
-- Auth and permission checks go in the `permissions` field, never in the function
-  body. This is what makes §4's app split safe.
-- No `process.env` inside a function. Read config through the injected
-  `variables` / `secrets` services; `process.env` belongs only in bootstrap. Every
-  secret a function reads needs a matching `defineSecret`, or `pikku all` reports
-  PKU951 and nobody knows what to provision at deploy.
-- Let the database type your values, via `db/annotations.ts`. A `BOOLEAN` column
-  is derived for you. On SQLite the other two are **not** — add them by hand,
-  once, and they are typed AND coerced end-to-end:
-
-  ```typescript
-  export const classifications = {
-    payment: {
-      paid_at: { kind: 'date' }, // -> Date, not an ISO string
-      metadata: { kind: 'json', tsType: 'PaymentMeta' }, // -> parsed object, not unknown
-    },
-  }
-  ```
-
-  A `TIMESTAMP`/`DATETIME`/`DATE` column with no entry types as `string`, and a
-  `JSON` column with no entry types as `unknown` (the CLI warns PKU481). Add the
-  annotation rather than casting around the generated type. Once the file carries
-  manual fields, `db migrate` stops overwriting it.
-
-- A `z.date()` on a function's **input** arrives over RPC as an ISO string, not a
-  `Date`. Normalise before calling date methods on it (`new Date(value)`), or it
-  throws `.getTime is not a function` at runtime — schema validation accepts the
-  string without converting it.
-- Every user-facing string is a translation key. Never a hardcoded literal. With
-  two apps that means two `messages/` directories; a string used by both belongs
-  to whichever app renders it, and duplication beats a shared bundle that couples
-  the apps together.
-- Surface errors. No empty catch, no swallowed promise. If a mutation can fail,
-  render the failure inline next to the control that triggered it — not a toast.
-- An exposed function with no session and no permission is reachable by anyone
-  over `POST /rpc/:rpcName` (PKU574). Either gate it, drop `expose: true`, or —
-  when public is the point — write `auth: false` on it to say so.
-- A public, signed-out read (a homepage's programme, a price list) is a
-  `pikkuSessionlessFunc` with `auth: false` written out, which is what keeps
-  PKU574 quiet for it. `pikkuFunc` with `auth: false` still answers
-  `MissingSessionError` over `/rpc` to a caller with no session.
-- Better Auth already owns the `user`, `session`, `account` and `verification`
-  tables. A domain table with one of those names — a class _session_, a drop-in
-  _session_ — collides in the migration. Name it for the domain instead
-  (`evening`, `class_meeting`) and keep the word in the UI copy.
-- The template's `/` redirects to `/app`, so the login screen is what a
-  signed-out visitor sees first. Replace `/` with a public homepage and a
-  reviewer lands on a site with no way in: link it to the login screen.
-
-Before the first run, make sure `.env` at the project root holds the secret
-the local stack needs. `bun run dev` appends it if missing, but check anyway —
-a project scaffolded from an older template, or a `.env` copied in from
-elsewhere, can lack it, and the failure does not name the variable:
-
-- `BETTER_AUTH_SECRET` — without it the first sign-up is a 500.
-
-Virtual user sign-in needs nothing in `.env`: `pikku dev` creates its own key
-pair and hands the app the public half.
-
-```sh
-grep -q '^BETTER_AUTH_SECRET=' .env 2>/dev/null || echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
-```
-
-`.env` is gitignored and local only — never commit it. A deployed stage gets its
-secrets from the hosting platform, not from this file.
-
-Then run it:
-
-```sh
-bun run prebuild && bun run dev
-```
-
-That starts the API on :3000 and every frontend in `frontends`. A
-frontend running against a dead API looks exactly like an app bug, so if every
-request fails, check that both halves came up.
-
-**Start the stack through `bun run dev`, not by launching `vite` or `pikku dev`
-yourself.** The frontend needs to reach _your_ API. If you start the
-frontend on its own (say :3000 is taken by another project), point
-`VITE_API_PROXY` at your API: the dev proxy defaults to `http://localhost:3000`,
-so beside another project's server every request goes to the wrong API.
-
-The `--bun` in `bunx --bun pikku …` is load-bearing — keep it. Without it the
-CLI's `#!/usr/bin/env node` shebang hands the process to whatever Node is on
-PATH, which fails below Node 24 with `ERR_UNKNOWN_BUILTIN_MODULE: No such
-built-in module: node:sqlite`.
-
-Open it, sign up, and click through what you built. **HTTP 200 is not evidence.**
-The pages are client-rendered: the server returns 200 with an empty shell, so a
-page whose component throws still looks fine to `curl`.
-
-That click-through is a smoke check, and it is the only thing it is. **Do not
-hand-drive a browser tool in place of a test.** Steering Playwright yourself
-proves a page rendered once, on your machine, in an order only you remember —
-nothing about it re-runs, so the next agent inherits a claim rather than a test,
-and a regression lands silently. When a journey is worth driving through the UI,
-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 changeset against its plan, not against your memory
-
-```sh
-pikku knowledge plan progress <changeset>
-```
-
-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. It exits non-zero while anything in the first pass is
-missing, and `changes done` runs the same check on the last change.
-
-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 <changeset> function:sendReminder \
-    -r "The email service it needs is the next changeset."
-  ```
-
-  **A deferral is capped at two per plan.** Past that, the plan was wrong and the
-  changeset is two changesets — say so rather than deferring again. What you may
-  never do is drop the item silently. A merged changeset with deferrals leaves its
-  notes `partial`, and `pikku knowledge gaps` files what it left behind.
-
-- **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 edit the plan to match what you built — the plan was written before the
-code on purpose, and rewriting your own denominator afterwards is exactly what
-that order exists to stop.
-
-### 6b. Feed the changeset back into the seats
-
-Before starting the next changeset, answer two questions out loud:
-
-- **What did the plan fail to say?** A field nothing wrote, a promise no function
-  could keep, a pass 1 that turned out to be two. That is a `pikku-architect`
-  lesson.
-- **What did the build learn the hard way?** Anything that cost a wasted run —
-  a stale process, a scenario that only passes once, a diagnostic that turned
-  out to be an echo of an earlier one. That is a `pikku-build` lesson.
-
-Then edit the skill — **at most one change to each per changeset**, and only for
-something that actually went wrong here. A rule with no incident behind it is a
-guess, and these files are read in full every time: they earn their length by
-naming failures a reader would otherwise repeat. Prefer sharpening an existing
-line to appending a new one, and delete a rule the last few changesets have
-shown to be noise.
-
-The gates are the compounding part. A lesson written into a scenario the suite
-runs, or into a check `plan progress` can see, is enforced; the same lesson
-written as prose is a thing the next reader has to remember. Reach for prose
-only when there is nothing to hang a check on.
-
-## 7. Prove it — scenarios
-
-A scenario is a user journey run as one of your virtual users, over the real
-transport, with that virtual user's session. It is the only kind of test worth writing
-here, because a passing one proves the app works the way a signed-in person
-experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
-green — and every scenario a changeset's plan names becomes one more.
-
-**Read the scenarios reference (see SKILL.md) before writing the changeset's scenarios,
-and again whenever one of these describes what you are doing.** It is the file
-where the expensive lessons live, and most of them produce a GREEN suite that
-proves nothing:
-
-- the shape of a scenario, and `do` vs `given`/`when`/`then`
-- what survives DSL extraction — a `then` in `return` position asserts nothing,
-  and a shared setup helper credits its steps to the wrong virtual user
-- what to assert — refusals must read the REASON, totals must be deltas, and the
-  assertion nobody writes is the row count
-- living without a state reset: the suite must be green on its SECOND run
-- how a shared step rots as later changesets add writers of the rows it selects
-- browser specifics — the click/navigate race, testids, and `Outlet` nesting
-
-Run them:
-
-```sh
-bunx --bun pikku scenario run local --spawn                  # server-side, the fast path
-bunx --bun pikku scenario run local --spawn --run browser    # the same journeys, driven as a human
-```
-
-In a multi-app project that one run covers both frontends: each virtual user carries
-its own `app` and `@pikku/playwright` resolves the base url from the
-environment's `appUrls` map, so there is no second environment to run.
-
-**Run the whole suite, not the changeset's own scenarios.** The changeset's
-scenarios are the ones you wrote to pass; the regression lives in someone
-else's. Tightening what "archived" means is a one-function change that reads as
-local and quietly breaks the first changeset's scenario nobody re-ran.
-
-**Restart the server after adding a function, and never edit one while a run is
-in flight.** Hot reload does not register a new RPC and does not re-run
-`afterStart`, so a fresh function answers 404 and anything provisioned at boot
-is missing — failures that read like a wiring bug and are nothing but a stale
-process. The same reload is what makes a run unrepeatable if you edit during
-it: a browser pass is long enough to feel like free time, and a schema touched
-at minute four hot-reloads into a half-generated contract, so every scenario
-after that point fails on something you have already fixed. Wait for the run or
-kill it — a run you edited under is not a result.
-
-### 7a. Coverage — which functions have actually been run
-
-Green scenarios tell you the journeys you wrote still work. They say nothing
-about the code you never wrote a journey for:
-
-```sh
-bunx --bun pikku dev --coverage                        # server, instrumented
-bunx --bun pikku scenario run local --coverage         # against that server
-```
-
-**A function no scenario touches has no scenario coverage** — the file knows
-what the suite exercises and nothing else, so a unit test, a scheduled job, a
-webhook or a hand call leaves no trace in it. Read
-`coverage/scenario-coverage.json` **as each changeset closes** — per changeset it is a short list you can act on, whereas read for the
-first time after ten changesets it is a wall of red nobody triages. Every gap is
-a missing scenario, a function that should not exist, or a deferral worth
-writing down; the scenarios reference (see SKILL.md) says how to tell them apart. Report
-the number when you hand the changeset over.
-
-## 8. Make it look like someone designed it
-
-**This section numbers 8, but half of it has already happened.** Read
-the design reference (see SKILL.md) before the first screen is built — a design pass run on
-eight changesets of scaffolded screens is a repaint, and it shows. What is left
-here at §8 is the theme you may have deferred and the critique you cannot run
-until there are screens to critique.
-
-Three separate jobs, and conflating them is why open-source builds come out
-looking like the template:
-
-- **Direction** — deciding what it should look like. **No open-source tool does
-  this.** A hosting platform may offer one; you have §1's answer and 8a below.
-- **Execution** — whether the screens actually realise that direction, or
-  default to whatever component was nearest. No theme does this, and it is where
-  "works but looks like nobody decided anything" comes from.
-  the design reference (see SKILL.md) carries the process for it, and it belongs at §6, per
-  screen.
-- **Critique** — judging how well the built screens execute the direction.
-  `impeccable` does this well, and it is free.
-
-Impeccable audits the design you chose. It will never tell you the app should
-have looked like something else — it will happily award a clean bill of health to
-a perfectly-executed default. Skip the first two and you ship Neutral with good
-spacing.
-
-### 8a. Author the theme — the step nothing does for you
-
-The look lives in `packages/theme`, and it is data, not code — one JSON
-per theme, `active.json` naming the live one. **Read the theming reference (see SKILL.md)** for
-the file layout, what each field changes, and how to turn a direction in words
-into a theme.
-
-Two things that belong here rather than in the reference, because they govern
-every screen you then build:
-
-**Set the theme once, don't hardcode colours per component.** A screen full of
-inline `color="blue"` and one-off hex values is why apps look templated. Change
-the theme, not the components — and keep it theme-aware for light and dark.
-
-With two apps, **share the theme package and vary the register, not the
-palette.** A back-office can be denser and more tabular; a customer-facing app
-can be roomier and warmer — that is `structure` and layout, not a second `brand`.
-Two unrelated colour schemes read as two products from two companies.
-
-Then **write the direction into `knowledge/decisions/design/`** — the words the
-user gave you, what you chose, and what it rules out. The JSON records what the
-theme is; only the note records why.
-
-### 8b. Compose real components, then critique
-
-**The design reference (see SKILL.md) is where design actually lives** — committing to a
-direction before the first screen, judging the result from screenshots rather
-than from source, the two screens that get skipped, and why you reset the dev
-database before judging anything. It prescribes no layouts on purpose: two apps
-built from this skill should not look like each other. What follows here is only
-the component inventory.
-
-**Compose with rich components — not tables and text everywhere:**
-
-- **shadcn `chart`** (Recharts underneath, coloured by `--chart-1` to `--chart-5`) for overviews — area,
-  bar, line and pie charts. A metric worth showing is
-  worth a chart, not a number in a paragraph.
-- **shadcn `calendar` and `date-picker`** for anything time-based, including
-  range inputs. Never hand-roll a date field.
-- Composed layouts over flat lists — a timeline for history, steps for
-  multi-step progress, `Card` + a CSS grid for a gallery, `Progress` for
-  completion, `Badge` for status.
-
-Add each one with the shadcn CLI and use the real component.
-
-Then critique it. Free, and works across coding agents:
-
-```sh
-npx impeccable install     # current releases need Node 22.18+
-```
-
-Impeccable scores a screen against interaction heuristics and names what is
-wrong: hierarchy, spacing, type registers, states you forgot. Run it on **every**
-screen in **every** app, fix what it finds, and re-run the ones you changed.
-
-Screenshot each page and feed it the images. Without them its findings drop to
-inference from source, and it misses real misalignment, contrast, and overflow.
-Judging your own UI from source code is guessing.
-
-**Screenshot at a phone width too (≈390px), not just desktop, and critique
-those.** A layout that is fine at 1440px routinely breaks at 390 — a table that
-overflows, a row of buttons that wraps into a pile, text jammed against the edge,
-a modal taller than the viewport. Tailwind gives you the tools (responsive `grid-cols-*`,
-`md:hidden` / `hidden md:block`, `flex-col` instead of `flex-row` at small sizes); use
-them. The template already mounts a phone navigation per `AGENTS.md` — pick
-`MobileTabBar` or `MobileNavDrawer` deliberately per app, never both.
-
-The gate: **no P0 findings left on any screen, in any app, at either width**,
-and every screen honestly answers the questions in the design reference —
-including whether it looks like the direction you committed to or like the
-components you had. Don't silence a finding by deleting the feature it is
-about.
-
-**Critique the data too, not just the layout.** Scenario runs write run-tagged
-rows into the dev database, so by §8 the app is full of `Ripe peaches d193e2aa`
-seven copies deep. Run `pikku db reset` and restart the dev server before you
-screenshot anything — a screen judged against that data gets designed for a
-problem it does not have.
-
-## 9. Ship it, and stay deploy-ready
-
-When the queue is empty, `pikku knowledge gaps` lists nothing and the scenarios are green, read
-the ship reference (see SKILL.md). It carries the open-source deploy paths (`--provider
-standalone`, `cloudflare`, `aws`), how to serve several frontends behind one
-API, the pre-release gate to run, and the contract that keeps the project
-importable by a hosting platform later rather than a migration.
-
-The app is not handed over without its user guide. The scenarios you wrote are
-already its skeleton: read **pikku-guide**, write one page per audience citing
-every feature, and build it from a full, passing `--run browser --screenshots`
-run.
-
-Two things from it are worth knowing before you get there, because they are
-cheaper to honour than to retrofit:
-
-- **Nothing hardcodes a host, a port, or a `process.env` read inside a
-  function.** Secrets go through `defineSecret` and the injected `secrets`
-  service. This is the most common reason a working local project fails its
-  first deploy, on any platform.
-- **Generated files stay generated.** No hand edits to `.pikku/`, `*.gen.*`, or
-  the SDK.
+5. Report at the person's level (SKILL.md, "Who you are talking to"): plain
+   words, the app and API links `bun run dev` printed, and no code unless they
+   are a developer.
+
+## Rules that hold in every phase
+
+- **Identifiers are always English**; meta follows `metaLocale`; product UI strings are
+  translation keys (§1a, §6).
+- **Permissions live in a function's `permissions` field**, never in its body or in a frontend (§4, §6).
+- **No `process.env` inside a function**; secrets go through `defineSecret` and the injected `secrets` service (§6, §9).
+- **Generated files stay generated** — never hand-edit `.pikku/`, `*.gen.*`, or the SDK.
+- **Nothing is built until a knowledge note says what it is** (§2), and a plan is never edited to match what you built (§5a, §6a).
+- **Every changeset ends proven**: a passing scenario including its refusals (§7), screens looked at (§6), functions covered (§7a).
+- **One approval, then build to the end** (§5). Stop only for what is theirs to decide.
 
 ## Reference