@pikku/skills 0.12.35 → 0.12.38

package/skills/pikku-build/SKILL.md

@@ -24,7 +24,6 @@ agent:
         command: pikku knowledge validate
       - id: typechecks
         command: pikku all --tsc-summary
-
 ---
 
 # Build on Pikku
@@ -45,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
 
@@ -63,6 +64,24 @@ generated code depends on, and on a fresh scaffold **every command that touches
 codegen fails until it has run**, including ones you would reasonably reach for
 while still planning. Those failures look alarming and are nothing but this.
 
+## Start from what you were handed
+
+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." 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.
+
+Neither is the app. When the conversion compiles, come back here and carry on
+in the mode the request calls for — App by default — planning milestones around
+what the user wants to do with the API or the workflow, and reaching the
+generated functions through `ref()`.
+
 ## What holds in every mode
 
 - **The branch and the diff are the contract.** A reviewer sees real, compiled,
@@ -86,6 +105,75 @@ while still planning. Those failures look alarming and are nothing but this.
   `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
@@ -494,6 +516,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 +556,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 +678,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 +851,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/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/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/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

@@ -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.
@@ -214,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: