@pikku/skills 0.12.52 → 0.12.54

package/skills/pikku-build/SKILL.md

@@ -4,12 +4,14 @@ description: >-
   Use to build on Pikku — turning a fresh scaffold into a working app (quick spike, real product,
   or a showcase that exercises every surface), adding a feature to an app that already exists, and
   the one-off cleanup right after a template is cloned. Covers the knowledge base, personas and
-  roles, filing the work as changes and planning each changeset, the scenario that proves each one, theming, multi-app layouts and
-  deploying. TRIGGER when: the user asks for an app to be built on Pikku, a freshly scaffolded
-  project needs turning into a product, the user asks to add a feature or wire up a new endpoint
-  in a working app, or a template was just cloned or scaffolded. DO NOT TRIGGER when: the user
-  asks for a one-off edit to an existing function, asks about Pikku concepts (use pikku-concepts),
-  or wants one specific surface explained rather than built (use that surface's skill).
+  roles, filing the work as changes, the scenario that proves each one, theming, multi-app
+  layouts and deploying. TRIGGER when: the user asks for an app to be built on
+  Pikku, a freshly scaffolded project needs turning into a product, the user asks to add a feature
+  or wire up a new endpoint in a working app, or a template was just cloned or scaffolded. DO NOT
+  TRIGGER when: the user asks for a one-off edit to an existing function, asks about Pikku concepts
+  (use pikku-concepts), wants one specific surface explained rather than built (use that surface's
+  skill), only needs the technical plan for one claimed changeset (use pikku-architect), or is
+  working items off a deployed stage's changes queue (use pikku-changes).
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
 argument-hint: '[feature description]'
 installGroups: [core]
@@ -30,29 +32,30 @@ agent:
 
 ## Which mode
 
-| The situation                                                                | Read                                                                     |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| A template was just cloned or scaffolded, and the tree still looks like one  | `references/post-clone.md` first, then come back                         |
-| A real product, meant to be picked up by someone else                        | `references/app.md` — the default                                        |
-| A spike, a throwaway demo, an idea nobody has committed to                   | `references/quick.md`                                                    |
-| A showcase meant to exercise every Pikku surface                             | `references/platform.md`, which is a delta on top of `references/app.md` |
-| A feature added to an app that already has its knowledge base               | `references/feature.md`                                                  |
+| The situation                                                                  | Read                                                                                          |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| A template was just cloned or scaffolded, and the tree still looks like one    | `references/post-clone.md` first, then come back                                              |
+| A real product, meant to be picked up by someone else                          | `references/app.md` — the default                                                             |
+| A spike, a throwaway demo, an idea nobody has committed to                     | `references/quick.md`                                                                         |
+| A showcase meant to exercise every Pikku surface                               | `references/platform.md`, read together with `references/app.md`                              |
+| A feature added to an app that already has its knowledge base                  | `references/feature.md`                                                                       |
+| Writing or fixing the scenarios that prove a changeset (app §7, §7a)           | `references/scenarios.md`                                                                     |
+| Before the first screen is built: a picture of the screens, a design direction | `references/design.md`                                                                        |
+| Authoring or changing the theme (app §8a)                                      | `references/theming.md`                                                                       |
+| A screen needs data no function returns yet                                    | `references/mocks.md`                                                                         |
+| Adding a second frontend (app §4), at the changeset that needs it              | `references/multi-app.md`                                                                     |
+| Shipping an app as a desktop or Android app                                    | `references/native-app.md`                                                                    |
+| Deploying, and the Fabric-readiness contract (app §9)                          | `references/ship.md`                                                                          |
+| The request is built on an OpenAPI spec (auth mode, sign-in or connect screen) | `references/openapi.md`                                                                       |
 
 **App is the default.** A small or toy-sounding app does not make it Quick;
 only an explicit signal of speed or throwaway-ness does. Platform is not "App
-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/native-app.md`
-(shipping an app as a desktop or Android app), `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/openapi.md` (an app on an OpenAPI spec: the auth mode, the
-auth-config format, and the sign-in or connect screen it implies).
+plus more effort" — it is App plus a deliberate surface checklist: read both
+files, follow the base in full, and do not blend the two into one plan.
+
+Each reference names the topics it leans on but never tells you to open
+another file; this table is the only routing. Open a reference when its row
+matches, not up front.
 
 ## Bootstrap before anything else
 

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

@@ -1,5 +1,27 @@
 # Build a product on open-source Pikku
 
+## Contents
+
+- Agent Operating Procedure
+- 0. Bootstrap, before anything else
+- 1. One more round of questions — then stop asking
+- 1a. Three languages, and you must not collapse them
+- PHASE 1 — What the app is
+- 2. Write the knowledge graph — before any code
+- PHASE 2 — Who it is for, and what it is made of
+- 3. Declare the people — personas and roles
+- 4. Declare the apps — one API, several frontends
+- PHASE 3 — The plan
+- 5. File the work as changes
+- 5a. The technical plan — per changeset, before you build it
+- PHASE 4 — Build
+- 6. Build each changeset
+- 6a. Close the changeset against its plan, not against your memory
+- 7. Prove it — scenarios
+- 8. Make it look like someone designed it
+- 9. Ship it, and stay Fabric-ready
+- Reference
+
 You have a scaffolded project with skills installed. This skill owns everything
 from here: no Fabric account, no card, no hosted build — while keeping the
 project shaped so `pikku fabric init` later adopts it with zero rework.
@@ -15,9 +37,9 @@ 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
 changes and each changeset'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.
+§7-§7a proving it, §8 design, §9 ship. Four of them have their own reference —
+scenarios, design, multi-app and ship, each listed in SKILL.md — to read at the
+point you need it.
 
 ## Agent Operating Procedure
 
@@ -74,10 +96,10 @@ in one message. Then stop; do not interview the user.
   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, with yes marked recommended, in the words of
-  `references/design.md` — "a picture of the main screens so you can say 'yes,
+  the design reference (see SKILL.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
+  answer at all, the design reference (see SKILL.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. Only an explicit no skips it.
 - **May I write test records into the system it talks to?** Ask only when the
@@ -328,7 +350,7 @@ Recording the decision is Phase 2 work. **Creating the directory is not.**
 Cloning `apps/app` materialises a folder of copied screens, so it belongs to the
 changeset that first needs the second app, not to planning.
 
-When you get there, read `references/multi-app.md`. It carries the clone, the
+When you get there, read the multi-app reference (see SKILL.md). It carries the clone, the
 `package.json` edits, the `frontends` map in `pikku.config.json`, the dev-runner
 change that otherwise silently never starts your second app, the per-frontend
 scenario environments, and how sessions behave across two origins.
@@ -449,7 +471,7 @@ while the plan is short.
    every screen is `Card` + `Stack` + `Text` composed the inventory rather than a
    design. Register the screen in `useNavItems()` — that one file feeds both the
    desktop sidebar and the phone navigation.
-   **Read `references/design.md` before you write the first screen.** You commit
+   **Read the design reference (see SKILL.md) before you write the first screen.** You commit
    to a design direction there and are then accountable to it — it hands you no
    layouts, because the design is yours to make. What you build here is then
    judged at step 7, at the end of this changeset rather than once at §8, where
@@ -458,7 +480,7 @@ while the plan is short.
 7. **Look at it.** Screenshot every screen this changeset touched, at both
    widths, with the seed in place, and look at the images. This is a gate, the
    same as the scenario: a changeset whose screens nobody has seen is not built,
-   it is unproven at the one layer scenarios cannot reach. `references/design.md`
+   it is unproven at the one layer scenarios cannot reach. the design reference
    carries how to take the shot when no browser tool is wired up, and what to
    look for. Then close it against its plan (§6a) — `pikku knowledge plan
 progress` has to exit zero before the last change is done — and only then
@@ -645,7 +667,7 @@ 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 scenario a changeset's plan names becomes one more.
 
-**Read [scenarios.md](scenarios.md) before writing the changeset's scenarios,
+**Read the scenarios reference (see SKILL.md) before writing the changeset'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:
@@ -701,13 +723,13 @@ webhook or a hand call leaves no trace in it. Read
 `coverage/scenario-coverage.json` **as each changeset closes** — per changeset it is a short list you can act on, whereas read for the
 first time after ten changesets 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
+writing down; the scenarios reference (see SKILL.md) says how to tell them apart. Report
 the number when you hand the changeset over.
 
 ## 8. Make it look like someone designed it
 
 **This section numbers 8, but half of it has already happened.** Read
-`references/design.md` before the first screen is built — a design pass run on
+the design reference (see SKILL.md) before the first screen is built — a design pass run on
 eight changesets of scaffolded screens is a repaint, and it shows. What is left
 here at §8 is the theme you may have deferred and the critique you cannot run
 until there are screens to critique.
@@ -720,7 +742,7 @@ looking like the template:
 - **Execution** — whether the screens actually realise that direction, or
   default to whatever component was nearest. No theme does this, and it is where
   "works but looks like nobody decided anything" comes from.
-  `references/design.md` carries the process for it, and it belongs at §6, per
+  the design reference (see SKILL.md) carries the process for it, and it belongs at §6, per
   screen.
 - **Critique** — judging how well the built screens execute the direction.
   `impeccable` does this well, and it is free.
@@ -732,10 +754,8 @@ spacing.
 
 ### 8a. Author the theme — the step nothing does for you
 
-The look lives in `packages/mantine-theme`, and it is data, not code:
-
-The look lives in `packages/mantine-theme`, and it is data, not code — one JSON
-per theme, `active.json` naming the live one. **Read `references/theming.md`** for
+The look lives in `packages/theme`, and it is data, not code — one JSON
+per theme, `active.json` naming the live one. **Read the theming reference (see SKILL.md)** for
 the file layout, what each field changes, and how to turn a direction in words
 into a theme.
 
@@ -757,26 +777,25 @@ theme is; only the note records why.
 
 ### 8b. Compose real components, then critique
 
-**`references/design.md` is where design actually lives** — committing to a
+**The design reference (see SKILL.md) is where design actually lives** — committing to a
 direction before the first screen, judging the result from screenshots rather
 than from source, the two screens that get skipped, and why you reset the dev
 database before judging anything. It prescribes no layouts on purpose: two apps
 built from this skill should not look like each other. What follows here is only
 the component inventory.
 
-**Compose with Mantine's rich components — not tables and text everywhere:**
+**Compose with rich components — not tables and text everywhere:**
 
-- **`@mantine/charts`** (Recharts underneath) for overviews — `AreaChart`,
-  `BarChart`, `LineChart`, `DonutChart`, `Sparkline`. A metric worth showing is
-  worth a chart, not a number in a `Text`.
-- **`@mantine/dates`** for anything time-based — `DatePicker`, `Calendar`,
-  `DateTimePicker`, range inputs. Never hand-roll a date field.
-- Composed layouts over flat lists — `Timeline` for history, `Stepper` for
-  multi-step progress, `Card` + `SimpleGrid` for a gallery, `RingProgress` for
-  completion, `Badge`/`ThemeIcon` for status.
+- **shadcn `chart`** (Recharts underneath, coloured by `--chart-1` to `--chart-5`) for overviews — area,
+  bar, line and pie charts. A metric worth showing is
+  worth a chart, not a number in a paragraph.
+- **shadcn `calendar` and `date-picker`** for anything time-based, including
+  range inputs. Never hand-roll a date field.
+- Composed layouts over flat lists — a timeline for history, steps for
+  multi-step progress, `Card` + a CSS grid for a gallery, `Progress` for
+  completion, `Badge` for status.
 
-Both ship in the template's app dependencies. Look each one up in the Mantine
-llms.txt and use the real component.
+Add each one with the shadcn CLI and use the real component.
 
 Then critique it. Free, and works across coding agents:
 
@@ -795,13 +814,13 @@ Judging your own UI from source code is guessing.
 **Screenshot at a phone width too (≈390px), not just desktop, and critique
 those.** A layout that is fine at 1440px routinely breaks at 390 — a table that
 overflows, a row of buttons that wraps into a pile, text jammed against the edge,
-a modal taller than the viewport. Mantine gives you the tools (responsive `Grid`,
-`visibleFrom` / `hiddenFrom`, `Stack` instead of `Group` at small sizes); use
+a modal taller than the viewport. Tailwind gives you the tools (responsive `grid-cols-*`,
+`md:hidden` / `hidden md:block`, `flex-col` instead of `flex-row` at small sizes); use
 them. The template already mounts a phone navigation per `AGENTS.md` — pick
 `MobileTabBar` or `MobileNavDrawer` deliberately per app, never both.
 
 The gate: **no P0 findings left on any screen, in any app, at either width**,
-and every screen honestly answers the questions in `references/design.md` —
+and every screen honestly answers the questions in the design reference —
 including whether it looks like the direction you committed to or like the
 components you had. Don't silence a finding by deleting the feature it is
 about.
@@ -815,7 +834,7 @@ problem it does not have.
 ## 9. Ship it, and stay Fabric-ready
 
 When the queue is empty, `pikku knowledge gaps` lists nothing and the scenarios are green, read
-`references/ship.md`. It carries the open-source deploy paths (`--provider
+the ship reference (see SKILL.md). It carries the open-source deploy paths (`--provider
 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.
@@ -837,16 +856,16 @@ cheaper to honour than to retrofit:
 
 ## Reference
 
-Read these when the section that names them comes up, not up front:
+Read these when the section that names them comes up, not up front. SKILL.md
+says when to open each one:
 
-- [multi-app.md](multi-app.md) — adding a second frontend (§4), at the changeset
-  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)
-- `references/ship.md` — deploying, and the Fabric-readiness contract (§9)
+- multi-app — adding a second frontend (§4), at the changeset that needs it
+- scenarios — writing journeys that stay proven (§7, §7a)
+- design — committing to a design direction, and how to tell whether the
+  screens realise it. Read BEFORE the first screen (§6), not at §8
+- theming — authoring the theme (§8a)
+- ship — deploying, and the Fabric-readiness contract (§9)
 - 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: [quick.md](quick.md). Doing more: [platform.md](platform.md).
+- Doing less than this: the quick reference. Doing more: the platform reference (both in SKILL.md).

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

@@ -1,5 +1,17 @@
 # Design
 
+## Contents
+
+- Commit to a direction before the first screen
+- Offer to draw the screens before you build them
+- One screen, designed properly, before the rest exist
+- Judge it — and don't grade your own homework
+- The kit is a floor, not a ceiling
+- Design is a gate on the changeset, not a phase at the end
+- Facts, not taste
+- Two screens that get skipped
+- Symptoms of a screen nobody designed
+
 Your job here is to design something worth the product — not to apply a house
 style. **There is no house style, and this file is not one.** Two apps built from
 this skill should not look like each other; if they do, something has gone wrong
@@ -23,7 +35,7 @@ never clinical" is a direction. "Clean and modern" is not — it rules nothing o
 so it cannot be departed from.
 
 Write it to `knowledge/decisions/design/`, then build the theme from it
-(`references/theming.md`). **From that point you are accountable to your own
+(the theming reference, see SKILL.md). **From that point you are accountable to your own
 direction, not to this file.** That is the whole mechanism: the freedom is real,
 and so is the commitment.
 
@@ -36,9 +48,9 @@ Being ambitious is easier against a list of specific things to not be. Generated
 interfaces cluster hard, and these are the attractors — not because any is ugly,
 but because arriving at one *by default* means no choice was made:
 
-- **Stock Mantine.** The strongest pull, and the hardest to see: a component
+- **Stock component-library defaults.** The strongest pull, and the hardest to see: a component
   library's untouched defaults do not look broken, they look finished. Blue
-  accent, `#dee2e6` borders, `md` radius on everything, `Card` + `Stack` + `Text`
+  accent, grey borders, one radius on everything, `Card` + stacked text
   down every page. An app can be entirely this and never trip a critique, because
   nothing on any screen is *wrong*.
 - Warm cream ground with a serif display face and a terracotta accent.
@@ -71,29 +83,29 @@ screens costs a fraction of eight built screens, and it is the only point where
 "that is not what I meant" is free.
 
 **Author the theme first, then draw the mock from it.** This order is the whole
-point. A beautiful page in hand-rolled CSS sets a bar Mantine then misses, and
+point. A beautiful page in hand-rolled CSS sets a bar the real components then miss, and
 what the user approved is not what ships — they signed off on a picture and
 received an approximation of it. So write `themes/<name>.json` first
-(`references/theming.md`), and let the mock take its every value from that file:
+(the theming reference, see SKILL.md), and let the mock take its every value from that file:
 the palette, `structure.radius`, the spacing scale, the fonts, the component
 `defaultProps`. Approving the mock then approves the theme, and the built screens
 inherit it rather than chase it.
 
-**The mock has two halves, and only one of them is Mantine's.** This is the same
+**The mock has two halves, and only one of them is the component library's.** This is the same
 split the built screen lives under, applied a step earlier so the two agree by
 construction. The PAGE — the shell, the regions, the columns, the rhythm, the
 material behind the content, what overlaps what — is plain HTML and your own
 CSS, arranged however the layout decision demands; that half is free, and it is
 where the design actually happens. The COMPONENTS — anything a person would
 point at and call a control, and that the app will adopt as itself: buttons,
-inputs, selects, tables, badges, menus, modals — are drawn as *Mantine's*, at the
-metrics Mantine actually uses: its control heights, its input shapes, its table
+inputs, selects, tables, badges, menus, modals — are drawn as *shadcn's*, at the
+metrics shadcn actually uses: its control heights, its input shapes, its table
 and menu behaviour. The test is the one the build will apply too: is this thing
 the SHAPE OF THE PAGE, or a COMPONENT someone would point at?
 
 Getting that second half wrong is what makes a mock a lie. A control the mock
 invents is a promise the app cannot keep, and a beautiful hand-rolled input sets
-a bar the real one misses on screen one. If the mock wants something Mantine
+a bar the real one misses on screen one. If the mock wants something shadcn
 does not do, that is a real finding, and finding it here is the point: change the
 theme so it does, or change the mock, and say which.
 
@@ -102,7 +114,7 @@ needs — not a prototype, not a click-through. Static markup, real content from
 their domain (never lorem), the empty and error states beside the happy path,
 laid out so the whole app is legible by scrolling. Its CSS is custom properties
 on `:root` carrying the theme JSON's values, so a change to either is a change
-to one number in both. Mantine itself will not load here — it is a React library
+to one number in both. The components themselves will not load here — they are React
 and a page like this has no bundler, and on hosts that sandbox the page (a Claude
 Artifact) external stylesheets are blocked outright — so do not try; the mock
 reproduces the theme's values by hand, which is why they have to be written down
@@ -130,25 +142,25 @@ stating:
   wins; when they disagree about a *layout*, the mock wins.
 
 **Building it is then a transcription, not a translation.** Because the theme
-already exists and the mock was drawn from it, the screen is Mantine components
+already exists and the mock was drawn from it, the screen is shadcn components
 arranged the way the mock arranges them — the look arrives with the theme. Two
 rules keep it that way:
 
-- **Layout is yours to write; components are Mantine's.** The page shape — the
+- **Layout is yours to write; components are shadcn's.** The page shape — the
   regions, the columns, the rhythm, what sits beside what — is ordinary markup
   and your own CSS. Anything a person would point at and call a control comes
-  from Mantine: buttons, inputs, selects, tables, badges, menus. Those carry
+  from shadcn: buttons, inputs, selects, tables, badges, menus. Those carry
   focus rings, keyboard behaviour and i18n, and hand-rolling one throws all of
   it away.
 - **A gap goes back to the theme, never into a component override.** If a screen
   does not match the mock, the fix is a value in `themes/<name>.json`. A stack of
-  one-off `className`s and `!important` fighting Mantine's defaults looks like
+  one-off `className`s and `!important` fighting the component defaults looks like
   progress on screen one and is unmaintainable by screen five, and the screens
   drift apart because nothing central holds them together.
 
 **Checking the built screen against the mock** is a structural comparison, not a
 pixel one: the same regions in the same order, the same hierarchy, the same
-states present, the same tokens used. Do not chase pixel equality — Mantine's
+states present, the same tokens used. Do not chase pixel equality — shadcn's
 components have their own metrics and the mock was drawn without them. A built
 screen that reads as the same screen has passed.
 
@@ -308,8 +320,8 @@ These are not design opinions and are not open to a different answer.
 - **Empty, loading and error are states that exist.** The empty state is what a
   new user meets first and the one most often skipped entirely.
 - **Contrast and tap targets are measured, not judged.** `pikku-a11y` covers it.
-  One trap worth knowing: a Mantine `light` variant paints its label at the
-  generated ramp's stop, which lands just under AA on its own tint — name the
+  One trap worth knowing: a tinted badge paints its label in the
+  accent, which lands just under AA on its own tint — name the
   darker ink once and reuse it.
 
 ## Two screens that get skipped
@@ -351,7 +363,7 @@ first one.
   and a display font applied to a default layout is a well-dressed default.
 - Every border, divider and disabled control is a cool blue-grey while the
   accent is not — the surest sign the neutrals were inherited rather than
-  chosen. See `references/theming.md`.
+  chosen. The theming reference (see SKILL.md) covers it.
 - It looks like the last app you built.
-- It looks like Mantine. Not *built with* Mantine, which it is and should be —
+- It looks like stock shadcn. Not *built with* shadcn, which it is and should be —
   but indistinguishable from a component gallery with the brand hue swapped in.

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

@@ -1,5 +1,19 @@
 # Pikku Create-a-Feature
 
+## Contents
+
+- Agent Operating Procedure
+- Stage 1 — Discover
+- Stage 2 — State intent in plain English (BEFORE writing code)
+- Stage 3 — Branch off
+- Stage 4 — Implement
+- Stage 5 — Verify
+- Stage 6 — Commit
+- Stage 7 — Hand off
+- Report what fought you
+- Hard constraints
+- Output discipline
+
 The stages, in order:
 
 - [Agent Operating Procedure](#agent-operating-procedure)

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

@@ -0,0 +1,23 @@
+# Data the backend does not have yet
+
+Read this when a screen needs data no function returns yet, or returns in a different shape. Real functions come first; mock only what is missing.
+
+## Three ways to get data
+
+- `usePikkuQuery('rpc:name')` and `usePikkuMutation('rpc:name')` take only RPCs that exist, with the function's own types. `api.gen.ts` lists them. Use these whenever a function fits.
+- Mocks are files, not code: `.mocks/<rpc.name>/<scenario>.json` is exactly what the RPC answers, and `<scenario>.meta.json` beside it holds `label`, `description`, `state` (healthy, empty, error or slow), `default`, `delayMs` and `status`. Exactly one scenario per RPC has `default: true`. Add an empty and an error scenario for every list and every mutation.
+- `usePikkuQueryStub('rpc:name')` and `usePikkuMutationStub('rpc:name')` always answer from the mock, and their output type is inferred from the mock files. Use a stub only when the function's types are not enough: no function exists, or the shape the screen needs differs from the function's output. If the mock already fits the function, use `usePikkuQuery`.
+
+With `VITE_MOCK` set the plain hooks answer from the default mock too, so every state of every screen can be looked at without a backend.
+
+## Publishing
+
+A stub with no `{ featureFlag }` works in development and cannot be published. `usePikkuQueryStub('rpc:name', { featureFlag: 'flag' })` can, as long as the flag is declared in the project. Production never ships mock data; a stub there is a plain call that gets a 404.
+
+## Making a screen real
+
+`pikku mocks check` lists every stub and blocks the unflagged ones. For each stub: implement the function so its output matches the mock, replace the stub with `usePikkuQuery`, delete the flag if nothing else uses it. `pikku mocks diff` shows what changed, what is unused and what is dead; delete a mock directory it reports as removed.
+
+## Screens built on mocks
+
+The screens are the real app's: real components, `m.*()` for every string, the theme tokens. Only the data is sample. Make it look lived in: at least six realistic records where a page lists things, real copy, tinted and textured placeholder images instead of flat grey boxes. A button that leads nowhere real stays inert.

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

@@ -1,5 +1,12 @@
 # Adding a second frontend
 
+## Contents
+
+- Deciding it is two apps, not one
+- The second app
+- Sessions across two origins
+- Building the second app's screens
+
 Read this when the split you recorded in Phase 2 is "separate apps" and you have
 reached the changeset that needs the second one. **Not before.** Cloning
 `apps/app` materialises a directory of copied screens; doing it during planning
@@ -121,8 +128,8 @@ supervisor, a dev runner, a deploy target — belongs to whatever is hosting it.
 On a plain checkout, `bun --filter @project/<slug> dev` is enough.
 
 Packaging it as a desktop or Android app is a separate step, on the same
-`frontends` entry: `pikku app native init <slug>`. See
-`references/native-app.md`.
+`frontends` entry: `pikku app native init <slug>`. The native-app reference
+(see SKILL.md) covers it.
 
 ### Scenarios across the two apps
 

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

@@ -1,5 +1,14 @@
 # Shipping an app as a desktop or Android app
 
+## Contents
+
+- The commands
+- Pick the mode first
+- What pikku owns and what you own
+- Plugins
+- The identifier
+- Building
+
 Read this when an app in `frontends` has to be installed rather than visited: a
 desktop app, an Android APK, later an iPhone app. The app is still the same
 frontend. A native app is that frontend packaged in a Tauri shell, configured on

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

@@ -1,5 +1,12 @@
 # An app on top of an OpenAPI spec
 
+## Contents
+
+- Pick the auth mode
+- The auth-config file
+- The screens
+- Scenarios
+
 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:

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

@@ -1,12 +1,22 @@
 # Build a platform showcase on Pikku
 
-**This skill is a delta. `references/app.md` is the base — read it and follow it in
-full.** Everything there applies: knowledge base first, personas and roles,
+## Contents
+
+- What "platform" means here
+- Choosing surfaces — during app workflow §5 (planning)
+- The surfaces
+- Coverage — where the bar is higher than the base workflow
+- The full gate
+- Deploy
+- Reference
+
+**This file is a delta: it adds to the app workflow, which stays the base and is
+followed in full.** Everything there applies: knowledge base first, personas and roles,
 changes grouped into changesets, planned then built one at a time, scenarios, design pass, deploy
 gates, Fabric-readiness. This file adds the surfaces that turn an app into a
 demonstration of the platform, and says where each one slots into that workflow.
 
-Read `references/app.md` now, then come back. Do not blend the two into one plan —
+Do not blend the two into one plan —
 the phases below hang off its phases by number.
 
 ## What "platform" means here
@@ -23,7 +33,7 @@ or agent page, never the queue, scheduler or wire pages behind it.
 Budget the extra surfaces at one changeset each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
 
-## Choosing surfaces — during `references/app.md` §5 (planning)
+## Choosing surfaces — during app workflow §5 (planning)
 
 When you file the work, each surface below becomes its own changeset, ordered
 after the spine it depends on.
@@ -137,7 +147,7 @@ correct rather than a smell: a third-party caller needs a real REST shape.
 
 ### Locales — `pikku-i18n`
 
-`references/app.md` already requires every string to be a key. **Here, ship three
+The app workflow already requires every string to be a key. **Here, ship three
 locales, and make one of them RTL** (`pikku-i18n`). Two LTR locales prove the
 plumbing; an RTL one proves the layout, and it will find real bugs — mirrored
 icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
@@ -150,7 +160,7 @@ every added locale is cloned from, so three locales is `locales: ["en", …]` an
 never a repointed base. Shipping locales is also not a reason for anything in
 the code to stop being English: identifiers are English in every project, and
 the language of `description`/`title`/`template` is `metaLocale` in
-`pikku.config.json`. See `references/app.md` §1a.
+`pikku.config.json`. The app workflow's §1a covers it.
 
 ### Emails — `pikku-emails`
 
@@ -177,7 +187,7 @@ the domain has a piece that genuinely belongs to no single app.
 
 ## Coverage — where the bar is higher than the base workflow
 
-`references/app.md` §7a already has the mechanics and the per-changeset habit:
+The app workflow's §7a already has the mechanics and the per-changeset habit:
 run the server instrumented, run the scenarios against it, read
 `coverage/scenario-coverage.json`, and triage every gap as a missing scenario, a
 function that should not exist, or a documented deferral. Do all of that here.
@@ -196,7 +206,7 @@ Two things change in a showcase:
 
 ## The full gate
 
-Everything in `references/app.md` §9, plus the checks a showcase should be able to
+Everything in the app workflow's §9, plus the checks a showcase should be able to
 survive:
 
 ```sh
@@ -218,7 +228,7 @@ bunx --bun pikku scenario run local --spawn --run browser
 
 ## Deploy
 
-`references/app.md` §9 covers the open-source paths (`--provider standalone`,
+The app workflow's §9 covers the open-source paths (`--provider standalone`,
 `cloudflare`, `aws`). One thing specific to this mode: **the extra surfaces are
 extra deploy units.** Workflow workers, queue workers, schedules and the events
 channel each appear in `pikku deploy plan` as their own entries. Read the plan
@@ -227,7 +237,7 @@ built.
 
 ## Reference
 
-- Base workflow: `references/app.md` — read it first, follow it in full
+- Base workflow: the app workflow, which this file adds to
 - Per-surface skills: `pikku-workflow`, `pikku-wiring`, `pikku-agent`,
   `pikku-i18n`, `pikku-emails`,
   `pikku-meta`, `pikku-addon`, `pikku-auth`, `pikku-services`