@pikku/skills 0.12.33 → 0.12.35

package/package.json

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

package/skills/pikku-addon/SKILL.md

@@ -47,7 +47,7 @@ wireAddon({
   package: string,                 // NPM package name (e.g. '@pikku/addon-todos')
   rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
   auth?: boolean,                  // Require a session for every function in the addon
-  mcp?: boolean,
+  mcp?: boolean | string[],        // true: every function the addon declared mcp: true; a list: the tools this app offers, typed against the addon's function names
   tags?: string[],                 // Tags applied to all addon functions
   scopes?: string[],               // Required of every function, on top of its own
   secretOverrides?: Record<string, string>,      // Remap secret names (and grant them)
@@ -324,11 +324,6 @@ 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-architect/SKILL.md

@@ -3,32 +3,45 @@ 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),
   the plan already exists and the job is to build it (use pikku-build), or the ask is a one-off
   edit to a working app.
 installGroups: [core]
+agent:
+  tools: read, write, edit, bash, grep
+  timeoutMs: 1800000
+  acceptance:
+    level: verified
+    evidence: [changed-files, validation-output]
+    verify:
+      - id: knowledge-consistent
+        command: pikku knowledge validate
+      - id: plan-accepted
+        command: pikku knowledge next --require dispatch,idle
+
 ---
 
 # 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 +51,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 +278,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

@@ -13,19 +13,31 @@ description: >-
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *), Bash(git branch *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
 argument-hint: '[feature description]'
 installGroups: [core]
+agent:
+  tools: read, write, edit, bash, grep
+  timeoutMs: 5400000
+  acceptance:
+    level: verified
+    evidence: [changed-files, tests-added, commands-run, validation-output]
+    verify:
+      - id: knowledge-consistent
+        command: pikku knowledge validate
+      - id: typechecks
+        command: pikku all --tsc-summary
+
 ---
 
 # Build on Pikku
 
 ## 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
@@ -53,9 +65,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
@@ -66,11 +79,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

@@ -81,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/*`
@@ -218,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',
@@ -229,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: {},
   },
@@ -369,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
@@ -396,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`.
 
@@ -416,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
@@ -443,8 +448,10 @@ over, and an uncovered function is a half-milestone whether or not the note says
    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.
+   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:
 
@@ -464,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
     },
   }
   ```
@@ -474,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
@@ -542,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.
@@ -550,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
 
@@ -566,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-fabric/SKILL.md

@@ -327,6 +327,19 @@ pikku fabric validate           # must pass clean
 pikku fabric deploy apply --production -y
 ```
 
+`init` and `link` import into whichever organization your session is in. When
+you belong to several — a personal one and a company one, say — name the target
+with `--organization`, taking a slug, a display name or an id:
+
+```bash
+pikku fabric link --organization vlandor
+```
+
+You have to be a member of the organization you name, and its GitHub account
+has to be connected already: importing a `github.com/<owner>/<repo>` repo needs
+the Fabric GitHub App installed on `<owner>` _and_ linked to that organization,
+or the import refuses by name.
+
 The branch is positional and defaults to the checked-out one, and `-y` is the
 short form of `--auto-approve`, so a one-shot deploy is:
 

package/skills/pikku-knowledge/SKILL.md

@@ -14,6 +14,16 @@ description: >-
   functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
   note), or to write a scenario test (use pikku-scenario).
 installGroups: [core]
+agent:
+  tools: read, write, edit, bash, grep
+  timeoutMs: 1800000
+  acceptance:
+    level: verified
+    evidence: [changed-files, validation-output]
+    verify:
+      - id: knowledge-consistent
+        command: pikku knowledge validate
+
 ---
 
 # Pikku Knowledge
@@ -266,7 +276,7 @@ Two things about the output matter if you are driving it:
   `options` is empty when the answer is free text, and an empty list means offer free
   text — never invent choices to fill it.
 
-`hold` means a profile's own gate is holding the milestone and no seat this loop knows
+`hold` means a profile's own gate is holding the milestone and nothing this loop knows
 about can clear it. It names the hold and the notes it is about; what to do then
 belongs to that profile, not here.
 
@@ -282,7 +292,7 @@ pikku knowledge plan progress <milestone>          # what it still owes, read fr
 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`.
+`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. How a plan is written is `pikku-architect`; building against one, and the order plan-then-build, is `pikku-build`.
 
 ### A finished milestone is a tombstone
 

package/skills/pikku-mantine/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pikku-mantine
+description: >-
+  Use when building a Mantine UI on top of a Pikku backend — rendering dates that came back from a
+  generated client, keeping layout flow-relative so the app survives an RTL locale, and branching on
+  colour scheme without hardcoding a shade. TRIGGER when: putting a value from usePikkuQuery or an
+  RPC response on screen, writing margins/padding/alignment in Mantine props or CSS, choosing a date
+  input, or handling light/dark. DO NOT TRIGGER when: the data does not come from a Pikku client
+  (this is only about what the generated clients hand you), or for user-facing copy (use pikku-i18n).
+installGroups: [client]
+---
+
+# Mantine on a Pikku client
+
+## Dates — always format before rendering
+
+The generated clients run `transformDates`, which revives **fully-zoned ISO-8601 instants** —
+`2026-03-14T08:12:00Z`, `2026-03-14T08:12:00.000+01:00` — into `Date` objects and touches nothing
+else. A bare `2026-03-14`, a zoneless `2026-03-14T08:12:00` and an impossible `2026-02-31T00:00:00Z`
+all stay the strings the server sent. So a field's runtime type follows the VALUE, not the schema:
+one column can arrive as a `Date` from one row and a string from the next.
+
+Two consequences, and both compile:
+
+- **A string method on one white-screens the page.** `row.createdAt.split('T')[0]` type-checks
+  against nothing useful and blows up at runtime. There is no string to slice.
+- **A raw `Date` dropped into JSX crashes the route.** `<Text>{row.createdAt}</Text>`, a table cell,
+  a `<Badge>` — React throws `Objects are not valid as a React child (found: [object Date])` and the
+  page falls into its error boundary. Nothing catches it before the screen is white, which makes it
+  the most common broken page in a build.
+
+**Format with dayjs.** It is Mantine's own date library, already shipped alongside `@mantine/dates`,
+and it takes either a `Date` or a string. Never `toLocaleDateString`, `date-fns` or `luxon`.
+
+```tsx
+import dayjs from 'dayjs'
+
+<Text>{dayjs(row.dueOn).format('D MMM YYYY')}</Text>        // 15 Jun 2026
+<Text>{dayjs(row.createdAt).format('D MMM YYYY, HH:mm')}</Text>
+```
+
+A relative "2 days ago" via dayjs `relativeTime` is fine. Coercing instead of formatting
+(`` `${d}` ``, `String(d)`, `d + ''`) does not crash but prints
+`Mon Jun 15 2026 02:00:00 GMT+0200` — a different bug, equally wrong.
+
+Date **inputs** are `@mantine/dates` — `DatePickerInput`, `DatePicker`, `Calendar` — never a raw
+`<TextInput type="date">`. Those are pickers and they are not a schedule: Mantine ships no
+week/time-grid component, so a diary, rota, timetable or booking week is a grid you build, not a
+`Calendar` with the time-of-day left out. `Calendar` with `renderDay` IS right for "a few things on
+each day of a month", like a content calendar or a holiday planner.
+
+All of this applies to stub and fixture dates exactly as it does to real data.
+
+## RTL-safe styles
+
+Write layout styles flow-relative so the UI works in both LTR and RTL languages. Pikku's i18n ships
+Arabic, Hebrew, Farsi and Urdu support, and a physical margin is what breaks under it.
+
+| Avoid                         | Use instead                                |
+| ----------------------------- | ------------------------------------------ |
+| `ml`, `mr`, `pl`, `pr`        | `ms`, `me`, `ps`, `pe`                     |
+| `text-align: left/right`      | `text-align: start/end`                    |
+| `margin-left`, `margin-right` | `margin-inline-start`, `margin-inline-end` |
+| `flex-direction: row-reverse` | `dir` attribute or logical properties      |
+
+Mantine shorthand: `ms` = margin-inline-start, `me` = margin-inline-end, `ps` = padding-inline-start,
+`pe` = padding-inline-end.
+
+## Dark mode
+
+Use Mantine's `light-dark()` utility or `useMantineColorScheme`, and only with colours that already
+come from the theme — never introduce a literal colour or a shade string for one scheme.
+
+```tsx
+// Correct
+<Box bg="var(--mantine-color-body)">
+
+// Wrong — scheme branch with hardcoded Mantine shades
+<Box bg={theme.colorScheme === 'dark' ? 'dark.6' : 'gray.0'}>
+```

package/skills/pikku-wiring/references/http.md

@@ -147,6 +147,14 @@ it is optional because the same function can be reached over plain HTTP or RPC,
 where there is no stream to send on. The `if (channel)` guard is what lets one
 function serve both; the return value is the non-streaming answer.
 
+A function that throws once the stream is open cannot answer with a status code,
+so the runner ends the stream with `{ type: 'error', errorText }` then
+`{ type: 'done' }`. A route whose client parses a different event protocol says
+so with `streamProtocol`, and the failure is written in that one instead —
+`streamProtocol: 'agui'` ends the stream with a single AG-UI `RUN_ERROR` and
+nothing after it. The default is `'pikku'`; the generated agent stream routes
+set `'agui'`.
+
 ### Generated Fetch Client
 
 After `npx pikku all`, a type-safe client is generated:

package/skills/pikku-wiring/references/mcp.md

@@ -186,6 +186,63 @@ When you add a tool, tell whoever asked for it the URL. An assistant that cannot
 be pointed at an endpoint has not been connected to anything, and `/mcp` is the
 whole answer.
 
+## Authentication
+
+An MCP endpoint is not gated as a whole. Pikku already knows, tool by tool, which
+calls need a session, and the endpoint answers accordingly:
+
+| Declaration                              | Anonymous call      |
+| ---------------------------------------- | ------------------- |
+| `pikkuSessionlessFunc` with `mcp: true`  | runs                |
+| the same, plus `auth: true`              | `401` + a challenge |
+| `pikkuFunc` with `mcp: true`             | `401` + a challenge |
+
+```typescript
+// public: anyone connecting to /mcp can call this
+export const searchCatalog = pikkuSessionlessFunc<Query, Results>({
+  mcp: true,
+  func: async (services, data) => services.catalog.search(data),
+})
+
+// private: an anonymous caller is challenged, never dispatched
+export const myOrders = pikkuFunc<void, Order[]>({
+  mcp: true,
+  func: async (services, _data, session) =>
+    services.orders.forUser(session.userId),
+})
+```
+
+The `401` carries a `WWW-Authenticate` header naming the endpoint's RFC 9728
+Protected Resource Metadata document, which the server also serves — `/mcp` is
+described at `/.well-known/oauth-protected-resource/mcp`. That pair is what an
+MCP client needs to discover an authorization server and start an OAuth flow;
+a refusal delivered as a JSON-RPC result instead reads to a client as a tool that
+failed, and no discovery happens.
+
+`tools/list` is never gated, so a client can still see what exists before it has
+a token.
+
+Nothing needs configuring: the metadata document defaults to advertising the
+origin the request arrived on, which is right whenever the app is its own
+authorization server. To point elsewhere, pass `mcpAuth` to the runtime:
+
+```typescript
+new PikkuNodeHTTPServer(config, logger, {
+  mcpJson,
+  mcpAuth: {
+    authorizationServers: ['https://auth.example.com'],
+    scopesSupported: ['mcp'],
+    resourceName: 'Example API',
+  },
+})
+```
+
+The transport never verifies a token itself — session resolution stays with the
+app's own middleware, exactly as it works over HTTP. One consequence: only a
+request carrying *no* credentials is challenged. A token that is present but
+expired is dispatched, and the runner's refusal reaches the client as a tool
+error.
+
 ## Red flags
 
 | Symptom                                          | Cause                                                           |
@@ -195,3 +252,5 @@ whole answer.
 | Resource returning `{ uri, blob, mimeType }`     | Resources are text only: `{ uri, text }`                        |
 | Client sees a tool with no description           | `mcp: true` without a `description` — check the codegen warning |
 | `/mcp` 404s                                      | Nothing to serve yet — the mount is skipped until one tool, resource or prompt exists |
+| A tool an assistant should be able to call returns `401` | It is a `pikkuFunc`, or declares `auth: true` — make it a `pikkuSessionlessFunc` if it is genuinely public |
+| A private tool returns a result rather than a challenge | The request carried a credential, so it was dispatched; only a call with none is refused at the door |