@pikku/skills 0.12.41 → 0.12.43

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -340,6 +340,14 @@ wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 
 After registration, run `yarn pikku all` to generate types for the addon's functions.
 
+In a workspace, add the addon to the dependencies of the package whose file
+calls `wireAddon`, not the repo root. Codegen resolves an addon from the
+package that wires it first and the project root second, the way that
+package's own imports resolve at runtime, and a remote addon's
+`devDependencies` check reads that same package's manifest. If codegen reports
+PKU340, the dependency is missing from the package its message names — do not
+add it at the root to paper over it. `verifiers/addon-workspace` is that layout.
+
 If the addon ships tables, `pikku db generate` then writes one migration per
 addon — named after the package, carrying the addon's own SQL — after Better
 Auth's and the runtime's, so an addon table may reference `user` or a runtime

package/skills/pikku-architect/SKILL.md

@@ -200,6 +200,15 @@ callback, a public URL another system posts to), a queue job, a channel, a sched
 workflow entry point. Those last two are not alternate URLs — they are what the milestone IS, and a
 plan that omits them ships a `status` column nothing advances or a job nobody runs.
 
+A wire is also a constraint on the function's SHAPE, not only an address for it. `wireScheduler`
+takes a function of `void` to `void` — the clock passes nothing and reads nothing back — so a
+function that answers with a report cannot be the one on the clock. One plan here put
+`wire: scheduler` on a nightly collector whose output was the counts a member of staff needed to
+see, and the build had to split it in two: a void shell for the clock, and the exposed collector it
+calls. That was the right answer, but it was a design decision made mid-build because the plan had
+not asked what the wire would accept. Before you write a wire, name what that wire hands the
+function and what it does with the answer; where the two disagree, plan BOTH halves.
+
 `permission` is a SENTENCE, not a role name — "only the person who wrote it can edit it". The roles
 are the engineer's choice; the rule is the part that has to survive being implemented, in the
 function's `permissions` field and never in its body. `null` means open to anyone signed in, and
@@ -259,20 +268,28 @@ cover it — so a role × resource cross product there costs the milestone nothi
 
 ## What makes a plan wrong
 
-`plan set` catches the mechanical failures. These are the ones it cannot:
-
-- **A plan for a different milestone.** The note is about `entries`; the plan builds `projects`.
-  Every entity the note names must appear in a function or a table.
-- **A pass 1 that is a layer, not a slice.** "Pass 1: the data model. Pass 2: the API. Pass 3: the
-  screens." That is three passes of nothing working.
-- **Scenarios that assert the code ran rather than that the person got what they came for.** A
-  scenario proving `saveEntry` returns 200 proves the wire. The one worth planning is the one where
-  a person writes something, comes back, and it is still there. A browser scenario that opens a page
-  and asserts it is still on it proves the route loads and nothing else —
-  `pikku knowledge plan progress` names it as a problem and refuses the milestone.
-- **A permission rule invented here.** If the notes do not say who may do a thing, the answer is
-  `null` with the reason, not a rule you made up. A rule the user never agreed to is one they find
-  out about by being locked out of their own app.
+`plan set` catches the mechanical failures — a missing slot, a bad hash, a pass 1 with no `ui` item.
+Read your draft back against these six questions, which it cannot ask. Each has cost a real
+milestone; **[references/plan-defects.md](references/plan-defects.md)** carries the case behind every
+one, and is worth opening for any question you cannot answer with a flat yes.
+
+1. **Is this a plan for THIS note?** Every entity the note names appears in a function or a table.
+2. **Does pass 1 slice, and does the model fit inside it?** Not "pass 1: the data model, pass 2: the
+   API" — and `model` holds only the tables pass 1 or 2 actually migrates, because the model slot has
+   no passes and a later table is a PROBLEM from the first day.
+3. **Can each scenario actually be performed?** Name the persona; assert what the person got rather
+   than that the code ran; write totals as deltas against a database nobody resets; check that every
+   input the prose describes is a field somebody planned.
+4. **Does something produce every state and field the plan reads?** For each clause of a description,
+   each screen the opening paragraph names, each field you filter or badge on, and each state a
+   scenario waits in — name the function that gets the world there. A producer you are reusing is
+   checked against code that already exists; a producer this milestone is adding is checked against
+   the plan that adds it. What is never allowed is a state with no named producer at all.
+5. **Can two sentences in the plan both be true?** Write a state machine out once as a table in
+   `model`, name who sets and reads every clock in it, and say whether saving a child collection
+   REPLACES it or ADDS to it.
+6. **Did you invent anything?** If the notes do not say who may do a thing, that is `null` with a
+   reason, not a rule you made up.
 
 ---
 

