@pikku/skills 0.12.52 → 0.12.55

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

@@ -1,23 +1,45 @@
 # 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 — virtual users 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 deploy-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.
+from here: no hosted account, no card, no hosted build — while keeping the
+project shaped so a hosting platform can adopt it later with zero rework.
 
 **Four phases, and you do not skip ahead:**
 
 1. Write the knowledge graph — what the app IS, before any code
-2. Declare the people and the apps — personas, roles, frontends
+2. Declare the people and the apps — virtual users, roles, frontends
 3. File the work as changes — grouped into changesets, in dependency order
 4. Build them one changeset at a time — each proven by a scenario before it merges
 
 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
+three languages, §2 the knowledge graph, §3-§4 virtual users 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
 
@@ -46,7 +68,7 @@ One command, run once, now — not later when you start building. It wires the
 `#pikku` import alias the generated code depends on. On a fresh scaffold `.pikku/`
 is empty, so **every command that touches codegen fails until this has run** —
 including ones you would reasonably reach for while still planning, like
-`pikku persona list`. Those failures look alarming (`Cannot find module
+`pikku virtual-user list`. Those failures look alarming (`Cannot find module
 '#pikku/workflow/pikku-workflow-types.gen.js'`, `Schema generation failed for 16
 schemas`) and they are nothing but this missing step.
 
@@ -59,7 +81,7 @@ Ask **three to five** questions that actually change the schema or the screens,
 in one message. Then stop; do not interview the user.
 
 - **Who uses it — who are the distinct kinds of people?** Ask this however small
-  the app is. The answer becomes §3's personas and roles, and you build only the
+  the app is. The answer becomes §3's virtual users and roles, and you build only the
   roles they name.
 - **What are the two or three core objects?**
 - **What is the main thing someone does on their first visit?** This answer
@@ -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
@@ -99,11 +121,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 virtual user 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/*`
@@ -138,7 +160,7 @@ A German medical portal, correctly:
 ```jsonc
 // project.inlang/settings.json
 { "baseLocale": "en", "locales": ["en", "de"] }
-// apps/app/src/i18n/active.json   (or: fabric i18n --default-locale de)
+// apps/app/src/i18n/active.json
 { "defaultLocale": "de" }
 // pikku.config.json
 { "metaLocale": "de" }
@@ -206,14 +228,14 @@ bunx --bun pikku knowledge validate
 
 ## PHASE 2 — Who it is for, and what it is made of
 
-## 3. Declare the people — personas and roles
+## 3. Declare the people — virtual users and roles
 
 The answer to "who uses it" becomes code, in one file:
-`packages/functions/src/personas.ts`. It ships with a single `visitor`; add the
+`packages/functions/src/virtual-users.ts`. It ships with a single `visitor`; add the
 people the user named, and the roles they imply.
 
 ```typescript
-import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+import { defineVirtualUsers } from '#pikku/scopes/pikku-virtual-users.gen.js'
 import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
@@ -229,7 +251,7 @@ defineSystemRole({
   },
 })
 
