@pikku/skills 0.12.37 → 0.12.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.37",
+  "version": "0.12.39",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-addon/SKILL.md

@@ -359,6 +359,36 @@ export const myFunc = pikkuFunc({
 })
 ```
 
+### Wrap an addon function only to reshape it
+
+A screen that shows the addon's data as the addon returns it calls the addon
+function itself: name it in `wireAddon({ expose: ['listTodos'], auth: true })`
+and the frontend calls `rpc.invoke('todos:listTodos', …)` (over HTTP,
+`POST /rpc/todos:listTodos` with `{ "data": … }`), still behind the session.
+Use `ref('todos:listTodos')` on an HTTP or MCP wiring only when the addon needs
+a route of its own. Don't write an app function that calls `rpc.invoke` and
+returns the result unchanged: it's a second name and a second schema for the
+same thing, and it drifts. `expose: true` exposes only what the addon itself
+declared `expose: true` — an OpenAPI-generated addon declares none, so list
+the names.
+
+Write your own function when the app needs the data narrowed, typed, or
+combined (a flag the upstream sends as `"0"`, a total summed from several
+calls, one field out of fifty), or when the app adds a permission of its own.
+`wireAddon`'s `scopes` gate every function in the addon at once, and a wiring
+carries middleware, not permissions, so a rule on one addon function lives in
+the `permissions` of an app function that calls it. An addon called with the
+user's own credential is already limited upstream to what that user may do, so
+a data-aware `pikkuPermission` repeating that check (may they read *this*
+invoice?) adds nothing. A session-only `pikkuAuth` (a role, a tier) is still
+worth it: it can be checked before any input exists, so the functions a user
+can't call drop out of the tools an MCP client, an agent or a workflow is
+offered, instead of failing upstream when called. Name it for what the screen means
+(`getMyProfile`), not after the upstream operation (`usersRetrieveInfo`), and
+give it an `output:` schema of only what the app uses. For an OpenAPI-generated
+addon this matters more: its outputs mirror the upstream's loose, oversized
+payloads, and the wrapper is where they become the app's own shape.
+
 ### Wire to HTTP
 
 ```typescript

package/skills/pikku-addon/references/openapi.md

@@ -13,67 +13,81 @@ A JSON or YAML document with a top-level `openapi` key (3.x) or `swagger` key
 (2.0), and a `paths` object. A URL ending in `openapi.json`, `swagger.json` or
 `.yaml` is almost always one; open it and check the key before generating.
 
-## 1 — Put the spec in the repo
+## 1 — Look at the spec first
 
