@pikku/skills 0.12.32 → 0.12.34

package/package.json

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

package/skills/pikku-architect/SKILL.md

@@ -3,9 +3,9 @@ name: pikku-architect
 description: >-
   Use to turn one settled milestone note into the technical plan the build is measured against —
   the tables, functions, wires, roles, scopes, screens and scenarios it owes, split into passes and
-  written through `pikku knowledge plan set`. This is a SEPARATE SEAT from the build: the plan is
-  the denominator `pikku knowledge plan progress` divides by, so whoever writes it must not be the
-  one grading themselves against it. TRIGGER when: a milestone note is settled and the next step is
+  written through `pikku knowledge plan set`. The plan is the denominator
+  `pikku knowledge plan progress` divides by, so it is written BEFORE any of the milestone's code
+  exists and never edited afterwards to match what got built. TRIGGER when: a milestone note is settled and the next step is
   planning it, the user asks to plan or architect a milestone, `pikku knowledge plan progress` says
   a milestone has no plan, or pikku-build's App mode reaches a milestone with nothing planned. DO
   NOT TRIGGER when: the milestone notes themselves are still being written (use pikku-knowledge),
@@ -17,18 +17,19 @@ installGroups: [core]
 # Plan one milestone
 
 A milestone note says what the app must DO and how it must feel for the person using it. It
-deliberately does not say how. You are the seat that decides how, once, in writing, before anyone
-builds it.
+deliberately does not say how. This is where how gets decided, once, in writing, before any of
+it is built.
 
-**Why this is a separate seat.** The build agent used to write its own plan. That makes one party
-both author and examiner: it can build a fraction, plan only that fraction, and certify itself
-complete — and `pikku knowledge plan progress` then divides by a denominator the builder chose
-after seeing its own answer. A plan written here, against the note, by someone who is not going to
-build it, is the denominator the builder does not own.
+**Why the plan comes first and stays fixed.** A builder who plans after seeing its own work can
+build a fraction, plan only that fraction, and certify itself complete — `pikku knowledge plan
+progress` then divides by a denominator chosen after the answer. The defence is the ORDER: the plan
+is written against the note, in its own turn, before a single migration for it exists, and is never
+edited afterwards. An item that will not land is deferred with its reason through `plan defer`,
+not rewritten out of the plan. The same agent plans and then builds; nothing hands off.
 
-**One milestone, one plan, then stop.** Do not build in this session. Do not plan the next
-milestone "while you are here" — the notes after this one are still allowed to change, and a plan
-written against a note that later moves is worse than no plan.
+**One milestone, one plan, then build it.** Do not plan the next milestone "while you are here" —
+the notes after this one are still allowed to change, and a plan written against a note that later
+moves is worse than no plan.
 
 ---
 
@@ -38,6 +39,11 @@ The plan reaches disk through `pikku knowledge plan set <milestone> <file>` and
 validates first and names the field that is wrong if it refuses; a plan file written with an editor
 is a plan nothing checked, and the place that discovers that is a finished build.
 
+It is also written ONCE. `plan set` refuses a milestone that already has a plan: the plan is the
+order the build is measured against, and an order that can be rewritten measures nothing. The one
+way down from a written plan is `pikku knowledge plan defer <milestone> <item> --reason <why>`,
+which records what was left out and why.
+
 It is JSON rather than a note on purpose. Everything else under `knowledge/` is prose a human
 reads; this one is consumed field-by-field, and a markdown parser is one more place a misspelt
 heading silently passes. It cannot live INSIDE the milestone note either: that note is frozen once
@@ -260,6 +266,7 @@ cover it — so a role × resource cross product there costs the milestone nothi
 
 ## When you are done
 
-The accepted `plan set` is the end of the seat. Hand the milestone to `pikku-build`, which reads the
-plan with `plan show --for-build`, builds it, and closes the milestone only when
-`pikku knowledge plan progress` is clean. What you wrote is what it is measured against.
+The accepted `plan set` is the end of planning. Go straight on to the build in `pikku-build` §6:
+read the plan with `plan show --for-build`, build it, and close the milestone only when
+`pikku knowledge plan progress` is clean. What you wrote is what you are measured against, so do
+not touch it once the first migration is open.

package/skills/pikku-build/SKILL.md

