@pikku/skills 0.12.30 → 0.12.33

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.30",
+  "version": "0.12.33",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/skills"
+  },
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -10,13 +15,13 @@
   "type": "module",
   "scripts": {
     "embed": "node scripts/embed.mjs",
-    "tsc": "yarn embed && tsc",
-    "build": "yarn embed && tsc -b",
+    "tsc": "bun run embed && tsc",
+    "build": "bun run embed && tsc -b",
     "ncu": "npx npm-check-updates",
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "bun run build"
   },
   "exports": {
     ".": "./dist/index.js"
@@ -27,10 +32,9 @@
   ],
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "typescript": "^6.0.3",
     "yaml": "^2.9.0"
   },
   "engines": {
     "node": ">=24"
   }
-}
+}

package/skills/pikku-addon/SKILL.md

@@ -324,6 +324,11 @@ wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 
 After registration, run `yarn pikku all` to generate types for the addon's functions.
 
+Give each addon its own wiring file. A deployment unit imports a `wireAddon`
+file only while at least one addon that file wires survives the unit's filter,
+so wiring two addons from one file means a unit needing either one registers
+both and bundles both packages' dependencies.
+
 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-build/SKILL.md

@@ -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).
 

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
@@ -332,6 +338,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
@@ -415,16 +425,26 @@ 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 `status: built`, and say in the note what you looked at and
+   what it made you change.
 
 Rules that are not optional:
 

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.

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

@@ -23,6 +23,85 @@ how a worker deploy fails at runtime instead of at build.
 Always run `plan` before `apply`, and read it. It names what will be created,
 updated and deleted — the deletions are the reason to look.
 
