@pikku/skills 0.12.57 → 0.12.59

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

@@ -65,7 +65,7 @@ schemas (`yarn pikku meta functions get <id>`) or workflow steps
 
 **Language rule:** read `metaLocale` in `pikku.config.json` (default `en`). It is
 the language of every `description`, `title` and step `template` you author —
-the meta the Pikku Console renders back to the team. It renames nothing:
+the meta that is read back to the team. It renames nothing:
 functions, components, types, files, tables and columns are English in every
 project, and what the app says to its users is the message catalogue. See
 `pikku-concepts` → _What Language You Write In_.
@@ -260,9 +260,7 @@ your branch and silently breaks theirs.
 
 Tell the user the branch name and how to review. Two options:
 
-- **Local review:** open the pikku console — the changes view diffs the
-  current branch against `main` with pikku-aware structure (added functions,
-  new wires, migrations).
+- **Local review:** `git diff main` on the branch.
 - **PR review:** ask before pushing. Once they confirm, `git push -u origin
 feature/<slug>` and surface the PR-create URL.
 
@@ -300,7 +298,7 @@ explanation of why and what would change.
 - Stage 2 (intent statement) is plain English, one paragraph.
 - Between stages, give one-line updates: "Discovered 30 functions, http+queue
   in use. Drafting intent..." → "Branch `feature/todos` created, implementing..."
-  → "`pikku all` clean, `tsc` clean, committed. Review via console or run
+  → "`pikku all` clean, `tsc` clean, committed. Review with
   `git diff main`."
 - Don't narrate file-by-file. Only surface what's interesting (new patterns,
   judgment calls, things you suppressed).

package/skills/pikku-build/references/phase-1-what-it-is.md

@@ -0,0 +1,167 @@
+# Phase 1 — What the app is (§0, §1, §1a, §2)
+
+Part of the app workflow (`app.md` is the index and the rules that hold throughout). Work through §0 to §2 in order, before any code.
+
+## 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" }
+```
+
+Meta is the one part of a project that is read back by 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.
+
+---
+
+## 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
+```

package/skills/pikku-build/references/phase-2-people-and-apps.md

@@ -0,0 +1,133 @@
+# Phase 2 — Who it is for, and what it is made of (§3, §4)
+
+Part of the app workflow (`app.md` is the index and the rules that hold throughout). Declare the people, then decide the apps.
+
+## 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/`.

package/skills/pikku-build/references/phase-3-plan.md

@@ -0,0 +1,62 @@
+# Phase 3 — The plan (§5, §5a)
+
+Part of the app workflow (`app.md` is the index and the rules that hold throughout). File the work, and plan each changeset that needs it.
+
+## 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
+```

package/skills/pikku-build/references/phase-4-build.md

@@ -0,0 +1,249 @@
+# Phase 4 — Build (§6, §6a, §6b)
+
+Part of the app workflow (`app.md` is the index and the rules that hold throughout). Read this for each changeset. Proving and shipping it are §7-§9, in `phase-5-prove-and-ship.md`.
+
+## 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 it where the design reference (see SKILL.md), "The kit is a floor", says to.
+   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.
+
+**A host can inject platform services into `pikku dev`** the way a deploy does, with
+`dev.contributors` in `pikku.config.json`:
+
+```json
+{
+  "dev": {
+    "contributors": [
+      { "module": "./dev/email-contributor.ts", "export": "email" }
+    ]
+  }
+}
+```
+
+The module exports a `PlatformServiceContributor` (`{ name, imports?, emit }`, the
+type `@pikku/deploy` takes). `pikku all` writes `.pikku/pikku-dev-platform-services.gen.ts`
+from them, and `pikku dev` merges what it returns over the local services before
+`createSingletonServices` runs, so a contributed `emailService` beats
+`LocalEmailService` (and the test-mode spy). Nothing is written without
+contributors, `pikku serve` never loads it, and `NODE_ENV=production` ignores it. An import a contributor names by `file://` URL or absolute path is written as the package export that points at it, or as a path relative to `.pikku/`, so the file typechecks under the project's tsconfig as long as the lines a contributor emits are typed.
+
+## 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.