@@ -19,13 +19,13 @@ installGroups: [core]
 
 ## 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 and milestones | `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`, which is a delta on top of `references/app.md` |
+| A feature added to an app that already has its knowledge base and milestones | `references/feature.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
@@ -33,9 +33,10 @@ 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` (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` (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`
 (authoring the theme),
 `references/ship.md` (deploying, and the Fabric-readiness contract).
 
@@ -52,9 +53,10 @@ while still planning. Those failures look alarming and are nothing but this.
 
 ## What holds in every mode
 
-- **The branch and the diff are the contract.** There is no plan JSON. A
-  reviewer sees real, compiled, working code: apply is a merge, reject is a
-  `git branch -D`.
+- **The branch and the diff are the contract.** A reviewer sees real, compiled,
+  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
@@ -65,11 +67,13 @@ while still planning. Those failures look alarming and are nothing but this.
   lives in `messages/*.json`.
 - **`pikku all` is the gate.** Run it after touching functions, wirings or
   schemas, and treat its criticals as real.
-- **A milestone is planned by a different seat than the one that builds 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` by `pikku-architect`,
-  and `pikku knowledge plan progress` measures the build against it from the
-  generated meta. A builder who writes its own plan is grading itself.
+  passes — is written through `pikku knowledge plan set` (how: `pikku-architect`)
+  in its own turn before any of that milestone's code exists, and
+  `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.
 
 ## What NOT to do
 

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

@@ -61,6 +61,12 @@ in one message. Then stop; do not interview the user.
   Neutral (fine for an internal tool, but say so out loud); a direction in words;
   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
+  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.
 - **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
@@ -75,11 +81,11 @@ A brief saying "the entire UI is German" is about **one** of these. Getting this
 wrong has already shipped a project that can never add a second language, so
 settle all three explicitly before you write code.
 
-| Axis            | What it covers                                                                                                                       | Where it goes                                                                     |
-| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                                    | Nowhere — **always English**, no setting, not negotiable                          |
-| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions        | `metaLocale` in `pikku.config.json`, default `en`                                     |
-| **Product UI**  | Every string the app shows a user                                                                                                    | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
+| Axis            | What it covers                                                                                                                 | Where it goes                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Commit messages.                              | Nowhere — **always English**, no setting, not negotiable                             |
+| **Meta**        | `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role and persona descriptions | `metaLocale` in `pikku.config.json`, default `en`                                    |
+| **Product UI**  | Every string the app shows a user                                                                                              | `messages/<locale>.json`, and `defaultLocale` for what a first-time visitor opens in |
 
 **Identifiers are English.** The product's market does not change this and
 neither does `metaLocale`. Identifiers are the surface the generated `#pikku/*`
@@ -212,7 +218,11 @@ defineSystemRole({
 })
 
 definePersonas({
-  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+  visitor: {
+    name: 'Visitor',
+    jobTitle: 'Synthetic health-check user',
+    account: {},
+  },
   amina: {
     name: 'Amina',
     jobTitle: 'Property owner',
@@ -223,7 +233,8 @@ definePersonas({
   bilal: {
     name: 'Bilal',
     jobTitle: 'Property owner',
-    personality: 'A second owner — exists so "you see yours, not theirs" is testable',
+    personality:
+      'A second owner — exists so "you see yours, not theirs" is testable',
     roles: ['owner'],
     account: {},
   },
@@ -332,6 +343,10 @@ 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
+is a hole in this plan. Say which milestone covers which screen.
+
 How to order them:
 
 1. **The spine first.** The one object everything else hangs off, and the screen
@@ -359,10 +374,10 @@ scenarios, split into passes. It is JSON, it lives beside the note, and
 `pikku knowledge plan progress` measures the finished build against it.
 
 **Read `pikku-architect` and follow it.** The plan is the denominator the
-completion check divides by, so a builder who writes their own plan can build a
-fraction, plan only that fraction, and certify itself complete. Fabric answers
-that by giving the plan its own seat; here the defence is the ORDER, and it only
-holds if you keep it: the plan is written against the note in its own turn,
+completion check divides by, so a builder who plans after seeing their own work
+can build a fraction, plan only that fraction, and certify itself complete. The
+defence is the ORDER, and it only holds if you keep it: the plan is written
+against the note in its own turn,
 before any of the code it measures exists, and is never edited afterwards to
 match what you ended up building. An item that will not land is deferred with
 its reason — `plan defer` — not quietly rewritten. Write it before you open a
@@ -386,8 +401,8 @@ no plan, and everything after the current milestone is still allowed to move.
 
 **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
-covered*. A stack of half-milestones cannot be reviewed and cannot be handed
+until §6a passes, §7 is green for this one _and §7a shows its functions
+covered_. A stack of half-milestones cannot be reviewed and cannot be handed
 over, and an uncovered function is a half-milestone whether or not the note says
 `built`.
 
@@ -406,7 +421,7 @@ over, and an uncovered function is a half-milestone whether or not the note says
    Do this generously and do it now: an empty app demos badly and critiques
    badly, and you cannot judge a screen's hierarchy, overflow, or truncation
    against zero rows. Seed rows each persona sees differently — with an ownership
-   rule that means seeding rows for the *second* owner too.
+   rule that means seeding rows for the _second_ owner too.
 3. **Functions.** One `pikkuFunc` per `*.function.ts`. Mark it `expose: true` and
    Pikku generates the typed RPC client and the React Query hooks the UI calls;
    you do NOT write an HTTP route for it. Add `wireHTTP` only for a real REST
@@ -415,16 +430,28 @@ over, and an uncovered function is a half-milestone whether or not the note says
 5. **UI.** Pages in `<app>/src/pages/`, one route file each in `<app>/src/routes/`,
    calling functions through the generated `usePikkuQuery` / `usePikkuMutation`
    hooks from `@project/functions-sdk/pikku/api.gen`. One component per `.tsx`
-   file. Compose the kit from `@/components/<Name>` rather than hand-rolling.
-   Register the screen in `useNavItems()` — that one file feeds both the desktop
-   sidebar and the phone navigation.
+   file. Compose the kit from `@/components/<Name>` rather than hand-rolling
+   controls — and **add to that kit**: the component that draws the thing this
+   product is actually about, and the furniture you would otherwise copy-paste
+   into eight pages. The kit is where you start, not where you stop; an app whose
+   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
    to a design direction there and are then accountable to it — it hands you no
-   layouts, because the design is yours to make. Screenshot each screen at 390
-   and 1440 with the seed in place at the END of every milestone, and look at the
-   images — not once at §8, where the only affordable fix is a repaint of eight
-   screens.
-6. **Scenario** (§7), then `status: built`.
+   layouts, because the design is yours to make. What you build here is then
+   judged at step 7, at the end of this milestone rather than once at §8, where
+   the only affordable fix is a repaint of eight screens.
+6. **Scenario** (§7).
+7. **Look at it.** Screenshot every screen this milestone touched, at both
+   widths, with the seed in place, and look at the images. This is a gate, the
+   same as the scenario: a milestone whose screens nobody has seen is not built,
+   it is unproven at the one layer scenarios cannot reach. `references/design.md`
+   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 anything is `built` — and only then set
+   `status: built`, saying in the note what you looked at and what it made you
+   change.
 
 Rules that are not optional:
 
@@ -444,8 +471,8 @@ Rules that are not optional:
   ```typescript
   export const classifications = {
     payment: {
-      paid_at:  { kind: 'date' },                        // -> Date, not an ISO string
-      metadata: { kind: 'json', tsType: 'PaymentMeta' },  // -> parsed object, not unknown
+      paid_at: { kind: 'date' }, // -> Date, not an ISO string
+      metadata: { kind: 'json', tsType: 'PaymentMeta' }, // -> parsed object, not unknown
     },
   }
   ```
@@ -454,6 +481,7 @@ Rules that are not optional:
   `JSON` column with no entry types as `unknown` (the CLI warns PKU481). Add the
   annotation rather than casting around the generated type. Once the file carries
   manual fields, `db migrate` stops overwriting it.
+
 - A `z.date()` on a function's **input** arrives over RPC as an ISO string, not a
   `Date`. Normalise before calling date methods on it (`new Date(value)`), or it
   throws `.getTime is not a function` at runtime — schema validation accepts the
@@ -522,6 +550,7 @@ Three things it says, and what each one asks of you:
   milestone is two milestones — say so to the user rather than deferring again.
   What you may never do is drop the item silently: the plan is what the next
   person reads to know what this milestone was for.
+
 - **PROBLEMS** — something exists but does not do what was planned. A function
   planned as restricted whose meta says `auth: false`; a `cascade` no migration
   declares; a browser scenario that opens a page and asserts it is still on it.
@@ -530,8 +559,9 @@ Three things it says, and what each one asks of you:
   visible, never blocking.
 
 **Do not set the note to `built` while this exits non-zero**, and do not edit the
-plan to match what you built — `plan set` is the architect's seat, and a builder
-rewriting its own denominator is exactly what the split exists to stop.
+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.
 
 ## 7. Prove it — scenarios
 
@@ -546,26 +576,27 @@ 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',
+  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 },
+      { actor: actors.chidi }
     )
     await scenario.then(
       'appears on the owner’s queue',
       'reportShowsOnQueue',
       { id: report.id },
-      { actor: actors.amina },
+      { actor: actors.amina }
     )
     await scenario.then(
       'is invisible to the other owner',
       'reportIsNotVisible',
       { id: report.id },
-      { actor: actors.bilal },
+      { actor: actors.bilal }
     )
     return { id: report.id }
   },

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

@@ -30,6 +30,117 @@ and so is the commitment.
 Be ambitious with it. A direction that could describe any SaaS app has not been
 chosen — it has been defaulted to in words instead of in components.
 
+### The looks you will default to
+
+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
+  library's untouched defaults do not look broken, they look finished. Blue
+  accent, `#dee2e6` borders, `md` radius on everything, `Card` + `Stack` + `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.
+- Near-black with one acid-green or vermilion pop.
+- A purple-to-blue gradient header on white.
+- Inter, or Space Grotesk, as the "safe" typeface.
+- Emoji as section markers; everything centre-aligned; one radius and one shadow
+  stamped on every block, which flattens hierarchy instead of creating it.
+
+If the user asks for one of these, build it — their words win. What is not
+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:
+
+> 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.
+
+If they decline, build; 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.
+
+**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
+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 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
+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
+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
+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.
+
+**What to make.** One self-contained HTML page holding every screen the app
+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
+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
+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.
+
+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:
+
+- The milestones are read off it. A screen in the mock that no milestone builds
+  is a gap in the plan, not a spare drawing.
+- A screen the build turns out to need that the mock does not have means the
+  mock was wrong. Update it, and say you did. Do not let the app and the mock
+  drift and then quietly prefer the app.
+- The knowledge graph still owns the domain — objects, roles, rules. The mock
+  owns what the screens look like. When they disagree about a *fact*, knowledge
+  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
+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
+  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
+  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
+  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
+components have their own metrics and the mock was drawn without them. A built
+screen that reads as the same screen has passed.
+
 ## One screen, designed properly, before the rest exist
 
 Design the first real screen as if it were the only one, and take it further than
@@ -48,6 +159,31 @@ the thing that made it is always yes. Use evidence.
 - **Screenshot every screen and look at the image**, at ~390px and at ~1440px.
   Judging your own UI from source is guessing, and the failures that matter —
   proportion, hierarchy, a wall of identical boxes — are invisible in JSX.
+  **Sort out how you will take that screenshot before you need it**, because an
+  instruction with no working mechanism behind it is one that gets skipped, and
+  this is the one that gets skipped. If a browser-driving tool is wired up, use
+  it. If it is not — or it fails to connect, which happens — the fallback is
+  short enough to write once and keep:
+
+  ```sh
+  CHROME=$(command -v google-chrome || command -v chromium || \
+    command -v chromium-browser || \
+    echo "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
+  "$CHROME" --headless=new --no-sandbox \
+    --remote-debugging-port=9333 --user-data-dir=/tmp/gc-shots &
+  ```
+
+  Resolve the binary rather than hardcoding the macOS path: the same gate has to
+  work on a Linux box and in CI, and a fallback that only starts on one host is
+  a gate that gets skipped everywhere else. If the host already exposes a CDP
+  endpoint, point the script at that instead and start nothing.
+
+  Then drive it over CDP from a script: `Page.navigate`,
+  `Emulation.setDeviceMetricsOverride` for the two widths,
+  `Page.captureScreenshot`, write the PNG, and open it. Sign in the way a person
+  does — click the dev actor switcher on the login page — rather than reaching
+  for the secret the client uses; the UI path is shorter and it also proves the
+  login screen works. Keep the script; you will run it at every milestone.
 - **Run `impeccable`** (`npx impeccable install`, Node 22.18+) and feed it the
   screenshots. It is external, it does not flatter, and it scores execution
   against interaction heuristics. But it audits how well you executed the design
@@ -69,6 +205,77 @@ questions are fixed:
    had?
 6. Would you show it to the user without apologising for it?
 
+## The kit is a floor, not a ceiling
+
+The scaffold hands you a component kit, and the build instructions tell you to
+compose from it rather than hand-roll. Both are right, and together they have a
+failure mode worth naming: an app whose every screen is `Card` + `Stack` + `Text`
+because those were the pieces in the box. That is not a composed design, it is an
+inventory, and it produces the wall of identical boxes further down this file.
+
+**Composing from the kit means using its primitives, not being limited to its
+list.** A product has objects of its own, and the ones that carry its meaning are
+the ones no generic kit ships:
+
+- the thing the product is *about*, rendered as itself — a funding meter, a
+  streak, a seat map, a run's status over time. If a decision note says the
+  progress toward a goal is the primary object, then a component that draws that
+  progress has to exist, or the note is describing an app you did not build.
+- the repeated furniture that is currently copy-pasted — the page header, the
+  section label, the empty state, the recessed panel a form sits in. Eight inline
+  copies of a heading block will not agree with each other; they will disagree by
+  a few pixels each, and the screens will read as unrelated for reasons nobody
+  can point at.
+
+Both kinds are ordinary components built out of kit primitives and theme values.
+Adding them is not hand-rolling, and they are the difference between an app that
+uses a design system and an app that looks like one.
+
+The tell that you skipped this: your `components/` directory maps one-to-one onto
+your data model and contains nothing that names a *quality* of the product.
+
+## Design is a gate on the milestone, not a phase at the end
+
+The loop that actually runs is plan, build, prove, close. Design advice that
+lives outside that loop does not run — it gets read, agreed with, and skipped,
+because nothing blocks on it. Milestones close on green scenarios, and scenarios
+say nothing about how anything looks.
+
+So put it in the loop. **A milestone is not built until its screens have been
+looked at**, in the same sense that it is not built until its scenario passes:
+
+- Screenshot every screen the milestone touched, at both widths, with the seed
+  in place.
+- Look at the images. Not the JSX.
+- Fix what they show, in this milestone, while it is one screen and not eight.
+- Say in the milestone note what you looked at and what you changed.
+
+A milestone closed without that is closed on a claim, not on evidence. The cost
+of being honest about it now is minutes; the cost at §8 is a repaint of the whole
+app, and by then the wrong register has been inherited by every screen so the
+repaint is a rewrite.
+
+### The seed is part of the gate
+
+A screenshot is only evidence if the screen has something on it. Before the gate
+runs, the dev seed must populate what each screen *is for* — not one row, and not
+an empty state.
+
+This is a real and quiet failure: a list app whose seed has no list, a countdown
+whose seed has no dates, judged for weeks against its own empty state while the
+screen it was built for was never once looked at. The empty state is worth
+designing and is not what the milestone is about.
+
+Seed enough to be judged against: several rows, not three identical ones, and a
+deliberate spread of the cases the screen has to hold — a long title that wraps,
+a missing optional field, a picture and no picture, one item in each state the
+screen can show. Anything derived from *today* — a countdown, "3 days ago", an
+expiry — is seeded as an interval from `now`, never as a fixed date: fixed dates
+are correct on the afternoon they are written and meaningless a month later.
+
+Data left over from a scenario run is not a seed. If the screens are full of
+`Filter coffee grinder mttqdvsx`, you are designing against test debris.
+
 ## Facts, not taste
 
 These are not design opinions and are not open to a different answer.
@@ -125,4 +332,15 @@ first one.
 - Every row carries the same buttons, and the buttons outweigh the content.
 - The palette's meaningful colours are also used decoratively, so they have
   stopped meaning anything.
+- A decision note describes something the screens do not do — the note says
+  progress is the primary object and no screen draws progress, or it says warm
+  and not clinical and the error page is still template blue.
+- The theme JSON is rich and the screens are bare. Tokens are the cheapest half
+  of design and the easiest to mistake for the whole of it: a considered palette
+  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`.
 - It looks like the last app you built.
+- It looks like Mantine. Not *built with* Mantine, which it is and should be —
+  but indistinguishable from a component gallery with the brand hue swapped in.