@pikku/skills 0.12.52 → 0.12.54

package/skills/pikku-wiring/SKILL.md

@@ -3,14 +3,15 @@ name: pikku-wiring
 description: >-
   Use when exposing a Pikku function over a transport — HTTP routes and SSE, WebSocket channels,
   typed realtime pub/sub, internal and exposed RPC, queue workers, cron schedules, event triggers,
-  MCP tools/resources/prompts, CLI commands, or a Slack gateway. Covers choosing the wiring, the
-  model every wiring shares, and what differs: which function type each needs, where a session
-  comes from, and which calls throw instead of returning. TRIGGER when: code uses wireHTTP,
-  defineHTTPRoutes, wireChannel, wireQueueWorker, wireScheduler, wireTrigger, wireTriggerSource,
-  wireCLI, wireMCPResource, wireMCPPrompt, `mcp: true`, `sse: true`, `expose: true`, rpc.invoke,
-  SlackGatewayAdapter, or the user asks how to expose, route, schedule, queue, stream or publish a
-  function. DO NOT TRIGGER when: writing the function body itself (use pikku-concepts), declaring
-  authorization (use pikku-auth), or serving the app on a runtime (use pikku-deploy).
+  MCP tools/resources/prompts, CLI commands, or a Slack gateway. Covers choosing the wiring, what
+  every wiring shares, and what differs: function type, session source, and which calls throw
+  instead of returning. TRIGGER when: code uses wireHTTP, defineHTTPRoutes, wireChannel,
+  wireQueueWorker, wireScheduler, wireTrigger, wireTriggerSource, wireCLI, wireMCPResource,
+  wireMCPPrompt, `mcp: true`, `sse: true`, `expose: true`, rpc.invoke, SlackGatewayAdapter, or the
+  user asks how to expose, route, schedule, queue, stream or publish a function. DO NOT TRIGGER
+  when: writing the function body (use pikku-concepts), authorization (use pikku-permissions), serving on
+  a runtime (use pikku-deploy), building a live-updating view (use pikku-realtime), or sending
+  outgoing webhooks (use pikku-webhook).
 installGroups: [core]
 ---
 
@@ -53,7 +54,7 @@ Three consequences that hold for every wiring below:
   are merged into the function's `data` argument.
 - **Permissions are never declared on the wiring.** Wire-level permissions were
   removed in #972 — declare them on the function (`pikkuFunc({ permissions })`,
-  see `pikku-auth`) or app-wide via `addGlobalPermission`. Tags and
+  see `pikku-permissions`) or app-wide via `addGlobalPermission`. Tags and
   patterns now target *middleware* only.
 - **The wire is the third argument**, not a service. `channel`, `rpc`, `session`,
   `setSession`, `mcp`, `queue`, `scheduledTask` and `cli` all live there.
@@ -83,15 +84,15 @@ subpath it exempts — the service implementations bootstrap picks.
 
 | Reach for | When | Reference |
 | --- | --- | --- |
-| **HTTP** | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only) | `references/http.md` |
+| **HTTP** | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only) | `references/http.md`; every field in `references/http-options.md` |
 | **Channel** | A hand-designed WebSocket protocol with your own action routing | `references/channel.md` |
-| **Realtime** | Typed pub/sub push — the scaffolded `/events` channel and SSE topics | `references/realtime.md` |
+| **Realtime** | Typed pub/sub push — the scaffolded `/events` channel and SSE topics, plus subscribing to any other `sse: true` route or channel from the client | `references/realtime.md` |
 | **RPC** | One function calling another, or dispatching a name from outside | `references/rpc.md` |
 | **Queue** | Reliable background work that must survive a crash and retry | `references/queue.md` |
 | **Scheduler** | Recurring work on a cron expression | `references/scheduler.md` |
 | **Trigger** | Reacting in-process to an external event source (Redis pub/sub, PG LISTEN) | `references/trigger.md` |
 | **MCP** | Exposing functions to an AI assistant as tools, resources or prompts | `references/mcp.md` |
-| **CLI** | A terminal program with commands, subcommands and options | `references/cli.md` |
+| **CLI** | A terminal program with commands, subcommands and options | `references/cli.md`; end-to-end walkthrough in `references/cli-complete-example.md` |
 | **Gateway** | An inbound integration from a third-party product — Slack is the shipped adapter | `references/gateway-slack.md` |
 
 Realtime and Channel are the pair most often confused. If the shape is "server

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

@@ -1,5 +1,11 @@
 # Pikku WebSocket Wiring
 