+### How many workers you get
+
+By default a unit holds every function that builds the same set of singleton
+services. One unit per function is available too, but on a large app it means a
+hundred workers whose bundles are mostly the same framework code repeated, and a
+build and an upload for each. `deploy.grouping` in `pikku.config.json` sets the
+shape:
+
+```json
+"deploy": {
+  "grouping": {
+    "strategy": "single",
+    "rules": [
+      { "unit": "console", "addon": "console" },
+      { "unit": "pdf", "tags": ["pdf"] }
+    ]
+  }
+}
+```
+
+`strategy` is the fallback for a function no rule matches:
+
+| strategy | fallback |
+| --- | --- |
+| `services` | one unit per distinct set of singleton services (the default) |
+| `function` | one unit each |
+| `single` | one shared unit |
+
+Rules are ordered, first match wins, and match on `tags`, an `addon` namespace
+or `routes` globs. A rule always beats the strategy, so under `function` a rule
+merges and under `single` or `services` it carves out.
+
+`services` is the default because it is the middle ground: `single` is too
+coarse to reason about and `function` pays a cold start and a deploy step per
+function. Functions are keyed
+on the singleton services their bodies destructure, minus the ones every unit
+builds anyway (`config`, `logger`, `variables`, `schema`, `secrets`, and the
+per-request `rpc`/`mcp`/`channel`/`userSession`). Units are named for that set —
+`svc-todo-store`, `svc-event-hub-todo-store`, `svc-base` for functions needing
+nothing else — and each records it as `servicesKey` in the manifest. On the
+`templates/functions` app it turns 44 units into 10.
+
+The deploy target is part of the key, so a `server` unit is named `-server` and
+can never merge with its serverless twin. That is what keeps `services` from
+tripping the mixed-target refusal below: two functions can carry identical
+services and still run in different places, because a function may name
+`deploy: 'server'` itself without any service crossing it.
+
+Read the shape before trusting it. The partition depends entirely on how varied
+the app's service use is: an app where nearly every function reaches the same
+database collapses to roughly `single` with a few carve-outs. Run `pikku deploy
+plan` and look at the unit list; set `"strategy": "function"` if you want a unit
+per function back.
+
+Changing the strategy renames units, and a unit name is what a queue consumer, a
+scheduled task and a `dependsOn` point at. The manifest rewrites all three, but
+anything holding a unit name outside the manifest does not follow. Units dropped
+from the manifest are not deleted by OSS `deploy()` either (pikkujs/pikku#543) —
+fabric sweeps its dispatch namespace after each deploy, plain pikku leaves the
+old workers in place.
+
+`tags` matches the tags a function inherits from its wirings — `wireHTTP({ ...,
+tags: ['pdf'] })` — as well as any on the function itself, which is where almost
+every project writes them.
+
+Two things that bite:
+
+- **Grouping cannot change a deploy target.** Put a `serverlessIncompatible`
+  function in a group with serverless ones and the build fails naming both
+  sides. Give it its own rule — that refusal is the design, not a bug. To find
+  the culprit, read `deployment-manifest.json`: a unit carries `targetForcedBy`
+  naming the services that crossed it to `server`, and `groupedBy` naming the
+  rule that made it, so you can see which rule to carve the function out of.
+- **Grouping widens secret scope.** Every function in a unit reads every secret
+  that unit is granted, so treat a merge as a security decision too.
+
+Group by something that means something — a domain, a secret scope, a deploy
+cadence. There is deliberately no automatic packing by bundle size.
+
 The frontends build independently (`bun run build` at the root builds every
 workspace). Serve each behind its own hostname, and put the API behind `/api` on
 **all of them**, mirroring the Vite proxy from the multi-app reference: `/api/auth/*` keeps its

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

@@ -53,6 +53,128 @@ Then **write the direction into `knowledge/decisions/design/`** — the words th
 user gave you, what you chose, and what it rules out. The JSON records what the
 theme is; only the note records why.
 
+## The colours the theme has no field for
+
+`brand` is the product's accent. It is not the only colour a screen needs, and
+the missing ones are why "don't hardcode colours per component" gets broken by
+the same agent that wrote it down.
+
+A screen has to say *covered* and *still open*, *fine* and *needs attention* —
+and those are not the accent. Using the accent for them is worse than a stray
+hex: the brand colour stops meaning "this product" and starts meaning "good", so
+it means nothing. But there is no `brand.covered` field, so the value lands
+inline as `#3f7d5c`, once per component, slightly different each time.
+
+Give them a home. A small stylesheet of custom properties, imported once beside
+the Mantine styles, is enough:
+
+```css
+:root:root:root {
+  --app-covered: #3f7d5c;  --app-covered-bg: #e6f1ea;
+  --app-open:    #a8701a;  --app-open-bg:    #fbeedb;
+  --app-sunk:    #fdf7f4;   /* a recessed surface, for forms and asides */
+  --app-hairline: #ecdfd9;  /* NOT var(--mantine-color-gray-2) — see below */
+}
+:root:root[data-mantine-color-scheme='dark'] {
+  --app-covered: #7fc09a;  --app-covered-bg: #1e2f26;
+  --app-open:    #e0ab5c;  --app-open-bg:    #33271a;
+  --app-sunk:    #241b18;
+  --app-hairline: #392b26;
+}
+```
+
+Those values are one app's warm direction, not a palette to copy — derive your
+own from yours.
+
+## Choose the neutrals; do not inherit them
+
+The two details in that snippet that look like typos are the two things most
+likely to make your app look like every other app.
+
+**The hairline is a literal, not `var(--mantine-color-gray-2)`.** Mantine's grey
+ramp is blue-biased — `#f8f9fa`, `#dee2e6`, `#868e96` are all cool — and it is
+what draws card borders, dividers, the shell's edges and every disabled control.
+The theme JSON has `brand` and `structure` and **no neutral field at all**, so
+unless you choose otherwise, every app built from this skill runs its accent on
+somebody else's greys.
+
+If the accent is not itself blue, that mismatch lands on every screen at once:
+warm content ruled off in cold lines, off everywhere and wrong nowhere in
+particular, which is the hardest kind of wrong to find. It survives a careful
+critique because no single screen is broken.
+
+So bias the whole ramp toward the accent — not just the tokens with obvious
+names. Keep Mantine's lightness steps so contrast behaviour and every component
+that picks a step by number are unchanged; move only the hue:
+
+```css
+/* The ramps: hue only. Mantine picks a step by number in either scheme, so
+   these are scheme-independent and belong in the unscoped block. */
+:root:root:root {
+  --mantine-color-gray-0: #faf7f5;  --mantine-color-gray-5: #b8a49d;
+  --mantine-color-gray-1: #f5efec;  --mantine-color-gray-6: #93807a;
+  --mantine-color-gray-2: #efe6e2;  --mantine-color-gray-7: #574a45;
+  --mantine-color-gray-3: #e6dad5;  --mantine-color-gray-8: #3d332f;
+  --mantine-color-gray-4: #d8c8c2;  --mantine-color-gray-9: #2a1f1b;
+  --mantine-color-dark-0: #f3e9e4;  --mantine-color-dark-5: #4a3a34;
+  --mantine-color-dark-1: #cdbdb6;  --mantine-color-dark-6: #392b26;
+  --mantine-color-dark-2: #a8938c;  --mantine-color-dark-7: #241b18;
+  --mantine-color-dark-3: #7a655e;  --mantine-color-dark-8: #1b1512;
+  --mantine-color-dark-4: #5c4a44;  --mantine-color-dark-9: #120d0b;
+}
+
+/* Ground, text and border are a different colour in each scheme, so each one
+   is set in the scheme it belongs to. A scheme-dependent token left in the
+   block above is the classic unreadable-in-dark bug. */
+:root:root:root[data-mantine-color-scheme='light'] {
+  --mantine-color-body: #fdfaf8;
+  --mantine-color-text: #2a1f1b;
+  --mantine-color-default-border: #ecdfd9;
+  --mantine-color-dimmed: #7a625c;      /* keep AA: ~5.4:1 on the body above */
+  --mantine-color-placeholder: #826a64; /* ~4.8:1 */
+}
+:root:root:root[data-mantine-color-scheme='dark'] {
+  --mantine-color-body: #1b1512;
+  --mantine-color-text: #f3e9e4;
+  --mantine-color-default-border: #392b26;
+  --mantine-color-dimmed: #a8938c;      /* ~5.6:1 on the body above */
+  --mantine-color-placeholder: #8c7a74; /* ~4.7:1 */
+}
+```
+
+Check the four text tokens against your own grounds rather than copying these —
+`dimmed` is the most-used text colour in the app and the easiest to drop below
+4.5:1 while making it prettier, and it has to clear the bar on *both* grounds.
+
+**The selector is tripled on purpose.** Mantine's `cssVariablesResolver` injects
+its own `:root` block into `<head>` at runtime, which lands *after* your
+stylesheet and wins on source order at equal specificity. A plain `:root` here is
+silently reverted: the file reads correct, the app renders Mantine's defaults,
+and nothing errors. Repeating the pseudo-class raises specificity without adding
+an element to the selector.
+
+This one costs a whole pass if you meet it without knowing: you diagnose the
+colours correctly, write the right values, reload, and see no change — so you
+assume the diagnosis was wrong. **The only thing that catches it is looking at a
+screenshot and disbelieving the CSS.**
+
+Name them for what they *mean* in this product, never for the colour — `covered`,
+not `green`. The name is the whole value: it survives a change of palette, and it
+is the thing that makes the second use agree with the first. Define both colour
+schemes at once; a token defined only in light is the classic unreadable-in-dark
+bug, and Mantine will happily render it.
+
+The same file is where a couple of other things belong that the theme JSON has no
+field for and every screen otherwise re-invents: the hairline that separates rows
+in a list, the recessed surface a form sits on so it does not carry the same
+weight as the content it adds to, and the one animation the product is allowed
+(behind `prefers-reduced-motion`). Two or three rules, not a framework.
+
+If the app ships template screens you did not write — the error and not-found
+pages usually — read them before you call the palette done. They arrive with the
+scaffold's colours hardcoded, and a stock blue accent on an app whose direction
+says warm is the single loudest contradiction in the build.
+
 **Set the theme once, don't hardcode colours per component.** A screen full of
 inline `color="blue"` and one-off hex values is why apps look templated. Change
 the theme, not the components — and keep it theme-aware for light and dark.

package/skills/pikku-knowledge/SKILL.md

@@ -284,6 +284,20 @@ pikku knowledge plan defer <milestone> <item> -r "<why>"
 
 `progress` reconciles the plan against pikku's generated meta — set membership, never anyone's status — and exits non-zero while the first pass is short, or while anything already built contradicts the plan. Unbuilt work in a later pass is reported, not blocked; a function that shipped wide open against a planned permission rule blocks from any pass, because that is a hole rather than a backlog. Writing a plan is its own seat: read `pikku-architect`. Building against one is `pikku-build`.
 
+### A finished milestone is a tombstone
+
+**Once a milestone reaches `built`, its note and its plan are closed. Do not edit either.** Not to correct the wording, not to fold in what the build actually turned out to need, not to add the item everyone agrees should have been there. A finished milestone is the record of what was agreed and what was measured against it, and a record that can be revised afterwards measures nothing.
+
+This is the rule the shape of the thing already implies. `progress` reconciles a plan against generated meta and fails when what shipped contradicts it — a check with no force at all if the losing side of the contradiction may simply be rewritten. `attempts:` brakes a note nothing can satisfy, and refunds that budget when the note's content really changes; a `built` note that keeps changing is that brake removed. Both only work while the plan stays still.
+
+So when a `built` milestone turns out to be wrong or incomplete, **the answer is always a new note, never an edit to the old one**:
+
+- It needed more than it said → a new milestone, which may name the old one.
+- It was built differently than planned → that is what `progress` is for. Reconcile forward, or record a decision saying why the plan was not the right shape.
+- It was simply wrong → a decision note that supersedes it. The wrong milestone stays where it is; a base whose history is edited cannot answer *why* anything is the way it is, which is most of what a base is for.
+
+The exception, and it is narrow: bookkeeping the loop owns. `statusAt:` and `attempts:` are written by whatever moved the note, at any status, and are bookkeeping rather than content. Nothing else about a `built` note moves again.
+
 ## Profiles built on this one
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.

package/skills/pikku-services/references/services.md

@@ -1,6 +1,5 @@
 # Pikku Services (Dependency Injection)
 
-
 ## Before You Start
 
 ```bash
@@ -195,6 +194,13 @@ const createSingletonServices = pikkuServices(async (config) => {
 })
 ```
 
+A deployment split regenerates this manifest **per unit**, so the same
+`services.ts` sees a different manifest in each bundle and each unit builds only
+what its own functions, middleware and permissions reach. A `services.ts` that
+constructs unconditionally gets none of that: every unit pays for every service,
+and the split buys nothing but duplicated bytes. Branching on the manifest is
+what makes the split real.
+
 ### Audit Wire Service
 
 `createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and Fabric notes, read `references/audit-wire-service.md`.