@pikku/skills 0.12.34 → 0.12.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.34",
+  "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

@@ -12,6 +12,18 @@ description: >-
   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

package/skills/pikku-build/SKILL.md

@@ -13,6 +13,18 @@ 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

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

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 |