-definePersonas({
+defineVirtualUsers({
   visitor: {
     name: 'Visitor',
     jobTitle: 'Synthetic health-check user',
@@ -260,18 +282,18 @@ definePersonas({
 })
 ```
 
-- **Keep `visitor`.** The shipped scenarios name `actors.visitor`, and PKU677
-  requires a browser step's actor to be a literal `actors.<name>`. Removing it
-  stops `actors.visitor` type-checking, which fails `pikku all`, and nothing you
+- **Keep `visitor`.** The shipped scenarios name `virtualUsers.visitor`, and PKU677
+  requires a browser step's virtual user to be a literal `virtualUsers.<name>`. Removing it
+  stops `virtualUsers.visitor` type-checking, which fails `pikku all`, and nothing you
   write after that registers.
-- **One `definePersonas` call for the whole project.** Codegen builds the
-  `PersonaId` union from it, materialises one scenario actor per person, and
+- **One `defineVirtualUsers` call for the whole project.** Codegen builds the
+  `VirtualUserId` union from it, materialises one scenario virtual user per person, and
   seeds a user row each. A second call site is a second answer to "who uses this
   app".
 - **`roles` is typechecked against `defineSystemRole`.** An undeclared role is a
   build error rather than a runtime surprise.
-- **Never write an email address.** Each is derived from the persona id and
-  `scenarios.emailDomain` in `pikku.config.json` — `visitor@actors.local`.
+- **Never write an email address.** Each is derived from the virtual user id and
+  `scenarios.emailDomain` in `pikku.config.json` — `visitor@virtualuser.local`.
   Hand-writing one is how a run signs in as somebody who was never created.
 - **Declare a second person of the same kind** whenever the rule is ownership
   (`bilal` above). "You see yours, not theirs" is not testable with one owner,
@@ -283,14 +305,14 @@ definePersonas({
   in the function's `permissions` field (§6), never in the body. Read the
   `pikku-auth` skill.
 
-`pikku persona list` shows who is declared and `pikku roles audit` reports roles
+`pikku virtual-user list` shows who is declared and `pikku roles audit` reports roles
 the database still holds that code no longer declares — both need §0's bootstrap
 to have run, and both are worth a look once it has.
 
 **One warning about the scaffold's own notes:** `knowledge/index.md` may claim
-the people live in `pikku.config.json`, put there by a persona command.
-That is stale. In this template they live in `personas.ts` as above, and
-`pikku.config.json` carries no personas key at all — only `scenarios.emailDomain`.
+the people live in `pikku.config.json`, put there by a virtual user command.
+That is stale. In this template they live in `virtual-users.ts` as above, and
+`pikku.config.json` carries no virtual users key at all — only `scenarios.emailDomain`.
 Trust the file you can read over the note describing it.
 
 ## 4. Declare the apps — one API, several frontends
@@ -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.
@@ -352,7 +374,7 @@ What a change is:
 - **One commit's worth.** "The owner sees this month's arrears" is a change,
   or a few. "Add the database schema" is not; it is a step inside one.
 - **It ends in something a person can do**, in a browser, signed in as a named
-  persona. If you cannot say what they see when it is done, that is a
+  virtual user. If you cannot say what they see when it is done, that is a
   `questions/` note, not a change.
 
 If §1's screen mock was made — approved, or drawn because nobody answered —
@@ -432,7 +454,7 @@ while the plan is short.
    configuration and belongs in a migration, not here.
    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
+   against zero rows. Seed rows each virtual user sees differently — with an ownership
    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;
@@ -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
@@ -515,28 +537,26 @@ Rules that are not optional:
   tables. A domain table with one of those names — a class _session_, a drop-in
   _session_ — collides in the migration. Name it for the domain instead
   (`evening`, `class_meeting`) and keep the word in the UI copy.
-- The template's `/` redirects to `/app`, so the login screen — and its "Sign in
-  as …" switcher — is what a signed-out visitor sees first. Replace `/` with a
-  public homepage and that stops being true: mount `<DevActorSwitcher />` in the
-  public layout as well, or a reviewer lands on a site with no way in.
+- The template's `/` redirects to `/app`, so the login screen is what a
+  signed-out visitor sees first. Replace `/` with a public homepage and a
+  reviewer lands on a site with no way in: link it to the login screen.
 
-Before the first run, make sure `.env` at the project root holds the two
-secrets the local stack needs. `bun run dev` appends whichever is missing, but
-check anyway — a project scaffolded from an older template, or a `.env` copied
-in from elsewhere, can lack one, and neither failure names the variable:
+Before the first run, make sure `.env` at the project root holds the secret
+the local stack needs. `bun run dev` appends it if missing, but check anyway —
+a project scaffolded from an older template, or a `.env` copied in from
+elsewhere, can lack it, and the failure does not name the variable:
 
 - `BETTER_AUTH_SECRET` — without it the first sign-up is a 500.
-- `SCENARIO_ACTOR_SECRET` — without it `/api/auth/sign-in/actor` is disabled:
-  every scenario fails at sign-in before its first step, and the "Sign in as …"
-  switcher renders nothing.
+
+Virtual user sign-in needs nothing in `.env`: `pikku dev` creates its own key
+pair and hands the app the public half.
 
 ```sh
 grep -q '^BETTER_AUTH_SECRET=' .env 2>/dev/null || echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
-grep -q '^SCENARIO_ACTOR_SECRET=' .env 2>/dev/null || echo "SCENARIO_ACTOR_SECRET=$(openssl rand -base64 32)" >> .env
 ```
 
 `.env` is gitignored and local only — never commit it. A deployed stage gets its
-secrets from the platform (`pikku fabric secrets`), not from this file.
+secrets from the hosting platform, not from this file.
 
 Then run it:
 
@@ -549,13 +569,10 @@ frontend running against a dead API looks exactly like an app bug, so if every
 request fails, check that both halves came up.
 
 **Start the stack through `bun run dev`, not by launching `vite` or `pikku dev`
-yourself.** The "Sign in as …" switcher asks the API for its personas at
-runtime, so the frontend needs nothing baked in — but it does need to reach
-_your_ API. If you start the frontend on its own (say :3000 is taken by another
-project), point `VITE_API_PROXY` at your API: the dev proxy defaults to
-`http://localhost:3000`, so beside another project's server the switcher lists
-_its_ personas, or none, which reads like a missing switcher rather than the
-wrong server.
+yourself.** The frontend needs to reach _your_ API. If you start the
+frontend on its own (say :3000 is taken by another project), point
+`VITE_API_PROXY` at your API: the dev proxy defaults to `http://localhost:3000`,
+so beside another project's server every request goes to the wrong API.
 
 The `--bun` in `bunx --bun pikku …` is load-bearing — keep it. Without it the
 CLI's `#!/usr/bin/env node` shebang hands the process to whatever Node is on
@@ -639,20 +656,20 @@ only when there is nothing to hang a check on.
 
 ## 7. Prove it — scenarios
 
-A scenario is a user journey run as one of your personas, over the real
-transport, with that persona's session. It is the only kind of test worth writing
+A scenario is a user journey run as one of your virtual users, over the real
+transport, with that virtual user's session. It is the only kind of test worth writing
 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:
 
 - the shape of a scenario, and `do` vs `given`/`when`/`then`
 - what survives DSL extraction — a `then` in `return` position asserts nothing,
-  and a shared setup helper credits its steps to the wrong actor
+  and a shared setup helper credits its steps to the wrong virtual user
 - what to assert — refusals must read the REASON, totals must be deltas, and the
   assertion nobody writes is the row count
 - living without a state reset: the suite must be green on its SECOND run
@@ -666,7 +683,7 @@ bunx --bun pikku scenario run local --spawn                  # server-side, the
 bunx --bun pikku scenario run local --spawn --run browser    # the same journeys, driven as a human
 ```
 
-In a multi-app project that one run covers both frontends: each persona carries
+In a multi-app project that one run covers both frontends: each virtual user carries
 its own `app` and `@pikku/playwright` resolves the base url from the
 environment's `appUrls` map, so there is no second environment to run.
 
@@ -701,13 +718,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.
@@ -716,11 +733,11 @@ Three separate jobs, and conflating them is why open-source builds come out
 looking like the template:
 
 - **Direction** — deciding what it should look like. **No open-source tool does
-  this.** Fabric has `fabric-theme`; you have §1's answer and 8a below.
+  this.** A hosting platform may offer one; you have §1's answer and 8a below.
 - **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 +749,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 +772,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 +809,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.
@@ -812,13 +826,13 @@ seven copies deep. Run `pikku db reset` and restart the dev server before you
 screenshot anything — a screen judged against that data gets designed for a
 problem it does not have.
 
-## 9. Ship it, and stay Fabric-ready
+## 9. Ship it, and stay deploy-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.
+API, the pre-release gate to run, and the contract that keeps the project
+importable by a hosting platform later rather than a migration.
 
 The app is not handed over without its user guide. The scenarios you wrote are
 already its skeleton: read **pikku-guide**, write one page per audience citing
@@ -837,16 +851,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 deploy-readiness contract (§9)
 - Sibling skills: `pikku-knowledge` (§2), `pikku-auth` (§3),
-  `pikku-scenario` (§7, §7a), `pikku-deploy` and `pikku-fabric` (§9)
+  `pikku-scenario` (§7, §7a), and `pikku-deploy` (§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).