+## Contents
+
+- API Reference
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 ### `wireChannel(config)`
@@ -33,7 +39,7 @@ wireChannel({
 
 Note there is **no `permissions` key on a message wiring** — wire-level
 permissions were removed in #972. Authorization lives on the function's own
-`permissions` field (see `pikku-auth`).
+`permissions` field (see `pikku-permissions`).
 
 ### `pikkuChannelMiddleware(fn)`
 

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

@@ -1,5 +1,11 @@
 # Pikku CLI Wiring
 
+## Contents
+
+- API Reference
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 ### `wireCLI(config)`
@@ -212,4 +218,4 @@ session for local runs. Don't hand-write or edit the generated channel file.
 
 ## Complete Example
 
-For a full functions + renderers + nested-subcommand wiring walkthrough, see `cli-complete-example.md`.
+For a full functions + renderers + nested-subcommand wiring walkthrough, see the CLI complete example listed in `SKILL.md`.

package/skills/pikku-wiring/references/gateway-slack.md

@@ -1,5 +1,11 @@
 # Pikku Gateway Slack
 
+## Contents
+
+- Installation
+- API Reference
+- Usage Patterns
+
 ## Installation
 
 ```bash

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

@@ -1,5 +1,12 @@
 # Pikku HTTP Wiring
 
+## Contents
+
+- API Reference
+- Data Flow
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 All three come from `#pikku/http` (the generated `.pikku/http/index.ts`), which
@@ -14,7 +21,7 @@ Function input/output types come from the function's own `input:`/`output:` zod
 
 Config cascading across groups: `basePath` concatenates down the chain, `tags` merge (union), `auth` child overrides parent.
 
-For the full option tables (every `wireHTTP` field, the `defineHTTPRoutes`/`wireHTTPRoutes` config shape), read `http-options.md`.
+For the full option tables (every `wireHTTP` field, the `defineHTTPRoutes`/`wireHTTPRoutes` config shape), read the HTTP options reference listed in `SKILL.md`.
 
 ### `addHTTPMiddleware(pattern, middlewares)`
 
@@ -23,7 +30,7 @@ addHTTPMiddleware('*', [authBearer()]) // All routes
 addHTTPMiddleware('/api/*', [rateLimit()]) // Pattern match
 ```
 
-> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-auth`), or app-wide via `addGlobalPermission`. Tags/patterns are for _middleware_ only now.
+> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-permissions`), or app-wide via `addGlobalPermission`. Tags/patterns are for _middleware_ only now.
 
 ## Data Flow
 
@@ -86,7 +93,7 @@ wireHTTP({ method: 'get', route: '/books', func: listBooks, auth: false })
 wireHTTP({ method: 'delete', route: '/books/:bookId', func: deleteBook })
 ```
 
-Authorization is not a wiring concern — declare it on the function via `permissions` (see `pikku-auth`), or app-wide via `addGlobalPermission`.
+Authorization is not a wiring concern — declare it on the function via `permissions` (see `pikku-permissions`), or app-wide via `addGlobalPermission`.
 
 ### Middleware
 

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

@@ -1,5 +1,13 @@
 # Pikku MCP Wiring
 
+## Contents
+
+- The shape of MCP in Pikku
+- API Reference
+- Reaching the server
+- Authentication
+- Red flags
+
 ## The shape of MCP in Pikku
 
 MCP has three surfaces, and Pikku wires them differently:

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

@@ -1,5 +1,11 @@
 # Pikku Queue Wiring
 
+## Contents
+
+- API Reference
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 ### `wireQueueWorker(config)`

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

@@ -1,5 +1,17 @@
 # Pikku Realtime
 
+## Contents
+
+- 1. Declare your topics
+- 2. Enable the server side
+- 3. Generate the typed client
+- 4. Publish events from a function
+- 5. Wire it up — share fetch with PikkuRPC
+- 6. Subscribe from React
+- Other SSE / WebSocket routes
+- When to pick which transport
+- What NOT to do
+
 ## 1. Declare your topics
 
 In your project's types file (e.g. `types/eventhub-topics.d.ts`):
@@ -95,7 +107,7 @@ export class PikkuRealtime {
     handler: (data: EventHubTopics[K]) => void
   ): { close: () => void }
 
-  // generic escape hatches — see realtime-other-routes.md
+  // generic escape hatches — see "Other SSE / WebSocket routes" below
   subscribeToSSE<T>(
     path: string,
     handler: (data: T) => void
@@ -236,9 +248,27 @@ function TodoList() {
 
 ## Other SSE / WebSocket routes
 
-The same client also subscribes to generic `sse: true` routes and raw `wireChannel`
-sockets (`subscribeToSSE`, `connectToChannel`). See
-[realtime-other-routes.md](realtime-other-routes.md).
+The same client also handles generic SSE + channel routes (not just
+`/events` topics). Use the path; the base URL is inherited from `PikkuFetch`.
+
+```ts
+// Any `sse: true` HTTP route
+const sub = realtime.subscribeToSSE<{ progress: number }>(
+  `/workflow-run/${runId}/stream`,
+  (event) => setProgress(event.progress)
+)
+// later: sub.close()
+
+// Any wireChannel — open a raw socket, wrap in PikkuWebSocket for typed I/O
+const ws = realtime.connectToChannel('/ws/kanban')
+const typed = new PikkuWebSocket<'kanban-live'>(ws)
+typed.getRoute('command').subscribe('message', (data) => {
+  /* ... */
+})
+```
+
+Discover what's available with `pikku meta clients --json` — `channels` and any HTTP
+`sse: true` routes are listed there.
 
 ## When to pick which transport
 

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

@@ -1,5 +1,11 @@
 # Pikku RPC Wiring
 
+## Contents
+
+- API Reference
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 ### RPC Methods (on `wire.rpc`)

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

@@ -1,5 +1,11 @@
 # Pikku Scheduled Tasks
 
+## Contents
+
+- API Reference
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 ### `wireScheduler(config)`

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

@@ -1,5 +1,13 @@
 # Pikku Trigger Wiring
 
+## Contents
+
+- API Reference
+- Starting triggers
+- Webhook sources
+- Usage Patterns
+- Complete Example
+
 ## API Reference
 
 All three come from `#pikku`. A trigger is deliberately split in two: the

package/skills/pikku-workflow/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: pikku-workflow
 description: >-
-  Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku.
-  Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
-  TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows,
-  multi-step processes, durable execution, suspend/resume, or DAG orchestration. DO NOT TRIGGER
-  when: user asks about simple background jobs (use pikku-wiring) or scheduled tasks (use
-  pikku-wiring).
+  Use when building multi-step, durable workflows with Pikku — pikkuWorkflowFunc,
+  pikkuWorkflowGraph, workflow.do / sleep / suspend / approval, retries, compensate, sub-workflows,
+  and starting or resuming runs. Includes deciding whether something should be a workflow at all.
+  TRIGGER when: code uses pikkuWorkflowFunc or pikkuWorkflowGraph, or the user asks about
+  workflows, multi-step processes, durable execution, suspend/resume, approval gates, sagas or DAG
+  orchestration. DO NOT TRIGGER when: the user wants a single background job (use the queue
+  reference in pikku-wiring) or a cron task (use the scheduler reference in pikku-wiring), or is
+  converting an n8n export (use pikku-n8n-import).
 installGroups: [core]
 ---
 

package/skills/pikku-auth/references/permissions.md

@@ -1,261 +0,0 @@
-# Pikku Permissions
-
-## ⛔ FIRST: is the caller a machine with a token? ⛔
-
-**Then this is NOT a permissions problem.** Resolve the token in `addHTTPMiddleware('*')` middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with `scopes`. A `permissions` check that verifies a bearer token and returns `true` is authentication wearing an authorization hat — and it leaves the function sessionless, so every body still has to work out who called it. See `references/machine-auth.md`. The only exception is a bootstrap endpoint whose caller has no identity yet (a shared-secret registration, a login): that one is sessionless and declares its gate here.
-
-## The Rule
-
-**ALWAYS put authorization checks in the `permissions` field of `pikkuFunc` or `pikkuSessionlessFunc` — NEVER inside the `func` body.**
-
-This includes: org access checks, repo access checks, role checks, resource ownership, and any other authorization logic. The `permissions` field runs before `func` and is visible to the inspector, so the gate is declared rather than buried — which is what lets `pikku info permissions` and an audit see it at all. Alongside it sits `scopes` (see below) for grant-based gating; between them they are where Pikku enforces authorization. The one sanctioned exception is `permissionsInBody`, covered at the end.
-
-```typescript
-// CORRECT
-export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-  },
-  permissions: {
-    owner: isBookOwner, // ← authorization here
-  },
-})
-
-// WRONG — permission check inside func body
-export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }, { session }) => {
-    if (!session) throw new UnauthorizedError() // ← never do this
-    await db.deleteBook(bookId)
-  },
-})
-```
-
-
-## Permission Factories
-
-### `pikkuAuth(fn)` — Session-Only Checks
-
-Use for checks that read the session but need no request data — and that assert
-something **beyond** merely having a session (a flag, a tier, a claim).
-
-```typescript
-import { pikkuAuth } from '#pikku/auth'
-
-// Good: a real gate on the session's contents, not just its existence.
-export const isVerified = pikkuAuth(
-  async (_services, session) => !!session?.emailVerified
-)
-```
-
-**Do NOT write an "is signed in" permission.** A checker that just returns
-`!!session` is not authorization — it re-checks authentication, which the
-function already enforces. A function that needs a signed-in user sets
-`auth: true` (the default for `pikkuFunc`); it does not also carry a
-`permissions: { signedIn }`.
-
-```typescript
-// WRONG — redundant with auth: true; adds a permission that gates nothing.
-export const isSignedIn = pikkuAuth(async (_s, session) => !!session)
-pikkuFunc({ auth: true, permissions: { signedIn: isSignedIn } /* ... */ })
-
-// RIGHT — auth: true already requires the session; permissions are for capability.
-pikkuFunc({ auth: true /* ... */ })
-```
-
-A permission answers "_may this user do this?_" (role, ownership, tier) — never
-"_is there a session?_".
-
-### `pikkuPermission(fn)` — Data-Aware Checks
-
-Use when authorization depends on the actual request data (e.g., resource ownership).
-
-```typescript
-import { pikkuPermission } from '#pikku/auth'
-
-export const isBookOwner = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    const book = await db.getBook(bookId)
-    return book?.authorId === session?.userId
-  }
-)
-
-export const hasBookAccess = pikkuPermission(
-  async ({ db }, { bookId }, { session }) => {
-    return await db.hasAccess(session?.userId, bookId)
-  }
-)
-```
-
-## OR / AND Logic
-
-```typescript
-permissions: {
-  verified: isVerified,                    // OR: verified users can access
-  owner: isBookOwner,                      // OR: owners can access
-  reviewer: [isVerified, hasBookAccess],   // AND: both must pass
-}
-// Logic: verified OR owner OR (isVerified AND hasBookAccess)
-```
-
-Groups are OR'd. Entries within a group array are AND'd.
-
-## Where to Apply Permissions
-
-### Per-Function (preferred)
-
-```typescript
-export const deleteBook = pikkuFunc({
-  func: async ({ db }, { bookId }) => {
-    await db.deleteBook(bookId)
-  },
-  permissions: {
-    verified: isVerified,
-    owner: isBookOwner,
-  },
-})
-```
-
-### Global (`addGlobalPermission`) — App-Wide AND Gate
-
-A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever _narrow_ access — it never grants access a function's own `permissions` would deny.
-
-```typescript
-import { addGlobalPermission } from '#pikku/auth'
-
-addGlobalPermission([isEmployee]) // every function now also requires an employee session
-```
-
-Multiple `addGlobalPermission` calls accumulate and are AND'd together.
-
-> Wire-, tag-, and HTTP-route-level permissions (`addHTTPPermission`, `addTagPermission`, and a `permissions` field on HTTP/channel/MCP wirings) were **removed in #972**. Permissions now live only on the function definition, plus the optional global gate. Tags are organizational only — use tag/HTTP _middleware_ (`addTagMiddleware`, `addHTTPMiddleware`) for cross-cutting request handling, not authorization.
-
-## Scopes — the AND Gate Above Permissions
-
-Scopes answer "what was this session granted?" before permissions ask "may this
-user do this to this resource?". They are AND-ed: every scope listed must be
-held. Because they are checked first and fail closed, a scope can only ever
-_narrow_ access — it never grants what `permissions` would deny.
-
-Declare the scope tree once with `defineScope`. The body is a no-op that
-tree-shakes away; the CLI reads the call by AST and generates a `ScopeId` union,
-so a function naming an undeclared scope fails the build rather than silently
-gating on nothing.
-
-```typescript
-// src/scopes.ts
-import { defineScope } from '#pikku/scopes'
-
-defineScope({
-  admin: {
-    displayName: 'Administration',
-    description: 'Administrative access',
-    scopes: {
-      invoices: {
-        description: 'Invoice management',
-        scopes: {
-          create: { description: 'Create invoices' },
-          void: { description: 'Void invoices' },
-        },
-      },
-    },
-  },
-  billing: {},
-})
-```
-
-Every node is grantable, keyed by segment: the above yields `admin`,
-`admin:invoices`, `admin:invoices:create`, `admin:invoices:void` and `billing`.
-Scopes may be declared across more than one file — the declarations merge.
-
-```typescript
-export const voidInvoice = pikkuFunc({
-  scopes: ['admin:invoices:void'],
-  permissions: { owner: isInvoiceOwner },
-  func: async ({ db }, { invoiceId }) => { ... },
-})
-```
-
-A grant satisfies a required scope if it is the scope itself, an ancestor of it,
-or a wildcard at any level — so a session holding `admin` satisfies
-`admin:invoices:void`, and `admin:*` does too. A missing scope throws
-`MissingScopeError` naming the first one that failed.
-
-`scopes` requires a session and so is unavailable on `pikkuSessionlessFunc`:
-scopes fail closed, an anonymous caller holds none, and a sessionless function
-with scopes would reject every caller it exists to serve. Gate those with
-`permissions`, which receive the optional session and may pass anonymous.
-
-## The Three Gates
-
-Authorization is three independent gates, evaluated in this order, all of which must pass:
-
-1. **Scopes** (`scopes`) — AND'd, checked before input validation. Fails closed.
-2. **Global permissions** (`addGlobalPermission`) — AND'd together. A broad baseline that can only narrow access.
-3. **The function's own `permissions`** — OR'd groups (OR-of-ANDs), as above.
-
-The gates are independent: a broad global (e.g. `isEmployee`) can **never** satisfy an admin-only function's own requirement. Each function still enforces its own `scopes` and `permissions` in full.
-
-## The Sanctioned Exception: `permissionsInBody`
-
-A few checks genuinely cannot be expressed as a permission — verifying a webhook
-signature, a signed token, or an invite code, where the "identity" arrives in the
-payload and there is no session to check. For those, declare
-`permissionsInBody: true` on the function and keep the check in the body.
-
-```typescript
-export const handleStripeWebhook = pikkuSessionlessFunc({
-  permissionsInBody: true,
-  auth: false,
-  func: async ({ stripe }, data, { http }) => {
-    stripe.webhooks.constructEvent(
-      data.raw,
-      http.request.header('stripe-signature'),
-      secret
-    )
-    // ...
-  },
-})
-```
-
-This is a last resort, and it is purely declarative — it grants nothing and
-enforces nothing. Its only job is to tell the auditor that this function's
-apparent openness is deliberate, so asserting it falsely disables the very check
-that would have caught the mistake. It requires `"allow": { "permissionsInBody": true }`
-in `pikku.config.json`, which keeps the decision visible at the project level.
-Prefer `permissions` whenever the check can be expressed as one — they are
-declared, inspectable, and reusable.
-
-## Complete Example
-
-```typescript
-// src/permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/auth'
-
-export const isVerified = pikkuAuth(
-  async (_services, session) => !!session?.emailVerified
-)
-
-export const isOrgMember = pikkuPermission(
-  async ({ db }, { orgId }, { session }) => {
-    return await db.isMember(session?.userId, orgId)
-  }
-)
-
-// src/functions/org.function.ts
-export const deleteOrg = pikkuFunc({
-  func: async ({ db }, { orgId }) => {
-    await db.deleteOrg(orgId)
-  },
-  permissions: {
-    verified: isVerified,
-    owner: [isVerified, isOrgMember],
-  },
-})
-```
-
-## After Changes
-
-```bash
-pikku all              # regenerate if wirings changed
-pikku all --tsc        # regenerate, then verify permission checker types (fails on type errors)
-```

package/skills/pikku-mantine/SKILL.md

@@ -1,80 +0,0 @@
----
-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/realtime-other-routes.md

@@ -1,23 +0,0 @@
-# Subscribing to other SSE / WebSocket routes
-
-The same `PikkuRealtime` client also handles generic SSE + channel routes (not just
-`/events` topics). Use the path; the base URL is inherited from `PikkuFetch`.
-
-```ts
-// Any `sse: true` HTTP route
-const sub = realtime.subscribeToSSE<{ progress: number }>(
-  `/workflow-run/${runId}/stream`,
-  (event) => setProgress(event.progress)
-)
-// later: sub.close()
-
-// Any wireChannel — open a raw socket, wrap in PikkuWebSocket for typed I/O
-const ws = realtime.connectToChannel('/ws/kanban')
-const typed = new PikkuWebSocket<'kanban-live'>(ws)
-typed.getRoute('command').subscribe('message', (data) => {
-  /* ... */
-})
-```
-
-Discover what's available with `pikku meta clients --json` — `channels` and any HTTP
-`sse: true` routes are listed there.