-`--openapi` reads a local path, not a URL. Download it to `specs/`, where it
-stays as the record of what the addon was generated from:
+`--openapi` takes a path or a URL. A spec published only to signed-in callers
+takes the key the way the API reads it: `--openapi-header "NAME: value"`
+(repeatable), or in the URL's query string when the API reads it there
+(Dolibarr's explorer takes `?DOLAPIKEY=`). A 401 while fetching says which.
 
-```bash
-mkdir -p specs
-curl -fsSL <url> -o specs/<name>.openapi.json
-```
+The generator warns loudly when the spec has fewer than five operations, or only
+auth routes. That is almost always the public half of a spec that shows more
+to an authenticated caller — fetch it again with the key, don't build on it.
 
-## 2 — Generate
+Keep a copy in `specs/` as the record of what the addon was generated from.
 
-Inside an app, the addon is a workspace package under `packages/`:
+## 2 — Generate, from the app's root
 
 ```bash
-bunx --bun pikku new addon <name> --openapi specs/<name>.openapi.json --dir packages
+bunx --bun pikku new addon <name> --openapi <path-or-url>
 ```
 
-This writes `packages/addon-<name>` as `@pikku/addon-<name>`, installs it and
-builds it. Inside a workspace the generated test app depends on it as
-`workspace:*`, so nothing is published.
-
-| Flag                          | When                                                                                      |
-| ----------------------------- | ----------------------------------------------------------------------------------------- |
-| `--credential apikey\|bearer` | The spec's `securitySchemes` is an API key or a bearer token — each user brings their own |
-| `--credential oauth2`         | The spec's `securitySchemes` is OAuth2                                                    |
-| `--auth-config <file>`        | The spec gets auth wrong or leaves it out: a custom header, a delegated login endpoint    |
-| `--mcp`                       | The operations should also be MCP tools                                                   |
-| `--camel-case`                | The API's property names are snake_case and the app's are not                             |
-
-Read the spec's `securitySchemes` to pick the credential. Leave the flag off
-only when the API really takes no auth.
+One command. Inside an app it writes `packages/addon-<name>` as
+`@pikku/addon-<name>`, then installs it into the app:
+
+- the dependency in the root and the functions `package.json`
+- `src/addons/<name>.addon.ts` — `wireAddon` with `auth: true` and an explicit
+  `expose` list (every operation in per-user modes, only the `GET`s behind a
+  shared secret)
+- the auth wiring in `src/auth.ts` for the chosen mode
+- `<NAME>_BASE_URL` in `.env`
+
+and then runs install and the addon's build. `--no-install` generates the
+package alone.
+
+| Flag                                         | When                                                                             |
+| -------------------------------------------- | -------------------------------------------------------------------------------- |
+| `--auth user` (default)                      | Each user brings their own credential                                            |
+| `--auth shared`                              | One secret behind every user; locally it goes in `.env`                          |
+| `--auth none`                                | The API really takes no auth                                                     |
+| `--credential apikey\|bearer\|basic\|oauth2` | Override what the spec's `securitySchemes` declares                              |
+| `--auth-config <file>`                       | Users sign in with their upstream login, or the spec gets auth wrong             |
+| `--tags a,b` / `--include` / `--exclude`     | Keep part of a huge spec: tags, or globs on operationId, `/path`, `METHOD /path` |
+| `--mcp`                                      | The operations should also be MCP tools                                          |
+| `--camel-case`                               | The API's property names are snake_case and the app's are not                    |
+
+The mode comes from the spec unless a flag says otherwise. A spec with no
+machine-readable auth is refused rather than guessed: pass one of the flags the
+error names. Which mode fits, and the auth-config format, are in the
+`pikku-build` skill's `references/openapi.md`.
 
 ## 3 — Check what was generated
 
 ```
 packages/addon-<name>/
+├── <name>.svg                    # placeholder icon; replace with the real one
 ├── src/<name>-api.service.ts     # one fetch wrapper, reads <NAME>_BASE_URL
-├── src/<name>.variable.ts        # <NAME>_BASE_URL, an enum of the spec's servers
+├── src/<name>.variable.ts        # <NAME>_BASE_URL: z.string().url(), the first server as default
 ├── src/functions/<op>.function.ts
 ├── src/functions/<op>.schemas.ts # the op's zod schemas — never import #pikku here
 └── src/index.ts                  # re-exports every function
 ```
 
-`<NAME>_BASE_URL` is an enum of the spec's `servers`. When those are
-placeholders or a per-tenant host (`https://{tenant}.example.com`, or a server
-list that is only an example), change its schema in `src/<name>.variable.ts`
-to `z.string().url()` so each deployment sets its own.
-
-## 4 — Wire it into the app
+An operation whose spec gives no response, or one too vague to validate
+against, outputs `z.unknown()`. Tighten it in `<op>.schemas.ts` once §6 shows
+what the API really returns.
 
-```typescript
-// src/addons.ts
-import { wireAddon } from '#pikku/addon'
+An upstream 401 on a per-user credential throws `CredentialRejectedError`
+(403, `reauth: 'sign-in' | 'connect'`); a UI shows the matching screen again
+rather than a generic error.
 
-wireAddon({ name: '<name>', package: '@pikku/addon-<name>' })
-```
+## 4 — Call it from the app
 
-Then call operations by reference — `ref('<name>:<operationFn>')` in a
+Operations are reached by reference — `ref('<name>:<operationFn>')` in a
 workflow, agent tool or HTTP wiring — the same way as any other addon. See
-"Consuming an Addon" in the skill.
+"Consuming an Addon" in the skill. An exposed operation is also callable from
+the frontend at `POST /rpc/<name>:<operationFn>` with a body of
+`{ "data": { … } }`, as the signed-in user.
 
 ## 5 — Verify
 
@@ -92,6 +106,23 @@ another shared package. Codegen then reads the app's
 schemas with the wrong copy and fails on schemas that are correct. Pin one
 version for the whole install, as the finding says, and reinstall.
 
+## 6 — Check the spec against the real API
+
+Specs are often wrong, and the generated schemas repeat every mistake. Before
+building on the addon:
+
+- **Call the reads you can.** The `GET`s the credential can reach, following ids
+  from lists into retrieves. Writes only if the user opts in.
+- **Fix the addon, not the app**: the schema in the op's `<op>.schemas.ts`, or the
+  request shape in `src/<name>-api.service.ts`. Then rebuild it.
+- **List each mismatch in `packages/addon-<name>/SPEC-ISSUES.md`**: a title and a
+  short description. No credentials or customer data.
+
+Then tell the user in one line: "FYI, the spec deviates from the real API in
+N ways: [SPEC-ISSUES.md](…)". Add to the file whenever a later call disagrees
+with its schema. Ask before sending it to the API's maintainers, because an issue
+on their tracker is a public post.
+
 ## Then
 
 Go back to the mode you were building in (`pikku-build`). The addon is a

package/skills/pikku-auth/references/better-auth.md

@@ -307,7 +307,7 @@ singleton a 403 that leaves no platform user behind.
 
 ```typescript
 pikkuDelegatedAuth({
-  authenticate: async ({ email, password, apiKey }) => upstream.login(...),
+  authenticate: async ({ login, email, password, apiKey }) => upstream.login(...),
   storeCredential: (userId, identity) =>
     credentialService.set('acme', identity.credential, userId),
   defaultRole: 'member',
@@ -318,7 +318,10 @@ pikkuDelegatedAuth({
 ```
 
 `POST /sign-in/delegated` forwards the credentials the user already has to
-`authenticate`. On success it JIT-provisions a real user row (email-keyed and
+`authenticate`. The body takes `email`, `login` or `username` with `password`
+(or `apiKey`); whichever identifier was sent reaches `authenticate` as
+`credentials.login`, and `email` as well when it was one. Upstreams that sign in
+with a username — most ERPs — need nothing more. On success it JIT-provisions a real user row (email-keyed and
 `emailVerified` — the upstream just verified them), links it via an `account`
 row (`providerId: 'delegated'`, `accountId: externalId`), persists the upstream
 token **before** minting the session, and returns a normal session cookie.
@@ -333,6 +336,18 @@ a warning and the user still gets in.
 `storeCredential` failing, by contrast, **fails the sign-in**: every proxied
 call would be dead anyway.
 
+An upstream user with no email gets one made up from the login, and the
+identity says so with `syntheticEmail: true`. A made-up address never links to
+an existing user row, so it cannot take over someone else's account.
+
+For an addon generated from an OpenAPI spec, none of this is written by hand:
+`pikku new addon --openapi … --auth-config <file>` generates
+`authenticate<Name>Upstream` in the addon and wires this plugin, the stored
+credential and the actor credentials into `src/auth.ts`. The config format is
+in the `pikku-build` skill's `references/openapi.md`. When the upstream later
+refuses the stored token, the addon throws `CredentialRejectedError` (403,
+`reauth: 'sign-in'`): the UI shows the sign-in again.
+
 #### `pikkuFabric()` — control-plane operator sign-in
 
 ```typescript

package/skills/pikku-build/SKILL.md

@@ -44,12 +44,14 @@ plus more effort" — it is App plus a deliberate surface checklist, so read the
 base first and follow it in full rather than blending the two into one plan.
 
 The supporting references belong to whichever mode sends you to them:
-`references/multi-app.md` (a second frontend), `references/design.md` (offering
-to mock the screens first, committing to a design direction, and judging whether
-the screens realise it — read before the first screen is built, not after the
-last), `references/theming.md`
+`references/multi-app.md` (a second frontend), `references/design.md` (showing
+a picture of the screens first, committing to a design direction, and judging
+whether the screens realise it — read before the first screen is built, not
+after the last), `references/theming.md`
 (authoring the theme),
-`references/ship.md` (deploying, and the Fabric-readiness contract).
+`references/ship.md` (deploying, and the Fabric-readiness contract),
+`references/openapi.md` (an app on an OpenAPI spec: the auth mode, the
+auth-config format, and the sign-in or connect screen it implies).
 
 ## Bootstrap before anything else
 
@@ -67,10 +69,10 @@ while still planning. Those failures look alarming and are nothing but this.
 When the request comes with a file or a URL, look at it before planning
 anything. Two kinds are converted first and then built on:
 
-| Handed                                                                                                              | Say, then do                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| An **OpenAPI / Swagger spec** — top-level `openapi` or `swagger` key, a `paths` object                              | "This is an OpenAPI spec — I'll turn it into an addon first." Follow the `pikku-addon` skill's OpenAPI reference. |
-| An **n8n export** — an object with `nodes` and `connections`, an array of them, or a `{ workflows: [...] }` wrapper | "This is an n8n workflow — I'll import it first." Follow `pikku-n8n-import`.                                      |
+| Handed                                                                                                              | Say, then do                                                                                                                                                          |
+| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| An **OpenAPI / Swagger spec** — top-level `openapi` or `swagger` key, a `paths` object                              | "This is an OpenAPI spec — I'll turn it into an addon first." Pick the auth mode in `references/openapi.md`, then follow the `pikku-addon` skill's OpenAPI reference. |
+| An **n8n export** — an object with `nodes` and `connections`, an array of them, or a `{ workflows: [...] }` wrapper | "This is an n8n workflow — I'll import it first." Follow `pikku-n8n-import`.                                                                                          |
 
 Say it at once, in one line, and start: this is the obvious first move, not a
 question for the user. Generate the whole spec, however large.
@@ -103,6 +105,75 @@ generated functions through `ref()`.
   `pikku knowledge plan progress` measures the build against it from the
   generated meta. You plan it and you build it; what you never do is edit the
   plan afterwards to match what you built — that is grading yourself.
+- **Print the links whenever the stack comes up, and in every hand-over.** Full,
+  clickable URLs, with the ports taken from what `bun run dev` actually printed:
+  - **App** — the frontend's URL (`http://localhost:7104` in the template; each
+    frontend in `pikkufabric.config.json` has its own port)
+  - **API** — `http://localhost:3000`
+  - **Console** — `http://localhost:3000/console`, plus a deep link to each
+    page that shows what this turn produced (the paths are below)
+
+  A person who has to go hunting for the port assumes the app did not start.
+
+## Keep a BUILD-REPORT.md
+
+Whenever pikku or a skill costs you time — a command that failed on a fresh
+tree, a skill that described a flag the CLI does not have, generated code you
+had to fix by hand — add an entry to `BUILD-REPORT.md` at the repo root as it
+happens: what you ran, what you expected, what happened, and the workaround.
+Leave out secrets, tokens and customer data.
+
+At hand-over, show the file and ask the user whether to send it. Only with
+their okay, send each entry with `pikku fabric report --stdin` (JSON on stdin;
+`"kind": "product"` when pikku behaved wrongly, `"kind": "harness"` with
+`"skill"` and `"passage"` when a skill misled you). The `pikku-report` skill
+has the fields. When the CLI is not signed in to Fabric, the report is queued
+locally rather than sent: say so, and that `pikku fabric findings flush` sends
+the queue once they sign in. Do not retry or file it twice.
+
+## Who you are talking to
+
+The prompt asks first how technical the person is: **not technical**,
+**technical, no code**, or **developer** (the default when unsaid). Whenever the
+build makes or changes something the console can show, give the
+`http://localhost:<port>/console/...` link instead of describing it.
+
+Until the app is deployed that is the local open-source console, on the port
+`pikku dev` printed. Once it is on Fabric, link the Fabric console for the stage
+you are talking about instead; the `pikku-fabric` skill says which.
+
+| Level              | Links                       | Code in the conversation |
+| ------------------ | --------------------------- | ------------------------ |
+| Not technical      | Product pages only          | Never                    |
+| Technical, no code | Product and technical pages | Never                    |
+| Developer          | Product and technical pages | As normal                |
+
+"Never" includes snippets and command lines; say what changed in the person's
+words and link to where they can see it.
+
+**Product pages** — the only ones a non-technical person gets:
+
+| Shows                 | Path                                                                       |
+| --------------------- | -------------------------------------------------------------------------- |
+| Knowledge, plans      | `/console/knowledge`, `/console/knowledge?id=<note path>`                  |
+| Personas              | `/console/personas`, `/console/virtual-users?persona=<id>`                 |
+| Roles and permissions | `/console/roles`, `/console/scopes` (only with `@pikku/addon-admin` wired) |
+| Scenarios and runs    | `/console/scenarios?id=<id>`, `/console/scenarios?view=runs&run=<run id>`  |
+| Workflows             | `/console/workflow?id=<id>`                                                |
+| Agents                | `/console/agents`, `/console/agents/playground?id=<agent id>`              |
+
+**Technical pages** — never for a non-technical person: `/console/overview`,
+`/console/functions`, `/console/surface`, `/console/database`,
+`/console/changes`, `/console/wires/http`, `/console/wires/channel`,
+`/console/wires/mcp`, `/console/wires/cli`, `/console/wires/gateway`,
+`/console/async/scheduler`, `/console/async/queue`, `/console/async/trigger`,
+`/console/runtime`, `/console/emails`, `/console/webhooks`, `/console/secrets`,
+`/console/variables`, `/console/security`, `/console/auth-providers`,
+`/console/addons`, `/console/analytics`, `/console/credentials`,
+`/console/users`, `/console/audit`, `/console/flags`, `/console/scorers`.
+
+These come from `packages/console/src/App.tsx`; do not link a path that is not
+listed here.
 
 ## What NOT to do
 

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

@@ -24,6 +24,9 @@ project shaped so `pikku fabric init` later adopts it with zero rework.
    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
 
@@ -62,11 +65,18 @@ in one message. Then stop; do not interview the user.
   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, as a question and not a gate: one HTML page mocking the main
-  screens, a few minutes, far cheaper to change than built screens. If they say
-  yes, `references/design.md` owns what to make and what it then binds — the
+  this same round, with yes marked recommended, in the words of
+  `references/design.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, `references/design.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. If they say no, build.
+  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 milestone 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
@@ -343,8 +353,9 @@ What a milestone is:
   persona. If you cannot write the gherkin, you cannot build it yet — that is a
   `questions/` note, not a milestone.
 
-If §1's screen mock was made and approved, the milestones are read off it: every
-screen on that page belongs to some milestone, and a screen no milestone builds
+If §1's screen mock was made — approved, or drawn because nobody answered — the
+milestones are read off it: every screen on that page belongs to some milestone,
+and a screen no milestone builds
 is a hole in this plan. Say which milestone covers which screen.
 
 How to order them:
@@ -363,8 +374,17 @@ How to order them:
 Number the files (`01-…`, `02-…`) so the order is visible in the tree. Then
 `knowledge index && knowledge validate` before you write a line of code.
 
-**Show the user the list before building.** This is the last cheap moment to
-reorder — after §6 the migrations are numbered and the order is concrete.
+**One approval, then build to the end.** Show the picture of the screens and
+the milestone list together, in one message, as the plan: which milestone builds
+which screen, in what order. That is the only approval you ask for. It is the
+last cheap moment to reorder: after §6 the migrations are numbered and the order
+is concrete.
+
+Once they approve it, or don't answer, build every milestone in order without
+stopping to ask between them. Post one line as each milestone closes, with its
+console links, 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 — one milestone at a time, before you build it
 
@@ -399,6 +419,8 @@ no plan, and everything after the current milestone is still allowed to move.
 
 ## 6. Implement milestones, one at a time
 
+All of them, one after another, on the one approval from §5.
+
 **Per milestone** — plan it (§5a), set its note to `status: dispatched`, do the
 six steps, close it out (§6a), set it to `built`. Do not start the next one
 until §6a passes, §7 is green for this one _and §7a shows its functions
@@ -498,8 +520,8 @@ Rules that are not optional:
   `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
+  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
@@ -544,7 +566,7 @@ 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
+_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

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

@@ -54,13 +54,18 @@ allowed is landing on one because it was nearest to hand.
 ## Offer to draw the screens before you build them
 
 Before the first milestone, **ask** whether they want to see the screens first.
-One question, in §1's round, not a gate of its own:
+One question, in §1's round, not a gate of its own, with yes marked
+recommended every time:
 
-> Want me to mock the main screens as a page you can look at before I build
-> anything? It takes a few minutes and it is much cheaper to change a picture
-> than a built screen.
+> Before I build, shall I show you a picture of the main screens so you can say
+> "yes, like that" or "no, move this"? (Recommended: it takes a few minutes and
+> changing a picture is much cheaper than changing a built app.)
 
-If they decline, build; the direction in words is enough to be accountable to.
+Never say "mock", "mockup" or "wireframe" to the person; most people do not
+know the words. They stay the technical terms in this file only.
+
+If they do not answer, draw it anyway and build from it. Only an explicit no
+skips it; then build, and the direction in words is enough to be accountable to.
 If they accept, this is the cheapest decision in the project — a picture of eight
 screens costs a fraction of eight built screens, and it is the only point where
 "that is not what I meant" is free.
@@ -105,6 +110,12 @@ first. Whatever your host offers for showing a page is how you show it: an
 Artifact, a file they open, a preview server. The page is the deliverable; how it
 gets in front of them is not this file's business.
 
+**Say it is a picture, on the page and in the message.** A well-drawn screen
+reads as a finished app, and a person who thinks it is already built asks why
+nothing works. The page opens with a banner that stays in view: "A picture of
+the planned screens. Nothing is built yet." The message that shows it says the
+same, then says what happens next: "Once you're happy with it, I'll build it."
+
 Write it to `knowledge/decisions/design/screens.html` and treat it as **source of
 truth for the screens** once they approve it. That has consequences worth
 stating:

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

@@ -63,86 +63,61 @@ Worth a scenario each, because they are two different claims: that a mechanic ca
 *see* the invoices nav item, and that their call to an invoices RPC is *refused*. The
 second is the one that catches a `permissions` field nobody wired.
 
-## The clone
+## The second app
 
 ```bash
-cp -R apps/app apps/admin
-rm -rf apps/admin/node_modules apps/admin/src/paraglide
+pikku new app admin --serves staff --personas manager,mechanic
 ```
 
-`src/paraglide` is compiled from `messages/` by the Vite plugin on first run;
-copying it forward ships one app's compiled strings inside another.
-
-Then, in order:
-
-### 1. `apps/admin/package.json`
-
-- `name` → `@project/admin`
-- `dev` and `preview` ports → `7105`. Every frontend needs its own, or the second
-  one fails to bind and the dev runner looks like it hung.
-- the `--tsBuildInfoFile` path inside the **`tsc` script** → `admin-tsc.tsbuildinfo`.
-  In this template it is a CLI flag on that script (`tsc --noEmit --incremental
-  --tsBuildInfoFile node_modules/.cache/app-tsc.tsbuildinfo`), not a
-  `compilerOptions` entry — `tsconfig.json` needs no change. Left alone, the two
-  apps fight over one incremental cache and you get type errors that vanish on a
-  clean build: an hour of debugging for a one-word edit.
-
-### 2. `pikkufabric.config.json`
-
-This file is the source of truth for what apps exist, and it is read whether or
-not you ever deploy to Fabric.
-
-```json
-{
-  "projectId": "__PROJECT_ID__",
-  "frontends": {
-    "app": {
-      "cwd": "apps/app", "primary": true, "deploy": true, "kind": "ssr",
-      "dev": { "command": ["bun", "run", "dev"], "port": 7104, "healthPath": "/" },
-      "serves": "tenant",
-      "personas": ["visitor", "chidi"]
-    },
-    "admin": {
-      "cwd": "apps/admin", "primary": false, "deploy": true, "kind": "ssr",
-      "dev": { "command": ["bun", "run", "dev"], "port": 7105, "healthPath": "/" },
-      "serves": "owner",
-      "personas": ["amina", "bilal"]
-    }
-  }
-}
-```
-
-Two things to fix while you are in here, not just add:
-
-- **The shipped `app` entry may say `["yarn", "dev"]`** while the rest of the
-  project is driven with bun. Correct it. A frontend that starts under a package
-  manager the project does not use is a failure that only appears on someone
-  else's machine.
-- **`serves` and `personas` name real personas.** Every persona should appear
-  under exactly one frontend. A persona listed nowhere is a person with no way
-  in, and that is a design bug worth seeing now rather than at review.
-
-### 3. The dev runner
-
-`dev.mjs`, under the project's scripts directory, spawns `@project/app` **by
-name** and will silently never start your second app — the frontend simply is not
-there, with no error to explain it.
-
-Make it read the `frontends` map and spawn one child per entry, rather than
-adding a second hardcoded line. Two sources of truth for "which apps exist" is
-the drift this whole file is trying to avoid.
-
-### 4. `pikku.config.json` → `environments`
-
-`local.appUrl` points at one app. Add an environment per frontend (`local`,
-`local-admin`) so the browser scenario pass can drive either one. A browser
-scenario run against the wrong `appUrl` fails on a missing element and reads like
-a UI bug rather than a config one.
-
-### 5. Re-run `bun install`
-
-`apps/*` is already globbed in the root workspaces, so this just links the new
-one.
+One command does every step this section used to list by hand: it fetches
+`pikkujs/starter-template`'s `apps/app`, re-points its `package.json` at the
+new name, its own dev/preview port and its own `--tsBuildInfoFile`, stamps
+`app: '<slug>'` onto each named persona in `definePersonas({…})`, adds the
+`frontends` entry, and re-runs `bun install`.
+
+**It scaffolds from the starter template, not from the app you already have.**
+Copying the working app drags its screens, routes and nav into an audience that
+never asked for them, and the first hour in the new app goes on deleting
+someone else's product.
+
+`--template <source>` scaffolds from something else — any giget source, or a
+path inside the repo for an offline or vendored copy. `--install false` skips
+the install when you are batching several.
+
+**The `--tsBuildInfoFile` edit is the one that used to bite.** Two apps sharing
+one incremental cache produce type errors that vanish on a clean build: an hour
+of debugging for a one-word edit. It is handled now, but it is why you should
+not copy by hand.
+
+### What it refuses, and why that is the valuable part
+
+The scaffolding is five file edits. Getting the audience wrong is a whole
+second app nobody needed, so the command will not create one when:
+
+- **`--serves` names a surface.** `dashboard`, `portal`, `admin`, `console`,
+  `ui` and friends say nothing — every frontend is an app. Name the people in
+  their own word: staff, customer, supplier, patient.
+- **An existing app already serves that audience.** People sharing an audience
+  share ONE app and differ by nav and permitted actions. A new app is for a
+  group the first app is not for.
+- **A named persona already signs into another app.** A person signs into one
+  app; move them out first if they really belong here.
+- **The slug is what the plan calls an app that already exists.** The plan's
+  FIRST app is the one the project starts with — only the apps after it get
+  created.
+- **A persona is not in `definePersonas({…})`.** The app is built around who
+  signs into it, so it is not created for people who do not exist yet.
+
+It also repairs its own half-states: a run that died between writing the
+directory and writing the config entry leaves one without the other, and
+neither survives alone, so the next run clears the remains and carries on
+rather than sending you in to do the surgery by hand.
+
+### What it does NOT do
+
+It stops after `bun install`. Serving the new app — a reverse proxy, a
+supervisor, a dev runner, a deploy target — belongs to whatever is hosting it.
+On a plain checkout, `bun --filter @project/<slug> dev` is enough.
 
 ## Sessions across two origins