@pikku/skills 0.12.37 → 0.12.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.37",
+  "version": "0.12.38",
   "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/openapi.md

@@ -0,0 +1,119 @@
+# An app on top of an OpenAPI spec
+
+The spec becomes an addon first — the `pikku-addon` skill's
+`references/openapi.md` covers generating, verifying and checking it against
+the real API. This reference is the decision that shapes the app around it:
+**whose credentials reach the upstream**, and what the person signs in with.
+
+## Pick the auth mode
+
+| The upstream…                                                            | Mode              | Command                       | Who signs in, and how                                   |
+| ------------------------------------------------------------------------ | ----------------- | ----------------------------- | ------------------------------------------------------- |
+| Is where the users already have accounts, and has a login endpoint      | Delegated         | `--auth-config <file>`        | Users sign in with their upstream login; no new account |
+| Takes a per-user API key, bearer token or basic auth                     | Per-user key      | (the default)                 | App account, then a Connect screen for the key          |
+| Uses OAuth2                                                              | Per-user OAuth    | (the default)                 | App account, then Connect via the OAuth consent         |
+| Is used on everyone's behalf with one key the business owns              | Shared secret     | `--auth shared`               | App account only; the key is a secret                   |
+| Takes no auth                                                            | None              | `--auth none`                 | App account only                                        |
+
+Per-user is the default because the upstream then enforces each person's own
+permissions. A shared secret acts with one identity for everyone, so the
+install exposes only its reads; widen that deliberately, never by default.
+
+The mode comes from the spec's `securitySchemes` unless a flag overrides it.
+Many real specs describe auth only in prose. The generator then refuses rather
+than guessing. Read the API's docs and pass the flag that is true.
+
+**Delegated is the right call whenever the upstream is the system of record for
+who the users are** — an ERP, a CRM, a helpdesk the whole team already logs in
+to. The app then has no separate sign-up, the upstream token is stored per user
+at sign-in, and every call acts as that user.
+
+## The auth-config file
+
+JSON, passed with `--auth-config`. Every field is optional except where noted.
+
+```json
+{
+  "headerName": "DOLAPIKEY",
+  "headerFormat": "raw",
+  "extraHeaders": { "Origin": "https://tenant.example.com" },
+  "delegated": {
+    "loginPath": "/login",
+    "loginMethod": "post",
+    "credentials": ["login", "password"],
+    "fields": { "login": "login", "password": "password" },
+    "encoding": "json",
+    "tokenPath": "success.token",
+    "expiresAtPath": "success.expires",
+    "identity": { "path": "/users/info", "method": "get" },
+    "claims": {
+      "source": "identity",
+      "externalId": "id",
+      "email": "email",
+      "name": ["firstname", "lastname"],
+      "role": "admin",
+      "tenantId": "entity"
+    },
+    "emailTemplate": "{login}@{host}",
+    "roles": { "1": "dolibarr-admin" }
+  }
+}
+```
+
+Top level — how every call authenticates:
+
+| Field          | Meaning                                                                                              |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `headerName`   | The header the API reads the token or key from. Setting it alone means a per-user API key            |
+| `headerFormat` | `raw` sends the bare value, `bearer` prefixes `Bearer `. Default: bearer for `Authorization`, else raw |
+| `extraHeaders` | Static headers on every request, login included — for upstreams that route on a header               |
+| `delegated`    | Present when users sign in with their upstream login                                                 |
+
+`delegated`:
+
+| Field            | Meaning                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `loginPath`      | Required. The spec-relative login operation                                                               |
+| `loginMethod`    | Default `post`                                                                                            |
+| `credentials`    | What the sign-in form collects: `login` (a username or email), `email`, `password`, `apiKey`. Default `["email","password"]` |
+| `fields`         | The upstream's name for each credential, e.g. `{ "login": "username" }`                                  |
+| `encoding`       | `json`, `form` or `query` — how the login fields travel. Default `json`                                   |
+| `apiKeyHeader`   | The header an `apiKey` credential is sent in. Default `x-api-key`                                         |
+| `tokenPath`      | Required. Dot-path to the token in the login response                                                     |
+| `expiresAtPath`  | Dot-path to an epoch-seconds expiry. Defaults to the JWT's `exp` when claims come from the JWT            |
+| `identity`       | An operation that returns the signed-in user, called with the new token — for logins that return only a token |
+| `claims.source`  | `jwt`, `response` or `identity`. Default `identity` when `identity` is set, else `response`               |
+| `claims.*`       | Dot-paths to `externalId`, `email`, `name` (one path or several joined with a space), `role`, `tenantId`  |
+| `emailTemplate`  | Builds an email for an upstream user who has none: `{login}`, `{externalId}`, `{host}`. Such an address never claims an existing user |
+| `roles`          | Maps the raw `claims.role` value onto an app role; an unmapped value gets no role                          |
+
+Check it before building on it: start `pikku dev`, sign in once with
+`POST /api/auth/sign-in/delegated` as a real upstream user, and call an exposed
+operation with the session. A wrong password must be refused. Keep real
+credentials in the environment, never in the config or a test.
+
+What the install wires for delegated mode — `pikkuDelegatedAuth` in
+`src/auth.ts`, the token stored per user, actors carrying it into scenarios — is
+in the `pikku-auth` skill's `references/better-auth.md`.
+
+## The screens
+
+**If the app has a UI, build the sign-in or connect screen that matches the chosen auth mode (Sign in with <X> for delegated, a Connect <X> screen for per-user keys/OAuth, nothing for a shared secret), labelling fields in the upstream's terms (e.g. 'Dolibarr login', not 'Email').**
+
+- **Delegated** — the sign-in page posts to `POST /api/auth/sign-in/delegated`
+  with the fields named in `credentials` (`login` or `username`, `password`).
+  It replaces email sign-up; there is no "create account".
+- **Per-user key or OAuth** — a Connect screen after sign-in, and wherever a
+  call fails with `missing_credential`.
+- A `credential_rejected` error (`CredentialRejectedError`, 403) means the
+  upstream refused the stored token: show the sign-in again (`reauth:
+  'sign-in'`) or the Connect screen (`reauth: 'connect'`), not a generic error.
+
+## Scenarios
+
+A persona that signs in through the upstream needs an upstream credential to
+act with. The install adds `credentials` to `pikkuActor` in `src/auth.ts`, and
+at sign-in each actor stores `ACTOR_CREDENTIAL_<PERSONA>_<NAME>` from the
+environment (e.g. `ACTOR_CREDENTIAL_SALES_REP_DOLIBARR`). Without it every
+scenario step that reaches the upstream fails with `missing_credential`. The
+`pikku-scenario` skill's `references/personas.md` has the details.

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

@@ -16,6 +16,10 @@ failed; a showcase where every surface is a stub has also failed. The bar for
 each surface below: **it does something the app genuinely needs, and a scenario
 proves it.** A cron job that logs "tick" is not a schedule — it is a comment.
 
+Each surface lands with its console link, filtered by the person's level
+(SKILL.md, "Who you are talking to"): a non-technical person sees the workflow
+or agent page, never the queue, scheduler or wire pages behind it.
+
 Budget the extra surfaces at one milestone each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
 

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

@@ -223,9 +223,10 @@ bunx --bun pikku scenario run local --spawn
 
 ## 6. Hand it over honestly
 
-Tell the user, in one short paragraph: what runs, what it is seeded with, and
-that this is a quick build — no knowledge base, no milestones, no design pass,
-access control clicked-through rather than proven.
+Tell the user, in one short paragraph and at their level (SKILL.md, "Who you
+are talking to"), with console links rather than descriptions: what runs, what
+it is seeded with, and that this is a quick build — no knowledge base, no
+milestones, no design pass, access control clicked-through rather than proven.
 
 **Upgrading to a real build is additive, not a rewrite.** If they want it, switch
 to `references/app.md` and do this, in order: