@pikku/skills 0.12.21 → 0.12.25

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

@@ -0,0 +1,114 @@
+# Pikku Project Metadata
+
+`pikku meta` is the machine-readable view of the project and the write path to it.
+`pikku info` is the same ground as human-readable tables. Prefer `meta` when you are
+going to act on the output; prefer `info` when a person is going to read it.
+
+
+## Reading
+
+| Command                         | What it answers                                                                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `pikku meta context`            | Everything a planner needs in one call — functions, wires, middleware, permissions, workflows, capabilities, layout. Start here. |
+| `pikku meta functions get <id>` | One function's input/output schema names, source file, tags, expose/readonly                                                     |
+| `pikku meta schemas get <name>` | One generated JSON schema                                                                                                        |
+| `pikku meta workflows get <id>` | One workflow's steps                                                                                                             |
+| `pikku meta permissions list`   | What permissions exist and where they are defined                                                                                |
+| `pikku meta middleware list`    | What middleware exists                                                                                                           |
+| `pikku meta wires list`         | Wires by transport (http, channel, scheduler, queue, trigger)                                                                    |
+| `pikku meta clients`            | Exposed RPCs/workflows/channels with their type names — what a frontend can call                                                 |
+
+`list` is the default for each group, so `pikku meta functions` and `pikku meta functions list`
+are the same call.
+
+A function's input/output shape comes from here. Do not infer it by reading the
+function body, and do not cast a call site to make it compile — the schema is the type.
+
+## Changing
+
+`pikku meta apply` applies a batch of edits to your own source. Pass JSON as a file
+or on stdin:
+
+```bash
+pikku meta apply ops.json
+```
+
+```json
+{
+  "operations": [
+    {
+      "kind": "functionConfig",
+      "sourceFile": "src/functions/todos.functions.ts",
+      "exportedName": "listTodos",
+      "changes": { "title": "List Todos", "tags": ["todos", "read"] }
+    },
+
+    {
+      "kind": "functionConfig",
+      "sourceFile": "src/functions/todos.functions.ts",
+      "exportedName": "listTodos",
+      "changes": {
+        "permissions": {
+          "functionLevel": {
+            "name": "isTodoOwner",
+            "from": "../permissions.js"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+Three kinds: `functionConfig`, `agentConfig`, `functionBody`. Every operation names
+a `sourceFile` and the `exportedName` declared in it.
+
+`functionConfig` changes: `title`, `description`, `summary`, `tags`, `errors`,
+`expose`, `remote`, `mcp`, `readonly`, `approvalRequired`, `permissions`.
+`agentConfig` changes: `name`, `description`, `instructions`, `role`, `personality`,
+`goal`, `model`, `maxSteps`, `temperature`, `toolChoice`, `tools`, `tags`.
+
+`null` removes a property. Edits are spliced into the original text, so formatting,
+comments and JSDoc survive.
+
+`permissions` and `tools` are written as identifiers rather than literals, so each
+one carries the module it comes from (`{"name": "isTodoOwner", "from": "../permissions.js"}`)
+and the missing import is added for you — widening an existing import from that
+module rather than adding a second one.
+
+### Why batch
+
+The whole batch either lands or it does not: every operation is resolved before
+anything is written, so a failure leaves every file untouched and names the
+operation that caused it. Batching is also what makes one codegen pass correct —
+**run `pikku all` once after the batch**, not once per property. The response tells
+you whether it is needed:
+
+```json
+{
+  "schemaVersion": "meta-apply.v1",
+  "applied": 2,
+  "files": ["src/functions/todos.functions.ts"],
+  "generatedMetaIsStale": true
+}
+```
+
+## Human-readable tables (`pikku info`)
+
+Four subcommands only — `functions`, `tags`, `middleware`, `permissions`. Routes,
+channels, schedulers and queues are not subcommands; they are the _transport_ column
+of `info functions --verbose`.
+
+```bash
+yarn pikku info functions --verbose --silent
+yarn pikku info tags --silent
+yarn pikku info middleware --verbose --silent
+yarn pikku info permissions --verbose --silent
+```
+
+`--silent` suppresses the banner and inspector diagnostics. It works, but it is not
+declared as an option, so every run also prints `Warning: Unknown option: --silent
+(ignored)` — the warning is wrong. Ignore that one line.
+
+`--limit N` caps rows (default 50); the footer says how many were withheld.
+On `tags`, `--verbose` swaps counts for names; elsewhere it adds columns.

package/skills/{pikku-versioning/SKILL.md → pikku-meta/references/versioning.md}

@@ -1,31 +1,5 @@
----
-name: pikku-versioning
-description: >-
-  Use when versioning Pikku function contracts, detecting breaking changes, or managing API
-  backward compatibility. Covers the version property, versions.pikku.json manifest, contract
-  hashing, and CI integration. Also covers `pikku semver`, which derives a release's semver by
-  diffing this build's surface against a deployed one and writes .pikku/changes.gen.json.
-  TRIGGER when: code uses version: on a pikkuFunc, user asks about
-  API versioning, breaking changes, contract hashes, backward compatibility, what semver a
-  release should get, comparing against production/staging, or "pikku versions" / "pikku semver"
-  CLI commands. DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config)
-  or general function definitions (use pikku-concepts), or about updating dependency versions
-  (use pikku-deps).
----
-
 # Pikku Function Versioning
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-Track and protect function contracts across releases. Pikku hashes each function's input/output schema into a manifest so you can detect breaking changes before they ship.
 
 ## Before You Start
 

package/skills/pikku-middleware/SKILL.md

@@ -6,8 +6,8 @@ description: >-
   understanding middleware execution order and priority. TRIGGER when: user wants middleware on
   some or all routes, machine-to-machine auth, tag-scoped cross-cutting concerns, global
   interceptors, or middleware priority/order questions. DO NOT TRIGGER when: user asks about
-  permissions/authorization checks (use pikku-permissions), auth strategies like
-  authBearer/authCookie (use pikku-security), or deployment.
+  permissions, sessions or auth strategies like authBearer/authCookie (use
+  pikku-auth), or deployment.
 installGroups: [core]
 ---
 
@@ -23,7 +23,7 @@ installGroups: [core]
 ## The `pikkuMiddleware` Factory
 
 ```typescript
