@pikku/skills 0.12.34 → 0.12.37

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

@@ -494,6 +494,35 @@ Rules that are not optional:
   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 or drop `expose: true`.
+- A public, signed-out read (a homepage's programme, a price list) is a
+  `pikkuSessionlessFunc`. `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 — and its "Sign in
+  as …" switcher — is what a signed-out visitor sees first. Replace `/` with a
+  public homepage and that stops being true: mount `<DevActorSwitcher />` in the
+  public layout as well, or a reviewer lands on a site with no way in.
+
+Before the first run, make sure `.env` at the project root holds the two
+secrets the local stack needs. `bun run dev` appends whichever is missing, but
+check anyway — a project scaffolded from an older template, or a `.env` copied
+in from elsewhere, can lack one, and neither failure names the variable:
+
+- `BETTER_AUTH_SECRET` — without it the first sign-up is a 500.
+- `SCENARIO_ACTOR_SECRET` — without it `/api/auth/sign-in/actor` is disabled:
+  every scenario fails at sign-in before its first step, and the "Sign in as …"
+  switcher renders nothing.
+
+```sh
+grep -q '^BETTER_AUTH_SECRET=' .env 2>/dev/null || echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
+grep -q '^SCENARIO_ACTOR_SECRET=' .env 2>/dev/null || echo "SCENARIO_ACTOR_SECRET=$(openssl rand -base64 32)" >> .env
+```
+
+`.env` is gitignored and local only — never commit it. A deployed stage gets its
+secrets from the platform (`pikku fabric secrets`), not from this file.
 
 Then run it:
 
@@ -505,6 +534,19 @@ That starts the API on :3000 and every frontend in `pikkufabric.config.json`. 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 dev script reads the personas, derives one credential per
+persona from `SCENARIO_ACTOR_SECRET`, and hands both to the frontend as
+`VITE_DEV_ACTORS` / `VITE_DEV_ACTOR_SECRETS`. Vite reads those once, at boot. A
+frontend started any other way — or restarted by hand later — has an empty
+actor list, and the switcher silently disappears from every page. If you do
+start the frontend on its own (say :3000 is taken by another project), you owe
+it three things: the two `VITE_DEV_*` values the dev script would have computed,
+and `VITE_API_PROXY` pointing at your API — the dev proxy defaults to
+`http://localhost:3000`, so beside another project's server your sign-ins go to
+*its* API and come back `401 Invalid actor secret`, which reads like a bad
+credential rather than the wrong server.
+
 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
@@ -614,10 +656,11 @@ export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
 - **Write the refusals.** The third step above is the whole point of §4: one
   persona reaching for another's row has to be rejected, and that rejection is a
   scenario. It is how you prove access control instead of asserting it.
-- **Add `SCENARIO_ACTOR_SECRET` to `.env`.** `bun run dev` generates that file
-  with a `BETTER_AUTH_SECRET` and nothing else, and without the actor secret
-  `/api/auth/sign-in/actor` is disabled — every scenario then fails at sign-in,
-  before its first step, for a reason that reads like an auth bug.
+- **`SCENARIO_ACTOR_SECRET` must be in `.env`** (§6, before the first run).
+  Without it `/api/auth/sign-in/actor` is disabled — every scenario then fails
+  at sign-in, before its first step, for a reason that reads like an auth bug.
+  `pikku scenario run` reads it from the environment, so source `.env` first
+  (`set -a && . ./.env && set +a`) when you run outside `bun run dev`.
 - **There is no state reset.** A scenario runs against a live server: scope what
   you create to your own rows and unique ids, and never assume a clean database.
 
@@ -786,6 +829,11 @@ standalone`, `cloudflare`, `aws`), how to serve several frontends behind one
 API, the pre-release gate to run, and the contract that keeps `pikku fabric init`
 a one-command import 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:
 

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

@@ -1,5 +1,19 @@
 # Pikku Create-a-Feature
 
+The stages, in order:
+
+- [Agent Operating Procedure](#agent-operating-procedure)
+- [Stage 1 — Discover](#stage-1--discover)
+- [Stage 2 — State intent in plain English (BEFORE writing code)](#stage-2--state-intent-in-plain-english-before-writing-code)
+- [Stage 3 — Branch off](#stage-3--branch-off)
+- [Stage 4 — Implement](#stage-4--implement)
+- [Stage 5 — Verify](#stage-5--verify)
+- [Stage 6 — Commit](#stage-6--commit)
+- [Stage 7 — Hand off](#stage-7--hand-off)
+- [Report what fought you](#report-what-fought-you)
+- [Hard constraints](#hard-constraints)
+- [Output discipline](#output-discipline)
+
 ## Agent Operating Procedure
 
 Use this skill as an execution checklist, not reference material.
@@ -7,7 +21,7 @@ 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.
+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 validation. Do not paper over generated errors by editing generated files.
 6. Report anything about pikku itself that cost you time, the moment it happens — see **Report what fought you**.
 
@@ -242,103 +256,16 @@ Do not push without explicit confirmation. Do not merge.
 
 ## Report what fought you
 
-When pikku itself is what cost you time, report it with `pikku fabric report`.
-Nothing is written to the repo; the finding goes to the linked fabric project
-and the terminal shows you exactly what was sent.
-
-**Report at the moment it happens**, not at the end from memory — a run that
-falls over never reaches its end. One finding per thing that fought you.
-
-### The ladder
-
-1. **Find the quicker workaround.** The user is paying for their feature, not
-   for pikku's health.
-2. **Investigate** only when there is no workaround, or when the user asks why
-   something is slow or wrong.
-3. **Report at the depth you already reached.** Never spend extra effort to
-   file; never throw away effort you already spent. If the investigation took
-   you to the mechanism, the finding says so — named file, named function, what
-   is actually happening, and what pikku should do instead.
-
-**Never fix pikku itself.** Not a patch in `node_modules`, not a linked
-checkout, not a branch in the framework repo. Many agents each patching pikku to
-unblock themselves is many divergent copies and a merge problem nobody signed up
-for. Work around it in the app, report it, and let the fix happen once.
-
-### What counts
-
-Anything that cost you time and would cost the next person the same. Most of
-these never produce an error: output that is quietly wrong, a generated type
-that disagrees with the runtime, a check that passes when it should not, a
-narrowing you had to write by hand because the framework should have written it.
-**Having to write code the framework should have written for you is a finding.**
-
-So is anything that only shows up in one place — invisible locally, fatal
-deployed, or the reverse. Say which, with `--surface`.
-
-Not a finding: a preference, a thing you would have designed differently, or
-baseline noise that was already failing before you started.
-
-### Two kinds
-
-- `--kind product` — pikku behaved wrongly. Fixing it is a change to the
-  framework.
-- `--kind harness` — a skill misled you: it told you to run something that does
-  not exist, described a flag that is spelled differently, or contradicted what
-  the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
-  section>"`. This is the most useful kind to file, because it is fixable
-  immediately — so file it even when the cost was small.
-
-### When there was no workaround
-
-Report it anyway with `--unresolved`, and put what you tried and how each
-attempt failed in `--tried`. That is what stops the next person walking the same
-dead ends. Tell the user what you did instead — abandoned it, shipped something
-degraded, or stopped.
-
-`--unresolved` means **no workaround was found**. It does not mean the
-workaround was unpleasant.
-
-### The command
-
-Send it as JSON on stdin. Most of a finding is prose, and prose carries
-apostrophes, quotes, backticks and newlines — each one a shell metacharacter
-before it is a character in your sentence. A stack trace passed to `--error`
-breaks the command at its first newline; a backtick in `--actual` runs whatever
-follows it. Quote the heredoc delimiter (`<<'EOF'`, never `<<EOF`) so the shell
-leaves the body alone.
-
-```bash
-pikku fabric report --stdin <<'EOF'
-{
-  "title": "<one-line title>",
-  "kind": "product",
-  "model": "<the model you are>",
-  "expected": "<what you expected pikku to do>",
-  "actual": "<what it did instead>",
-  "command": "<the command you ran>",
-  "workaround": "<what you did instead, inside the app>"
-}
-EOF
-```
-
-Add whichever of these you actually have: `error` (the error's message line,
-verbatim), `repro` (the shortest way to reach it again), `proposal` (what pikku
-should do), `area`, `surface` (`local`, `deployed` or `both`), `cost` (measured
-if you measured it — "98s vs 20s steady" ranks; "slow" does not), `run` (an id
-shared by every finding from this build), `deployTarget`.
-
-The same fields exist as flags — `--kind`, `--expected` and so on — for a
-finding short enough to type. Anything with a newline or a quote in it goes
-through `--stdin`.
+When pikku itself is what cost you time — a wrong generated type, a check that
+passed when it should not, a skill that misled you — file it with `pikku fabric
+report`. The `pikku-report` skill owns the ladder, the two kinds, the JSON-on-
+stdin form and the local spool; read it before filing.
 
-Versions, platform and package manager are read off the installed tree for you.
-Do not pass them and do not ask the user for them.
+Reporting at all is permitted here (see **Hard constraints**) and is the one
+network call a build may make. Nothing is written to the repo. Never patch pikku
+itself — not `node_modules`, not a linked checkout — work around it in the app,
+report it, and let the fix happen once.
 
-Reporting never fails a build. A finding that cannot be sent — logged out, or
-fabric unreachable — is held on the machine and goes out with the next report
-that succeeds, so nothing you file is lost. If it says the finding was queued,
-carry on with the feature; do not try to fix it, and do not file it again.
 
 ## Hard constraints
 

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

@@ -149,7 +149,17 @@ than they save:
   keystroke now and a rewrite later.
 - Never hardcode a host or port — the API base resolves to same-origin `/api`.
 
-Then run it:
+Before the first run, make sure `.env` holds both local secrets — `bun run dev`
+appends missing ones, but an older scaffold or a copied `.env` may not have them:
+
+```sh
+grep -q '^BETTER_AUTH_SECRET=' .env 2>/dev/null || echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
+grep -q '^SCENARIO_ACTOR_SECRET=' .env 2>/dev/null || echo "SCENARIO_ACTOR_SECRET=$(openssl rand -base64 32)" >> .env
+```
+
+Never commit `.env`. Then run it — through `bun run dev`, never `vite` on its
+own, because the dev script is what hands the frontend the persona list for the
+"Sign in as …" switcher; without it the switcher silently renders nothing:
 
 ```sh
 bun run prebuild && bun run dev
@@ -200,8 +210,7 @@ export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>
   `pikkuScenarioStep`.** An RPC name in a `then` will not resolve.
 - **Every scenario must assert.** A ladder with no `then` is a PKU680 critical —
   it fails `pikku all`, stopping codegen rather than a test.
-- **Add `SCENARIO_ACTOR_SECRET` to `.env`.** `bun run dev` writes that file with
-  only a `BETTER_AUTH_SECRET`; without the actor secret
+- **`SCENARIO_ACTOR_SECRET` must be in `.env`** (above). Without it
   `/api/auth/sign-in/actor` is disabled and every scenario fails at sign-in, for
   a reason that reads like an auth bug.
 - **There is no state reset** — scope what you create to unique ids.

package/skills/pikku-changes/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: pikku-changes
+description: 'Work a project''s changes queue — the todo list someone filed by walking a deployed stage. Covers `pikku fabric changes list|claim|show|ask|shot|done`, when to ask a question instead of guessing, and how to offer options as images. TRIGGER when: the user says "work the changes", "pick up the changes queue", names a change by its #number, or you are otherwise idle in a repo that has a pikkufabric.config.json. DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage — use pikku-fabric for those.'
+installGroups: [fabric]
+---
+
+# Working a changes queue
+
+Someone walked the deployed app and circled twenty things. Each one is a row with their
+words, a picture of what they were looking at, and the elements the circle enclosed. You
+have the repo and the app running locally. Your job is to empty the queue without making
+them regret filing.
+
+## The loop
+
+Every argument is a flag; nothing is positional. `--json` works on any of them. The
+project comes from the local `pikkufabric.config.json`, so `--project-id` is only needed
+when you are not in the checkout.
+
+```bash
+pikku fabric changes list --pickup-only --json
+pikku fabric changes claim --change-ids <id>,<id> --title "Checkout pass" --claimed-by claude-code
+pikku fabric changes show --change-id <id>
+pikku fabric changes ask --change-id <id> --question "…" --option "…" --option "…" --author-name claude-code
+pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
+pikku fabric changes done --change-id <id> --note "What you did"
+```
+
+`list --pickup-only` is the one a harness wants: it skips items still inside the grace
+window, so a batch someone is mid-way through typing is picked up together rather than item
+by item as it lands.
+
+Deciding what belongs together is yours: `claim` with `--change-ids` and no `--group-id`
+forms the group. Claim an existing one with `--group-id`.
+
+Claim before working. The lease expires (30 minutes by default, `--lease-minutes` to
+change it), so an abandoned claim returns to the queue rather than parking the work
+forever — but a second harness picking up something you are halfway through is the failure
+this prevents.
+
+## Reading an item
+
+`show` gives you four things, in descending order of trustworthiness:
+
+1. **Their words.** The title and body are the requirement. Everything else is evidence.
+2. **The screenshot.** What they actually saw, at their width, with their data. When the
+   other addresses disagree with the picture, the picture is right.
+3. **The circled elements** — a testid, a source anchor, a CSS path. The testid greps
+   straight to a component because it is the i18n message key.
+4. **The source anchor**, printed as `src/routes/app.orders.tsx:42 as of a91c4e2`. That line
+   number is where the JSX was **at that commit**. Read it as a starting point and find
+   today's equivalent; never edit line 42 of today's file because the anchor said 42.
+
+Resolution is a guess and the panel says so. If the circle and the anchor point at
+different things, believe the circle.
+
+## When to ask
+
+Ask when the item admits more than one reasonable implementation and you would be **picking
+for them**. Do not ask to confirm something the item already says.
+
+Ask:
+- "Make the total stand out" — bigger, bolder, coloured, or moved above the fold?
+- "This should be faster" — is it the spinner, the request, or the number of steps?
+- Anything that changes what data is stored, what an existing user sees, or what something costs.
+
+Do not ask:
+- "Should I use flexbox or grid?" — that is yours.
+- "Do you want me to fix the typo?" — they filed it; fix it.
+- "Can you confirm you want the button blue?" — they said blue.
+
+A question costs them a context switch, not typing. That is the budget you are spending.
+
+## What a good question looks like
+
+One decision. Their vocabulary, not the codebase's. And the choices in `--option`, not in
+the sentence.
+
+> **Bad:** "How would you like me to handle the ambiguity in the checkout total component's
+> emphasis requirement?"
+>
+> **Good:** `--question "Make the total stand out — which way?"`
+> `--option "Bigger" --option "Move it above the delivery line"`
+
+**A choice written into the prose is not a choice.** Every `--option` becomes a button in
+the panel and the console, and clicking one records the answer; a question that says
+"(a) build it, (b) leave existing bookings, (c) hold" makes them re-type in free text what
+they should have been able to click, and leaves you parsing prose to find out which one
+they meant. If you can enumerate them in the sentence, you can pass them as flags.
+
+Pass them even when there are only two, and even when one is "hold until I check" — that
+last one is a real option and it is the one most often left off. The filer can always
+choose "say something else", so the list constrains nothing.
+
+Batch per group. Three questions about one checkout flow go out together; three separate
+asks about the same screen is three interruptions for one context switch.
+
+Then **park it**. `ask` flips the item to `needs_answer` and you move to the next item. Do
+not sit waiting — pick answers up on your next `show`, and bound your polling so an
+unanswered item does not spin forever.
+
+## When to show instead of ask
+
+If the answer is visual and you can build it, build all of them and attach images:
+
+```bash
+pikku fabric changes shot --change-id <id> --label "Bigger" --kind option --image a.png
+pikku fabric changes shot --change-id <id> --label "Above the line" --kind option --image b.png
+```
+
+The panel turns a set of `option` attachments into a pick-one they open full-screen, and
+picking one writes the choice into the thread. Capture every variant in **one pass at one
+width**, including the baseline — variants shot at different sizes are not comparable, and
+comparing is the whole point.
+
+`--kind evidence` is the other use: a picture that proves something, rendered inline rather
+than as a choice.
+
+## Committing
+
+One item, one commit. `done` records a single `head_commit`, and that sha is what a human
+reverts when they change their mind — so an item folded in with three others cannot be
+undone without taking the other three with it. Land unrelated work separately.
+
+The subject carries the short id the way a GitHub issue number does, and the uuid goes in a
+trailer so `git log --grep` has an exact handle:
+
+```
+feat(login): #4 make the sign-in heading brown
+
+Change-Id: 0f3c8a12-9b44-4d2e-8f01-27c6a1d9e5b3
+```
+
+Both ids come from `show`. The type and scope are the usual conventional-commit ones —
+`feat`, `fix`, `style`, `refactor` — with the scope naming the screen or area they were
+looking at, not the file you edited.
+
+More:
+
+```
+fix(booking): #7 stop the date picker closing on the first click
+style(nav): #12 tighten the spacing around the logo
+```
+
+Reverting one later is then:
+
+```bash
+git revert $(git log --grep="Change-Id: <uuid>" --format=%H -1)
+```
+
+## Finishing
+
+`done` records the branch and commit that closed it, which is what strikes the item through
+on the page it was filed on and tells them where the fix landed. Both default to the
+checkout you are standing in, so run it from there and let it read git:
+
+```bash
+pikku fabric changes done --change-id <id> \
+  --note "What you did, for whoever reads the thread later"
+```
+
+`--branch` and `--head-commit` override them, for the case where the fix landed somewhere
+other than where you are. Never type a sha by hand — one that does not exist points the
+filer at nothing.
+
+An item you decided not to do is not `done`. Say why in the thread and leave it for a human
+to dismiss.
+
+## Scope
+
+Writes need the `changes:project:write` scope on your bearer. `list` and `show` are reads.
+The project comes from the local `pikkufabric.config.json`, so run these from the checkout.

package/skills/pikku-concepts/SKILL.md

@@ -20,7 +20,7 @@ Use this skill as an execution checklist, not reference material.
 1. Discover before editing. Run `pikku doc --ai` for the installed API surface, and the relevant `pikku meta ... --json` for what this project has wired.
 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.
+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 validation. Do not paper over generated errors by editing generated files.
 
 Pikku is a TypeScript framework that separates business logic from transport mechanisms. You define a function once, then wire it to HTTP, WebSocket, queues, schedulers, MCP, CLI, or RPC — without the function knowing how it's being called.
@@ -286,62 +286,22 @@ Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI doc
 
 ## Server Bootstrap
 
-There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+Two ways to start a Pikku app, and the choice is whether you need to own the HTTP server.
 
-**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+**Let Pikku own it** — `pikku dev` and `pikku serve` create the config and singleton services,
+start the server and shut it down cleanly, so you write no bootstrap code at all. Startup and
+shutdown work goes in one exported `pikkuServerLifecycle` (`beforeStart` / `afterStart` /
+`beforeStop`). **Only `dev` and `serve` invoke those hooks** — no deploy runtime does, so anything
+a Workers or serverless stage needs done belongs on the request path that needs it.
 
-`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+**Bootstrap it yourself** — required for Express, Fastify, uWS, Lambda, Cloudflare and Next.js,
+where Pikku is embedded in a server you own. Lifecycle hooks do not run on this path; do the
+startup work in the entrypoint.
 
-```typescript
-// src/lifecycle.ts
-import { pikkuServerLifecycle } from '@pikku/core'
-import type { SingletonServices } from '../types/application-types.js'
-
-export const lifecycle = pikkuServerLifecycle<SingletonServices>({
-  beforeStart: async ({ kysely }) => {
-    await runMigrations(kysely)
-  },
-  afterStart: async ({ logger }) => {
-    logger.info('accepting traffic')
-  },
-  beforeStop: async ({ queueService }) => {
-    await queueService.drain()
-  },
-})
-```
-
-Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
-
-**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
-
-**2. Bootstrap it yourself (required for a specific runtime)**
+`pikku validate` warns when a project starts a server by hand *and* depends on no runtime adapter,
+because that means the first path was available and unused.
 
-Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
-
-```typescript
-import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-// Pick your runtime:
-const server = new PikkuFastifyServer(
-  config,
-  singletonServices,
-  createWireServices
-)
-// or: new PikkuExpressServer(config, singletonServices, createWireServices)
-// or: pikkuAWSLambdaHandler(singletonServices)
-// or: PikkuCloudflareHandler(singletonServices)
-// or: pikkuNextHandler(singletonServices)
-
-await server.init()
-await server.start()
-```
-
-**Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
-
-`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
+**`references/bootstrap.md`** has both entrypoints in full.
 
 ## Code Generation
 
@@ -392,91 +352,26 @@ src/
 
 ## What Language You Write In
 
-Three different things in a Pikku project have a human language, and they are
-**not** the same language. Collapsing them is the mistake this section exists to
-prevent, and it has already shipped in a real product — the failure is at the
-bottom.
-
-| Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
-| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
-| **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
-
-### Identifiers are English, and nothing changes that
-
-Not the product's market, not the team's working language, and **not `metaLocale`**.
-A German medical practice, an Arabic marketplace and a Japanese logistics tool
-all get `getOverview`, `AttentionStripe`, `case`, `event`.
-
-This is not linguistic preference, it is mechanics. Identifiers are the surface
-every other tool binds to: the generated `#pikku/*` clients, `pikku info` and
-`pikku meta`, the RPC map a scenario's `actor.invoke` is typed over, the
-generated SQL types, every skill and every agent that ever picks the project up.
-A `vorgang` table types as `Vorgang` in Kysely and reads as noise to everyone who
-did not name it, and unlike a string it cannot be translated later — renaming an
-identifier is a migration, not an edit.
-
-### Meta follows `metaLocale`, and that is what the field is for
-
-```json
-{ "metaLocale": "de" }
-```
-
-Meta is the one part of a project the **Pikku Console** renders back to a human.
-A team reviewing their own functions, features and scenario reports in the
-Console is reading meta and nothing else, so a team whose working language is
-German should be able to read their Console in German. That is the entire reason
-the field exists.
-
-Read it before you author meta, and write descriptions, titles and templates in
-it. Absent, it is `en`. It is a BCP-47 tag (`en`, `de`, `pt-BR` — a hyphen, not
-an underscore), and the CLI rejects anything else by name.
-
-`metaLocale` is **not** licence to rename anything. `metaLocale: "de"` buys a German
-`description: 'Zeigt die Arbeitsliste'` on a function still called
-`getWorklist`.
-
-### Product UI language lives in the catalogue, and only there
-
-What the app says to its users is a translation concern, not a code concern. It
-belongs in `messages/<locale>.json`; `pikku-i18n` owns the details. The one rule
-worth repeating here: **`baseLocale` in `project.inlang/settings.json` stays
-`en`.** It names the message _source_ — the catalogue every other language is
-cloned from and translated against — so a project that sets it to anything else
-has no English catalogue to translate from and can never gain a second language
-without re-authoring every key.
-
-### The failure this comes from
-
-An agent was asked to build a doctor's portal for a German practice. The brief
-said "the entire UI is German, no English strings visible anywhere". The agent
-read one sentence about the product's users as an instruction about the
-codebase, and produced:
-
-- `project.inlang/settings.json` with `baseLocale: "de"` and `locales: ["de"]`,
-  no `en.json` at all — which silently broke `--add-locale` forever
-- RPC functions `getUebersicht` and `getPatientendetail`
-- React components `Zeitstrahl` and `AufmerksamkeitStreifen`
-- database tables `vorgang` and `ereignis`, with German columns
-
-Every one of those is wrong, and the brief was satisfied by none of them: a
-German UI needs German _messages_. What that project actually wanted was three
-settings, each on its own axis:
-
-```jsonc
-// project.inlang/settings.json — the message source stays English
-{ "baseLocale": "en", "locales": ["en", "de"] }
-
-// apps/app/src/i18n/active.json — what a first-time visitor opens in
-{ "defaultLocale": "de" }
-
-// pikku.config.json — the language the team reads their Console in
-{ "metaLocale": "de" }
-```
-
-Identifiers stay English throughout. When a brief tells you the product speaks a
-language, it is telling you about axis three and nothing else.
+Three different things in a Pikku project have a human language, and they are **not** the same
+language. Collapsing them has already shipped in a real product:
+
+| Axis            | Covers                                                                        | Decided by                                     |
+| --------------- | ----------------------------------------------------------------------------- | ---------------------------------------------- |
+| **Identifiers** | Function, component, type and file names; tables and columns; commit messages | Nothing. **Always English.** There is no setting |
+| **Meta**        | Prose authored inside the code — `description`, `title`, step `template`      | `metaLocale` in `pikku.config.json` (default `en`) |
+| **Product UI**  | Every string the app shows a user                                             | `messages/<locale>.json`, and `active.json`'s `defaultLocale` |
+
+Identifiers are the surface every other tool binds to — the generated clients, the RPC map a
+scenario is typed over, the SQL types — and unlike a string an identifier cannot be translated
+later: renaming one is a migration. `metaLocale` exists so a team can read their own Console in
+their own language; it is not licence to rename anything. And `baseLocale` in
+`project.inlang/settings.json` stays `en`, because it names the message *source* every other
+language is cloned from.
+
+**When a brief tells you the product speaks a language, it is telling you about the third axis and
+nothing else.** `references/language.md` has the three settings that satisfy such a brief, and the
+build that read one sentence about a product's users as an instruction about its codebase — German
+RPC names, German tables, and no English catalogue to ever translate from.
 
 ## Environment Variables