package/skills/pikku-architect/references/plan-defects.md

@@ -0,0 +1,157 @@
+# What makes a plan wrong
+
+`plan set` catches the mechanical failures — a missing slot, a bad hash, a pass 1 with no `ui`
+item. These are the ones it cannot, each carried back from a milestone that shipped it. They are
+grouped by the question that finds them, and the fastest way to use this file is to read the six
+questions and only open the group that worries you.
+
+1. [Is this a plan for THIS note?](#is-this-a-plan-for-this-note)
+2. [Does pass 1 slice, and does the model fit inside it?](#does-pass-1-slice-and-does-the-model-fit-inside-it)
+3. [Can each scenario actually be performed?](#can-each-scenario-actually-be-performed)
+4. [Does something produce every state and field the plan reads?](#does-something-produce-every-state-and-field-the-plan-reads)
+5. [Can two sentences in the plan both be true?](#can-two-sentences-in-the-plan-both-be-true)
+6. [Did you invent anything?](#did-you-invent-anything)
+
+---
+
+## Is this a plan for THIS note?
+
+**Every entity the note names must appear in a function or a table.** The note is about
+`entries`; the plan builds `projects`. Nothing downstream compares the two.
+
+---
+
+## Does pass 1 slice, and does the model fit inside it?
+
+**Pass 1 is a slice, not a layer.** "Pass 1: the data model. Pass 2: the API. Pass 3: the
+screens" is three passes of nothing working.
+
+**Put in `model` only the tables pass 1 — or at worst pass 2 — actually migrates.** The model
+slot has no passes: every item is checked from the moment the milestone starts, so a table whose
+migration belongs to pass 3 is a PROBLEM from pass 1, and `plan progress` refuses on a problem
+rather than deferring it. A milestone that finishes pass 1 green then cannot be closed, and every
+fix is outside the build's hands. When a later pass needs its own tables, that is the signal it is
+a second milestone — say so in `covers`.
+
+---
+
+## Can each scenario actually be performed?
+
+**Ask which persona performs it. If the answer is "nobody", it belongs one level up or to no pass
+at all.** The runner drives the app as the personas the project declares; there is no anonymous
+RPC caller, so "a caller with no session is refused" is a sentence a backend or permission
+scenario cannot perform. Signed-out is a BROWSER fact.
+
+**Assert that the person got what they came for, not that the code ran.** A scenario proving
+`saveEntry` returns 200 proves the wire. The one worth planning is the one where a person writes
+something, comes back, and it is still there. A browser scenario that opens a page and asserts it
+is still on it proves the route loads and nothing else — `plan progress` names it a problem and
+refuses the milestone.
+
+**Write summary and dashboard scenarios as deltas.** The suite runs against a live database nobody
+resets, so "the payment-failed count is zero, then one" is a claim about every run that came
+before. Read the figure, do the thing, assert what moved. And before planning a tile, name the
+function in this plan that can move it: one counted uncaptured paid orders, which the checkout
+function makes impossible to produce, so the scenario could only ever assert a zero.
+
+**Every input the person is described as giving has to be a field somebody planned.** A plan wrote
+"the desk lists what is due, and staff run the collection as of that date" while its screen only
+ever asked about today — and deliveries fall on the first of a month, so the only thing that
+scenario could assert was an empty desk. Read each scenario's prose against the `ui` items the
+same way you read it against the functions.
+
+**Write every refusal as "X, which is `<state>`, is refused because `<rule>`" — then check that
+state against the rule you wrote in the same plan.** A refusal claims two things at once: that the
+rule shuts, and that the described situation reaches the shut state. One plan asked for "a paused
+licence is refused the academy" in the same milestone whose gate admitted `active_until_expired`,
+which is exactly what pausing inside the paid period produces. The scenario could only ever have
+asserted a bug.
+
+---
+
+## Does something produce every state and field the plan reads?
+
+This is one question asked of four different things. Each costs a build a mid-flight design
+decision that nothing records.
+
+**Every clause of a `feature` or `scenario` description has to be performed by a function** — one
+in this plan, or one already in the meta. Write "when the distributor is removed its companies
+fall back to the direct catalog" with no function that removes a distributor and `plan set`
+accepts it, `plan progress` passes, and the milestone ships a sentence nothing proves. Read each
+description back asking *which function does this*, and cut the half you cannot name.
+
+**Where a scenario calls the same function twice, check it for a per-period guard first.** A
+one-per-day, one-per-order or one-per-person rule makes the second call a refusal, so the journey
+cannot be performed in a single run however correct the code is. One planned "she finishes the
+second lesson and is nudged about the third" against a function that refuses a second completion
+the same calendar day.
+
+**Every screen the milestone's opening paragraph names is either a `ui` item or a sentence to
+cut.** This trap is easier to miss in the summary prose than in the scenarios: a screen named
+there and carried by no `ui` item is invisible to `plan progress`, so the milestone closes green
+with a sentence of itself unbuilt. One promised "the interval control on the admin product form"
+for a form that does not exist anywhere in the app.
+
+**Every field the plan filters, orders or badges on needs the function that sets it** — or a line
+saying it is seed data, and why. A catalog planned to hide products by country, with no way to
+mark a product's countries, cannot be proven without amending the plan mid-build.
+
+**Every state a scenario waits in needs the function that leaves the world like that — checked
+against the code ALREADY built.** Three failure shapes, in rising order of cost:
+
+- *Stale*: a staff queue of "paid orders with no invoice yet", where an earlier milestone had
+  moved invoicing to checkout. No order a customer could place was ever in that state; three
+  scenarios passed once against old rows, then failed.
+- *Unreachable*: staff asked to "capture the payment on an authorised order" when no function in
+  the app or its addons could put an order in `authorized` — the addon only holds money when
+  checkout was started with a flag the plan's own checkout input did not carry.
+- *Wrong person*: a distributor salon owner planned to buy from a catalogue that is scoped by
+  distributor and does not show her the product. Actors are not interchangeable.
+
+**A `model` slot saying "this milestone adds no table" has to be true of the DATA the scenarios
+read, not only of the entities they name.** One promised a checkout priced by delivery country — a
+shipping rate per country, a VAT rate per country — against an `n/a` model, while the only shipping
+table in the tree (an addon's) carries no country column at all. The builder then chooses between
+altering someone else's table and amending the plan, with neither choice recorded. Wherever a
+description prices, rates or tiers something BY a dimension, say in `model` where that lookup lives:
+a table this milestone adds, a column on one that exists, or config-as-code — and if it is config,
+say so and why, exactly as for seed data.
+
+---
+
+## Can two sentences in the plan both be true?
+
+A plan is read one field at a time, so a contradiction between two descriptions survives every
+check `plan set` makes and is discovered mid-build, with the code already written one of the two
+ways.
+
+**Where the milestone has a state machine — anything with more than two states and a clock — write
+the transitions out once, in the model slot, as the table they are.** Every scenario description
+then quotes that table instead of restating it from memory. One plan said a cancel on a paid-up
+licence lands in `canceled` in one scenario and `active_until_expired` in the next.
+
+**Then find every clock in that table: name who sets it, who reads it, and check that every rule
+reading it agrees about when it starts.** The table itself is where the next contradiction hides.
+The next plan wrote exactly this table and still shipped one — it re-stamped `paused_at` at the
+moment a pause took effect, so "resume after four weeks paused" meant four weeks, but left
+`canceled_at` at the moment the customer ASKED, as the legacy source does. A licence cancelled in
+month one was, on the night its year ran out, already past both the 28-day chase and the 60-day
+reactivation, and got both in the same sweep. One clock, two readings, in one table, on one screen.
+When one clock in a family is deliberately diverged from its source, the sibling clocks are where
+you look next: either the same reasoning applies to them, or the plan says why it does not.
+
+**Wherever a function writes a set under a parent, say whether a save REPLACES that set or ADDS to
+it.** A product's variants, an order's lines, a company's members: the two produce identical tables
+and identical scenarios, and differ only on the second save. Left unsaid, one milestone shipped an
+input schema that could not carry a variant's id, so every save re-added the variants it was given
+to update — 1, 2, 4, 8, and by the nineteenth save 262,144 rows, with the suite green throughout.
+Say it in the model slot in the same breath as `onDelete`: that field settles what happens when the
+parent goes, this settles what happens when it stays.
+
+---
+
+## Did you invent anything?
+
+**If the notes do not say who may do a thing, the answer is `null` with the reason, not a rule you
+made up.** A rule the user never agreed to is one they find out about by being locked out of their
+own app.

package/skills/pikku-build/SKILL.md

@@ -88,16 +88,47 @@ generated functions through `ref()`.
   working code: apply is a merge, reject is a `git branch -D`. The milestone's
   plan is your own denominator, measured by `pikku knowledge plan progress` —
   never something a reviewer is handed instead of the code.
-- **Discover before editing.** `yarn pikku meta context --json` returns
-  functions, wires, middleware, permissions, workflows, `capabilities` and
-  `layout` in one call. Fall back to targeted `meta` commands only for a full
-  schema or a workflow's steps.
+- **Discover before editing, and there are two questions, not one.** What THIS
+  PROJECT has wired: `pikku meta context --json` returns functions, wires,
+  middleware, permissions, workflows, `capabilities` and `layout` in one call
+  (fall back to targeted `meta` commands only for a full schema or a workflow's
+  steps). What PIKKU ITSELF offers: `pikku doc <door|export>` — the surface of
+  the pikku installed here, every option key with what it is for, and a worked
+  example. `pikku doc scheduler wireScheduler pikkuVoidFunc` answers in one call
+  what reading `node_modules/@pikku/core` answers slowly and wrongly. **Never
+  open node_modules to find a signature, and never write an import, an export
+  name or an option key you have not seen in `pikku doc`.**
+- **`capabilities.<type>` reports what this app USES, not what pikku offers.**
+  A `false` there is "no wire of this type is declared yet", so the rule below
+  about not introducing one is about not widening an app's surface on a whim —
+  it is not a statement that the surface is unavailable. When a milestone's plan
+  calls for a scheduled task and `capabilities.scheduler` is `false`, check
+  `pikku doc` for the door before concluding you cannot build it.
 - **`metaLocale` in `pikku.config.json` is the language of authored meta** —
   every `description`, `title` and step `template` the console renders.
   Identifiers stay English whatever it says, and the product's own language
   lives in `messages/*.json`.
 - **`pikku all` is the gate.** Run it after touching functions, wirings or
-  schemas, and treat its criticals as real.
+  schemas, and treat its criticals as real. A run that fails on a critical still
+  records the contract hashes it got to, so the next run adds a PKU861 drift on
+  top of the original error — and `pikku versions update` cannot clear it,
+  because codegen refuses before it gets there. Delete those contracts' entries
+  from `versions.pikku.json` and re-run; they are re-recorded. Fix the real
+  diagnostic first, or you will chase the echo instead. Deleting is right only
+  for a contract first recorded INSIDE the milestone you are building — nothing
+  has consumed it, so there is no version to keep. A contract that shipped and
+  then genuinely changed shape gets `version: N+1` on its `pikkuFunc({...})`
+  followed by `pikku versions update`; delete its entry and you erase a version
+  a client is holding.
+- **A new migration reaches the database through `pikku db migrate` (or
+  `pikku db reset`, which wipes first).** `pikku dev` does not apply one — it will happily serve a
+  schema older than the file you just wrote, and the failure surfaces as a
+  function reading a column that is not there yet. Run `pikku db migrate`, then
+  restart the dev server. And never put an underscore before a digit in a column
+  name: `address_line_1` writes correctly from `addressLine_1` and reads back as
+  `addressLine1`, so a value saved through the query builder comes back missing
+  with no error anywhere. Follow the columns already in `db/sqlite/`
+  (`address_line1`), and check a new one round-trips before building on it.
 - **A milestone is planned before it is built, and the plan then stays fixed.**
   The plan — tables, functions, wires, roles, scopes, screens, scenarios, in
   passes — is written through `pikku knowledge plan set` (how: `pikku-architect`)
@@ -183,7 +214,19 @@ listed here.
   `knowledge/`, milestone planning, design direction and refusal scenarios — say
   so out loud to the user when you finish, and point at the way out.
 - **Do not introduce a wire of a type whose `capabilities.<type>` is `false`**
-  unless the user asked for it.
+  unless the user asked for it — and an approved milestone plan counts as them
+  asking. A plan the user signed off on authorizes the wires it names, so build
+  them and flip the capability, rather than refusing planned work because the
+  flag still reads `false` from before the plan.
+- **Do not assume an addon's mounted route works because it mounted.** An
+  addon's singleton services are narrowed to the handful its own factory returns
+  plus config, logger, schema, variables and secrets — the host's `queueService`,
+  `kysely` and the rest never reach it. So an addon route whose handler asks the
+  host for one of those answers 500 on every call, with codegen, typecheck and
+  the route table all clean. Send one real request at the surface a mounted
+  contract claims before you build scenarios on top of it; when it cannot work,
+  wire your own function on the same path (the host's services are yours) and
+  report the addon bug upstream rather than working around it in the caller.
 - **Do not hand-edit generated files** — `.pikku/`, `*.gen.*` or the SDK. Fix the
   source and regenerate.
 - **Do not invent a role.** An invented role becomes invented screens; build only

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

@@ -11,6 +11,14 @@ project shaped so `pikku fabric init` later adopts it with zero rework.
 3. Plan the milestones — the buildable pieces, in dependency order
 4. Implement them one at a time — each proven by a scenario before the next starts
 
+The sections below follow those phases in order, and are meant to be worked
+through rather than searched: §0 bootstrap, §1-§1a the last questions and the
+three languages, §2 the knowledge graph, §3-§4 personas and apps, §5-§5a the
+milestones and each one's technical plan, §6-§6a building and closing one,
+§7-§7a proving it, §8 design, §9 ship. Four of them hand off to their own file —
+[scenarios.md](scenarios.md), [design.md](design.md),
+[multi-app.md](multi-app.md) and [ship.md](ship.md) — at the point you need it.
+
 ## Agent Operating Procedure
 
 1. Discover before editing. Run `pikku info functions --verbose --silent` and
@@ -430,7 +438,13 @@ over, and an uncovered function is a half-milestone whether or not the note says
 
 1. **Migration.** SQL in `db/sqlite/` at the project root, numbered on from the
    ones already there. Apply with `bunx --bun pikku db migrate`, which also
-   regenerates the Kysely types your functions import.
+   regenerates the Kysely types your functions import. **Neither `pikku all` nor
+   restarting `pikku dev` applies a migration** — so a new column reads as
+   `TS2353 … does not exist in type 'InsertExpression<DB, "…">'` on the function
+   that writes it. An unapplied migration is the usual cause and the cheapest to
+   rule out, so run `db migrate` first — but the same error is what a misspelt
+   column or a stale generated type looks like, so if it survives the migration,
+   go and read the SQL.
 2. **Seed.** Demo rows in `db/sqlite-dev-seed.sql`. **There is no seed command** —
    `bunx --bun pikku db reset` is the only thing that applies the file, and it
    wipes, migrates and seeds in one go (`--no-seed` stops after the migration,
@@ -629,6 +643,29 @@ plan to match what you built — the plan was written before the code on purpose
 and rewriting your own denominator afterwards is exactly what that order exists
 to stop.
 
+### 6b. Feed the milestone back into the seats
+
+Before starting the next milestone, answer two questions out loud:
+
+- **What did the plan fail to say?** A field nothing wrote, a promise no function
+  could keep, a pass 1 that turned out to be two. That is a `pikku-architect`
+  lesson.
+- **What did the build learn the hard way?** Anything that cost a wasted run —
+  a stale process, a scenario that only passes once, a diagnostic that turned
+  out to be an echo of an earlier one. That is a `pikku-build` lesson.
+
+Then edit the skill — **at most one change to each per milestone**, and only for
+something that actually went wrong here. A rule with no incident behind it is a
+guess, and these files are read in full every time: they earn their length by
+naming failures a reader would otherwise repeat. Prefer sharpening an existing
+line to appending a new one, and delete a rule the last few milestones have
+shown to be noise.
+
+The gates are the compounding part. A lesson written into a scenario the suite
+runs, or into a check `plan progress` can see, is enforced; the same lesson
+written as prose is a thing the next reader has to remember. Reach for prose
+only when there is nothing to hang a check on.
+
 ## 7. Prove it — scenarios
 
 A scenario is a user journey run as one of your personas, over the real
@@ -637,105 +674,59 @@ here, because a passing one proves the app works the way a signed-in person
 experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
 green — and every milestone's gherkin block from §5 becomes one more.
 
-```typescript
-import { pikkuScenario } from '#pikku/scenarios'
-
-export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
-  title: 'A tenant reports a fault and the owner sees it',
-  description:
-    'The report lands on the owning landlord’s queue, and nobody else’s',
-  tags: ['scenario', 'maintenance'],
-  func: async (_services, _data, { scenario, actors }) => {
-    const report = await scenario.do(
-      'reports a broken boiler',
-      'createMaintenanceReport',
-      { summary: 'No hot water' },
-      { actor: actors.chidi }
-    )
-    await scenario.then(
-      'appears on the owner’s queue',
-      'reportShowsOnQueue',
-      { id: report.id },
-      { actor: actors.amina }
-    )
-    await scenario.then(
-      'is invisible to the other owner',
-      'reportIsNotVisible',
-      { id: report.id },
-      { actor: actors.bilal }
-    )
-    return { id: report.id }
-  },
-})
-```
+**Read [scenarios.md](scenarios.md) before writing the milestone's scenarios,
+and again whenever one of these describes what you are doing.** It is the file
+where the expensive lessons live, and most of them produce a GREEN suite that
+proves nothing:
 
-- **`do` takes an RPC name; `given`/`when`/`then` take a declared step.** A step
-  is a `pikkuScenarioStep` that says what a person is doing and holds one
-  implementation per surface (server-side by default, plus a `browser` one that
-  drives the page). Reaching for an RPC name in a `then` will not resolve.
-- **Every scenario must assert.** A ladder of `given`/`when` with no `then` is a
-  PKU680 critical — it fails `pikku all`, so it stops codegen rather than a test.
-  Coverage counts every step, so without that rule an assertion-free ladder of
-  clicks would score a perfect run while checking nothing.
-- **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.
-- **`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.
+- the shape of a scenario, and `do` vs `given`/`when`/`then`
+- what survives DSL extraction — a `then` in `return` position asserts nothing,
+  and a shared setup helper credits its steps to the wrong actor
+- what to assert — refusals must read the REASON, totals must be deltas, and the
+  assertion nobody writes is the row count
+- living without a state reset: the suite must be green on its SECOND run
+- how a shared step rots as later milestones add writers of the rows it selects
+- browser specifics — the click/navigate race, testids, and `Outlet` nesting
 
 Run them:
 
 ```sh
-bunx --bun pikku scenario run local --spawn                       # server-side, the fast path
-bunx --bun pikku scenario run local --spawn --run browser         # the same journeys, driven as a human
-bunx --bun pikku scenario run local-admin --spawn --run browser   # the second app
+bunx --bun pikku scenario run local --spawn                  # server-side, the fast path
+bunx --bun pikku scenario run local --spawn --run browser    # the same journeys, driven as a human
 ```
 
-`--spawn` starts and stops the server for the run; drop it if `bun run dev` is
-already up. The browser pass needs the environment's `appUrl` and a browser
-driver installed — without them the run fails fast rather than half-running.
+In a multi-app project that one run covers both frontends: each persona carries
+its own `app` and `@pikku/playwright` resolves the base url from the
+environment's `appUrls` map, so there is no second environment to run.
+
+**Run the whole suite, not the milestone's own scenarios.** The milestone's
+scenarios are the ones you wrote to pass; the regression lives in someone
+else's. Tightening what "archived" means is a one-function change that reads as
+local and quietly breaks the milestone-01 scenario nobody re-ran.
+
+**Restart the server after adding a function.** Hot reload does not register a
+new RPC and does not re-run `afterStart`, so a fresh function answers 404 and
+anything provisioned at boot is missing — failures that read like a wiring bug
+and are nothing but a stale process.
 
 ### 7a. Coverage — which functions have actually been run
 
 Green scenarios tell you the journeys you wrote still work. They say nothing
-about the code you never wrote a journey for, and that gap is invisible without
-measuring it:
+about the code you never wrote a journey for:
 
 ```sh
 bunx --bun pikku dev --coverage                        # server, instrumented
 bunx --bun pikku scenario run local --coverage         # against that server
 ```
 
-That writes `coverage/scenario-coverage.json` — which functions each journey
-exercised. **A function no scenario touches has never been run by anything but
-you, by hand, once.** It compiles, it typechecks, `pikku all` is happy, and
-nobody has proven it does what it says.
-
-Run it **as each milestone closes**, not once at the end. Coverage read per
-milestone is a short list you can act on — the milestone you just built either
-covered its own functions or it did not. Read for the first time after ten
-milestones it is a wall of red that nobody triages, and the honest response to a
-wall of red is to ignore it.
-
-Every gap is one of three things, and naming which is the point of looking:
-
-- **A missing scenario** — the function matters and no journey reaches it. Write
-  the journey. Refusal paths dominate this category, because it is the case you
-  are least likely to have clicked through by hand.
-- **A function that should not exist** — nothing reaches it because nothing needs
-  it. Delete it. An unused exposed function is also reachable over
-  `POST /rpc/:rpcName`, so this is a security finding, not only dead weight.
-- **Genuinely deferred** — real, not yet reachable from the UI. Say so in the
-  milestone note that will cover it, so the gap is a decision rather than a
-  hole.
-
-Report the number when you hand the milestone over. A number nobody says out
-loud is a number nobody acts on.
+**A function no scenario touches has no scenario coverage** — the file knows
+what the suite exercises and nothing else, so a unit test, a scheduled job, a
+webhook or a hand call leaves no trace in it. Read
+`coverage/scenario-coverage.json` **as each milestone closes** — per milestone it is a short list you can act on, whereas read for the
+first time after ten milestones it is a wall of red nobody triages. Every gap is
+a missing scenario, a function that should not exist, or a deferral worth
+writing down; [scenarios.md](scenarios.md) says how to tell them apart. Report
+the number when you hand the milestone over.
 
 ## 8. Make it look like someone designed it
 
@@ -870,8 +861,11 @@ cheaper to honour than to retrofit:
 
 ## Reference
 
-- `references/multi-app.md` — adding a second frontend (§4), at the milestone
+Read these when the section that names them comes up, not up front:
+
+- [multi-app.md](multi-app.md) — adding a second frontend (§4), at the milestone
   that needs it
+- [scenarios.md](scenarios.md) — writing journeys that stay proven (§7, §7a)
 - `references/design.md` — committing to a design direction, and how to tell
   whether the screens realise it. Read BEFORE the first screen (§6), not at §8
 - `references/theming.md` — authoring the theme (§8a)
@@ -879,4 +873,4 @@ cheaper to honour than to retrofit:
 - Sibling skills: `pikku-knowledge` (§2), `pikku-auth` (§3),
   `pikku-scenario` (§7, §7a), `pikku-deploy` and `pikku-fabric` (§9)
 - Project conventions written by the template: `AGENTS.md`
-- Doing less than this: `references/quick.md``. Doing more: `references/platform.md``.
+- Doing less than this: [quick.md](quick.md). Doing more: [platform.md](platform.md).

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

@@ -119,6 +119,48 @@ 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.
 
+### Scenarios across the two apps
+
+`pikku new app` stamps `app: '<slug>'` onto each persona it is given, and that
+field — not the `personas` array in `pikkufabric.config.json` — is what
+`@pikku/playwright` resolves a persona's base url from at sign-in. A persona
+with no `app` lands on the fallback frontend, which is the other app's screens
+with the right session on them.
+
+One environment is enough. `pikku.config.json` takes an `appUrls` map beside the
+single `appUrl` fallback, and the CLI takes `--app-url <app>=<url>,<app>=<url>`:
+
+```json
+"local": {
+  "apiUrl": "http://localhost:3000",
+  "appUrl": "http://localhost:7104",
+  "appUrls": { "app": "http://localhost:7104", "admin": "http://localhost:7105" }
+}
+```
+
+Three things follow, and each one has cost a run:
+
+- **An actor is bound to ONE app for the whole run.** The resolution happens once,
+  at sign-in. A staff persona cannot be walked through the customer app to check
+  something is absent from it — drive that assertion with a persona who lives
+  there, and say in the scenario's docblock why the witness is who it is. This
+  binds a SIGNED-OUT scenario too, and that is where it bites: 'a visitor with no
+  session cannot open the admin desk' driven by a customer-app persona points the
+  browser at a router with no such route at all, so what the assertion measures is
+  a 404, not the guard — and on an app with a catch-all redirect to login it
+  passes while proving nothing. Pick the actor by which app owns the ROUTE, not by
+  who should be refused, and drop their session instead.
+- **Every frontend needs its API proxy pointed at the API you are actually
+  running.** `vite.config.ts` reads a variable (`VITE_API_PROXY`) with a default
+  port in it; start the second app without it and every RPC from that app
+  answers 500 while the first app is green, which reads as an auth bug for as
+  long as you let it.
+- **A route sweep must be scoped to one app.** `staticRoutes(repoRoot)` in
+  `@pikku/playwright` unions the route trees of every directory under `apps/`, so
+  a sweep driven by a customer opens the admin app's routes and reports 404s that
+  are correct behaviour. Give the sweep step an `app` input and hand it a root
+  containing only that app.
+
 ## Sessions across two origins
 
 Better Auth lives once, at `/api/auth/*`, and every app proxies to it (see