-import { pikkuMiddleware } from '#pikku/function'
+import { pikkuMiddleware } from '#pikku/middleware'
 
 // Simple: just a function
 const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
@@ -139,7 +139,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '#pikku/function'
+import { addTagMiddleware } from '#pikku/middleware'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -223,7 +223,7 @@ export const reportSomething = pikkuFunc({
 })
 ```
 
-An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-permissions`).
+An unresolved token leaves the session unset and the function throws `MissingSessionError` — 401, for free. Declare the scope tree once with `defineScope` (see `pikku-auth`).
 
 ### It MUST be `addHTTPMiddleware`, never `addTagMiddleware`
 
@@ -255,13 +255,13 @@ Unlike tag middleware over `/rpc`, this works: `runScheduledTask` builds its wir
 
 ### The one sessionless exception: bootstrap
 
-An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-permissions`).
+An endpoint that runs BEFORE the caller has an identity — registering a new host with a shared bootstrap key, a login, a device-code request — has no session to set. That one stays `pikkuSessionlessFunc` and declares its gate in `permissions` (see `pikku-auth`).
 
 ## Service-to-Service Bearer Auth (gate-only pattern)
 
 Use this when the callee needs to know only THAT the caller is trusted, not WHICH caller it is. If it needs to know which, use the session pattern above.
 
-A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-permissions`), never inside `func`.
+A server that exposes RPCs only to a trusted caller (e.g. an API calling a machine-agent). Auth lives in a tag middleware — NOT in the function body. Authorization/permission checks belong in the `permissions` field (see `pikku-auth`), never inside `func`.
 
 **On the server (the service being called):** tag the function, register a `pikkuMiddleware` that reads the `Authorization` header on that tag.
 
@@ -277,7 +277,7 @@ export const getToken = () => _token
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '#pikku/function'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku/middleware'
 import { UnauthorizedError } from '#pikku/error'
 import { getToken } from '../lib/host-token.js'
 

package/skills/pikku-n8n-import/SKILL.md

@@ -3,7 +3,6 @@ name: pikku-n8n-import
 description: 'Use to import an n8n workflow JSON export into a runnable Pikku workflow. Triggers when the user says "import this n8n workflow", "convert this n8n export to pikku", points at an n8n `.json` export or a directory of them, or picks up after `pikku import n8n` left throwing stub functions (`STUB — generated from n8n …`, `— implement me`) or a `<workflow>.integrations.json` manifest. Owns the whole flow: run the importer, triage what it could not map, fill each stub, report any missing `@pikku/addon-*` integrations, and verify the result compiles and runs with no surviving stubs. DO NOT TRIGGER for hand-written addon wiring unrelated to an n8n import (use pikku-addon), or for authoring workflows from scratch (use pikku-workflow).'
 metadata:
   version: 1.0.0
-installGroups: [fabric]
 ---
 
 # n8n → Pikku Import

package/skills/pikku-react/SKILL.md

@@ -1,313 +1,65 @@
 ---
 name: pikku-react
-description: 'Set up @pikku/react in a React app: PikkuProvider context, createPikku factory, and the usePikkuRPC / usePikkuFetch hooks for direct (non-React-Query) calls. TRIGGER when: the user is bootstrapping a React frontend that talks to a Pikku backend, asks how to wire `PikkuProvider`, or needs to make one-off RPC calls outside of useQuery/useMutation. TRIGGER when: user asks about the dev actor switcher, "sign in as" / quick-login UI, useDevActors, VITE_DEV_ACTORS, or the app-missing-actor-quick-login validate finding. DO NOT TRIGGER when: the user is asking about useQuery/useMutation hooks (use pikku-react-query) or about workflows (use pikku-workflows-client).'
+description: >-
+  Use when a React frontend talks to a Pikku backend — PikkuProvider and createPikku at the app
+  root, the generated React Query hooks (usePikkuQuery, usePikkuMutation, usePikkuInfiniteQuery),
+  direct usePikkuRPC / usePikkuFetch calls, realtime subscriptions, agent and workflow hooks, and
+  the dev actor switcher. TRIGGER when: writing a React component that fetches or mutates backend
+  data, wiring PikkuProvider, paginating, running or tracking a workflow from the client, or
+  asking about useDevActors / VITE_DEV_ACTORS / quick login. DO NOT TRIGGER when: working on the
+  backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), or writing
+  user-facing copy (use pikku-i18n).
 installGroups: [client]
 ---
 
 # Pikku React
 
-## Agent Operating Procedure
+The hook names and their argument types come from your generated `api.gen.ts` —
+read it for what this app actually exposes. This skill is the part it cannot
+tell you: which hook a given need calls for, and where the generated client
+stops.
 
-Use this skill as an execution checklist, not reference material.
+## Pick the reference
 
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
-4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+| You are… | Read |
+| --- | --- |
+| Wiring the app root, resolving the server URL, authenticating, or subscribing to realtime | `references/client.md` |
+| Fetching, mutating or paginating data | `references/react-query.md` |
+| Starting a workflow and showing its progress | `references/workflows.md` |
 
-`@pikku/react` is the smallest possible binding: a Context provider plus
-two hooks. It does **not** depend on React Query — that's a separate
-opt-in via the generated `api.gen.ts`. Use this skill when setting up the
-provider or making direct RPC calls.
+## Reach for what
 
-## What ships
+| Need | Use |
+| --- | --- |
+| Render data, dedupe and cache | `usePikkuQuery` |
+| Trigger a write and wait for the result | `usePikkuMutation` |
+| Paginate | `usePikkuInfiniteQuery` |
+| One-off call from an event handler | `usePikkuRPC()` |
+| Hit a REST endpoint rather than an RPC | `usePikkuFetch()` |
+| Talk to one named AI agent | `usePikkuAgent(name)` → `.run` / `.stream` / `.approve` |
+| Run one named workflow | `usePikkuWorkflow(name)` → `.start` / `.run` / `.status` |
+| A workflow long enough to need progress UI | `references/workflows.md` |
+| Subscribe to events, SSE or a channel | `usePikkuRealtime()` |
 
-```tsx
-import {
-  PikkuProvider,
-  createPikku,
-  usePikkuFetch,
-  usePikkuRPC,
-  usePikkuRealtime,
-  usePikkuAgent,
-  usePikkuWorkflow,
-  asI18n,
-} from '@pikku/react'
-```
-
-`usePikkuRealtime` is only valid when you wired a `PikkuRealtime` class via
-`createPikku` — see the setup section. `usePikkuAgent` and `usePikkuWorkflow`
-are thin bindings over the RPC client that pin one agent/workflow name, so a
-component never repeats it. `asI18n` is the i18n brand (see **pikku-i18n**).
-
-## Resolving the server URL
-
-Every client (`createPikku`, realtime, the auth client) resolves its base
-through one shared helper in `src/lib/env.ts`. Write this once:
-
-```ts
-// Endpoints come from env, never hardcoded.
-export function apiUrl(): string {
-  // SSR: the client hooks only run in the browser, so a placeholder is fine.
-  if (import.meta.env.SSR) {
-    return import.meta.env.VITE_API_URL ?? '/__api'
-  }
-  return import.meta.env.VITE_API_URL ?? `${window.location.origin}/api`
-}
-```
-
-**Never fall back to `http://localhost:3000`.** `import.meta.env.VITE_API_URL`
-is substituted by Vite at _build_ time, so any deploy that supplies the URL as
-a _runtime_ env var or platform binding leaves it `undefined` in the shipped
-bundle — the fallback is then the only branch that ever runs in the browser. A
-localhost fallback means every request from a deployed app goes to the user's
-own machine. `origin + '/api'` is same-origin, needs no build-time knowledge of
-the domain, and is correct wherever the app is served from.
-
-For local dev, set `VITE_API_URL`, or proxy `/api` → your backend in
-`vite.config.ts` under `server.proxy`. One `/api` entry also covers
-`/api/auth/*`; only add more entries for root-level routes outside `/api`.
-
-## Setup at the app root
-
-```tsx
-import { createPikku, PikkuProvider } from '@pikku/react'
-import { PikkuFetch } from './pikku/pikku-fetch.gen'
-import { PikkuRPC } from './pikku/pikku-rpc.gen'
-import { apiUrl } from './lib/env'
-
-const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: apiUrl(),
-})
-
-createRoot(document.getElementById('root')!).render(
-  <PikkuProvider pikku={pikku}>
-    <App />
-  </PikkuProvider>
-)
-```
-
-If the project also exposes realtime events (see **pikku-realtime**), pass
-the `PikkuRealtime` class as the third argument and the instance gets a
-`realtime` field too:
-
-```tsx
-import { PikkuRealtime } from './pikku/realtime.gen'
-
-const pikku = createPikku(PikkuFetch, PikkuRPC, PikkuRealtime, {
-  serverUrl: apiUrl(),
-})
-// pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch
-// (server URL + auth configured once).
-```
-
-The generated classes come from your `pikku.config.json`:
-
-| config field                 | generated file                                        |
-| ---------------------------- | ----------------------------------------------------- |
-| `clientFiles.fetchFile`      | typed HTTP client (`PikkuFetch` class)                |
-| `clientFiles.rpcWiringsFile` | RPC client (`PikkuRPC` class) calling all exposed fns |
-| `clientFiles.realtimeFile`   | `PikkuRealtime` (websocket events + SSE + channels)   |
-
-If a file isn't being generated, that field is missing from the config —
-add it and re-run `pikku all`.
-
-`createPikku(...)` accepts the same `CorePikkuFetchOptions` as `PikkuFetch`
-plus `serverUrl`. Auth headers, request interceptors, etc. are configured
-on the fetch instance — RPC and realtime inherit them automatically.
-
-## Calling an RPC directly (no React Query)
-
-Inside a component:
-
-```tsx
-import { usePikkuRPC } from '@pikku/react'
-
-function Logout() {
-  const rpc = usePikkuRPC()
-  return <button onClick={() => rpc.invoke('logoutUser', {})}>Sign out</button>
-}
-```
-
-`rpc.invoke(name, data)` is typed against `FlattenedRPCMap` — `name` must
-be an exposed function id, `data` matches the input schema, return value
-matches the output schema.
-
-You also have `rpc.<funcName>(data)` if the generated RPC client builds
-direct methods (project-dependent).
-
-## Calling fetch directly
-
-```tsx
-const fetch = usePikkuFetch()
-const data = await fetch.get('/some-rest-route', { searchParams: {...} })
-```
-
-Use this only when the function is wired via HTTP (REST shape) and you
-need a path-style call. For RPC calls, `usePikkuRPC()` is cleaner.
-
-## Realtime subscriptions
-
-If you wired a `PikkuRealtime` class into `createPikku`, use
-`usePikkuRealtime()` to grab the shared instance:
-
-```tsx
-import { usePikkuRealtime } from '@pikku/react'
-import type { PikkuRealtime } from './pikku/realtime.gen'
-
-function TodoList() {
-  const realtime = usePikkuRealtime<PikkuRealtime>()
-  useEffect(() => {
-    return realtime.subscribe('todo-created', ({ todo }) => {
-      /* ... */
-    })
-  }, [realtime])
-  // ...
-}
-```
-
-The hook throws if no `PikkuRealtime` was wired — that's how you know to
-add it to `createPikku(...)`. Full event-hub setup, publishing, and SSE
-helpers live in **pikku-realtime**.
-
-## When to reach for what
-
-| Need                                | Use                                                |
-| ----------------------------------- | -------------------------------------------------- |
-| Render data, dedupe + cache         | **usePikkuQuery** (react-query)                    |
-| Trigger a write, wait for result    | **usePikkuMutation** (react-query)                 |
-| Paginate                            | **usePikkuInfiniteQuery** (react-query)            |
-| One-off call from an event handler  | `usePikkuRPC()` direct                             |
-| Hit a REST endpoint (not RPC)       | `usePikkuFetch()`                                  |
-| Run one named workflow              | `usePikkuWorkflow('name')` → `.start/.run/.status` |
-| Talk to one named AI agent          | `usePikkuAgent('name')` → `.run/.stream/.approve`  |
-| Longer-running workflow UX          | **pikku-workflows-client**                         |
-| Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-realtime**)      |
-
-The first three live in your generated `api.gen.ts` (see the
-**pikku-react-query** skill). This skill covers the rest.
-
-`usePikkuAgent` and `usePikkuWorkflow` bind the name once and hand back the
-call methods with it already applied:
-
-```tsx
-const agent = usePikkuAgent('todo-agent')
-const { text } = await agent.run({ message, threadId })
-
-const workflow = usePikkuWorkflow('onboardUser')
-const { runId } = await workflow.start({ email })
-const state = await workflow.status(runId)
-```
-
-## Authentication
-
-Auth is handled at the `PikkuFetch` layer, and `createPikku`'s options object
-_is_ `CorePikkuFetchOptions` plus `serverUrl` — flat, not nested under a
-`fetchOptions` key:
-
-```tsx
-const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: apiUrl(),
-  credentials: 'include', // cookie sessions
-  authHeaders: { jwt: token }, // or { apiKey }
-  transformDate: true,
-})
-```
-
-There is no request-interceptor hook. For a token that changes after startup,
-call the setter on the shared instance — RPC and realtime pick it up because
-they hold the same fetch:
-
-```tsx
-pikku.fetch.setAuthorizationJWT(token) // null clears it
-pikku.fetch.setAPIKey(key)
-pikku.fetch.setHeader('x-tenant', tenantId)
-```
-
-`authHeaders.jwt` becomes `Authorization: Bearer …` and `authHeaders.apiKey`
-becomes `X-API-KEY`; setting a JWT takes precedence over an API key.
-
-### Dev actor sign-in (`useDevActors`)
-
-The dev-only "Sign in as …" control: one click signs in as a declared scenario
-persona with no password, so the app can be reviewed as each kind of user.
-`pikku fabric validate` **requires** any frontend with a login screen to ship one
-(`app-missing-actor-quick-login-<app>`) — without it a reviewer is locked out of
-their own sandbox.
-
-```tsx
-import { useDevActors } from '@pikku/react'
-
-const { actors, signInAs, pendingEmail, isPending, error } = useDevActors({
-  // Gate both reads on the bundler's dev flag so no credential can reach a
-  // production bundle. The sandbox dev server bakes them from your personas.
-  actors: import.meta.env.DEV ? import.meta.env.VITE_DEV_ACTORS : undefined,
-  secrets: import.meta.env.DEV
-    ? import.meta.env.VITE_DEV_ACTOR_SECRETS
-    : undefined,
-  apiUrl: apiUrl(),
-  onSignedIn: () => navigate({ to: '/' }),
-})
-```
-
-- **It is UI-free**, so render it however you like. For the default rendering use
-  `<DevActorSwitcher />` from `@pikku/mantine/dev` — a separate entry point from
-  `@pikku/mantine/core`, whose contract is "drop-in alias for `@mantine/core`"
-  and so must not export components Mantine has no counterpart for.
-- **`secrets` is `{ address: credential }`, not one shared value** — a
-  credential opens the one persona it was minted for (see
-  **pikku-better-auth**). `actors` is empty unless the host supplied both a list
-  and the credentials for it, and an actor with no credential is not offered, so
-  a production build renders nothing without you testing for it.
-- **It takes `onSignedIn` rather than a router**, and takes the env values rather
-  than reading them, because how env is spelled is a bundler fact
-  (`import.meta.env.VITE_*` vs `process.env.NEXT_PUBLIC_*`).
-- The underlying `signInAsActor()` and `parseDevActors()` are exported too, for a
-  non-React caller. The endpoint only accepts rows flagged `actor: true`, so it
-  can never impersonate a real user — see **pikku-better-auth**.
-
-Do not hand-write the `devActors()` / `signInAsActor()` pair per app; that
-copy-paste, including the `import.meta.env.DEV` gate, is exactly what this
-replaced.
-
-### Linking from a Mantine element: `renderRoot`, not `component`
-
-Handing TanStack's `Link` to a Mantine element as `component={Link}` compiles,
-renders, and navigates — and silently unties the type. Mantine's polymorphic
-`component` prop widens the router generic to `AnyRouter`, so `to` and
-`params` stop being checked against your actual routes. Renaming a route then
-breaks the running app instead of the build, which is the one thing the typed
-router exists to prevent.
-
-Wrap the typed `Link` once and reach it through `renderRoot`, which passes the
-props through without re-typing the element:
-
-```tsx
-// components/links.tsx — one wrapper the whole app links through
-import { Link } from '@tanstack/react-router'
-
-export const AssessmentLink = (props: { assessmentId: string; children: React.ReactNode }) => (
-  <Link to="/assessments/$assessmentId" params={{ assessmentId: props.assessmentId }}>
-    {props.children}
-  </Link>
-)
-```
-
-```tsx
-<Button renderRoot={(p) => <AssessmentLink assessmentId={id} {...p} />}>
-  Open
-</Button>
-```
-
-The wrapper is where `to` and `params` are checked, and it is checked once.
+A workflow that finishes in a moment can be awaited; one that does not needs
+start-plus-observe, or the component holds a pending state with nothing to show.
 
 ## What NOT to do
 
-- Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`
-  goes once at the app root, the instance flows through Context.
-- Don't call `usePikkuRPC()` outside a `<PikkuProvider>` — it throws.
-- Don't write a custom RPC client. The generated one already covers every
-  exposed function with full types.
-- Don't hardcode user-facing strings. Every display string goes through an
-  i18n token — see **pikku-i18n** for the setup (it's English-only by default).
+- **Do not write a client.** The generated one covers every exposed function
+  with full types; a hand-rolled RPC client or a hand-written
+  `useQuery({ queryKey, queryFn })` reimplements it worse.
+- **Do not instantiate `PikkuFetch`/`PikkuRPC` in a component.** `createPikku`
+  runs once at the app root and the instance flows through context — and
+  `usePikkuRPC()` outside `<PikkuProvider>` throws.
+- **Do not call the RPC client inside a `useEffect`.** The hooks handle
+  deduplication, caching and unmounting; a manual effect handles none of them.
+- **Do not construct a hook name at runtime.** Hook names are the RPC names known
+  at generation time, and a computed one is not type-checked.
+- **Do not poll a workflow with `setInterval`.** `useWorkflowStatus` with a
+  `refetchInterval` callback dedupes across components and stops on a terminal
+  state in one place.
+- **Do not reach for `as any` when a hook's types disagree with you.** The
+  mismatch is the backend's input/output schema; fix it there.
+- **Do not hardcode a user-facing string.** Every display string goes through an
+  i18n message — see `pikku-i18n`.