@pikku/skills 0.12.52 → 0.12.55

package/skills/pikku-n8n-import/references/addon-mapping.md

@@ -1,5 +1,11 @@
 # Integration stub → Pikku addon
 
+## Contents
+
+- Inputs
+- Per entry, in order
+- Never
+
 Translate n8n integration nodes (`gmailTool`, `slackTool`, `googleSheetsTool`, plain
 `gmail` / `slack` action nodes, etc.) that the importer left as throwing stubs into
 real `ref('<addonRpc>')` references pointing at functions in **installed**

package/skills/pikku-n8n-import/references/code-translation.md

@@ -1,5 +1,12 @@
 # n8n Code node → Pikku function
 
+## Contents
+
+- Process
+- Rubric
+- Example
+- Report
+
 Replace a Code-node stub's `throw new Error(...)` body with a faithful TypeScript
 reimplementation. The original JS is preserved verbatim in the JSDoc above the
 function. Keep the signature and JSDoc intact; only widen the Zod input/output if

package/skills/pikku-permissions/SKILL.md

@@ -1,14 +1,24 @@
 ---
 name: pikku-permissions
 description: >-
-  Use when deciding WHO may call a function — resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes, and where ownership belongs versus where it does not.
-  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, or about to write an `if` in a function body that decides whether the caller is allowed.
-  DO NOT TRIGGER when: the question is how to sign someone in or seed a persona (that is pikku-auth), or how to shape a paginated list (that is pikku-list-query).
+  Use when deciding WHO may call a function: resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes and `defineScope`, `addGlobalPermission`, the three gates, `permissionsInBody`, and where ownership belongs versus where it does not.
+  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, about to write an `if` in a function body that decides whether the caller is allowed, or hitting `MissingScopeError`.
+  DO NOT TRIGGER when: the question is how a caller proves who they are, such as sign-in, sessions, tokens, API keys or seeding a virtual user (use pikku-auth), or how to shape a paginated list (use pikku-list-query).
 installGroups: [core]
 ---
 
 # 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` (pikku-auth, `../pikku-auth/references/machine-auth.md`). A `permissions` check that verifies a
+bearer token and returns `true` is authentication wearing an authorization hat, and it
+leaves the function sessionless. The only exception is a bootstrap endpoint whose caller
+has no identity yet (a shared-secret registration, a login): it is sessionless and
+declares its gate here.
+
 ## The rule
 
 **Authorization goes in the `permissions` field. Never in the `func` body.**
@@ -107,11 +117,32 @@ gets straight through if the function itself is open.
 ## Scopes
 
 `scopes: ['admin:invoices:void']` is an AND gate checked BEFORE permissions and before
-input validation. Declare the tree once with `defineScope`; a function naming an
-undeclared scope fails codegen rather than gating on nothing. A grant satisfies a scope if
-it is that scope, an ancestor, or a wildcard — a session holding `admin` satisfies
-`admin:invoices:void`. Most apps need roles, not scopes; reach for these only when the
-plan asked for granular grants.
+input validation. A function naming an undeclared scope fails codegen rather than gating on
+nothing. A grant satisfies a scope if it is that scope, an ancestor, or a wildcard. Most
+apps need roles, not scopes; reach for these only when the plan asked for granular grants.
+The `defineScope` tree, grant matching and the sessionless restriction are in
+[references/scopes.md](references/scopes.md).
+
+## Global permissions
+
+`addGlobalPermission([isEmployee])` (from `#pikku/auth`) is an app-wide baseline every
+function must additionally pass. It is an independent AND gate: it can only narrow access,
+never grant what a function's own `permissions` would deny. Multiple calls accumulate and
+are AND'd.
+
+## The three gates
+
+All must pass, in this order:
+
+1. **Scopes** (`scopes`) — AND'd, checked before input validation, fails closed.
+2. **Global permissions** (`addGlobalPermission`) — AND'd together, a baseline that only narrows.
+3. **The function's own `permissions`** — OR'd groups of AND'd entries.
+
+They are independent: a broad global (e.g. `isEmployee`) can never satisfy an admin-only
+function's own requirement. Wire-, tag- and HTTP-route-level permissions
+(`addHTTPPermission`, `addTagPermission`, a `permissions` field on a wiring) no longer
+exist; tags are organizational only. Use tag/HTTP middleware for cross-cutting request
+handling, not authorization.
 
 ## The one sanctioned exception
 
@@ -122,5 +153,5 @@ the auditor the openness is deliberate. Anything expressible as a permission mus
 
 ## After changes
 
-`pikku all` — regenerates and typechecks the checkers. A permission whose signature is
-wrong fails here, not at runtime.
+`pikku all --tsc` — regenerates, then verifies the checker types. A permission whose
+signature is wrong fails here, not at runtime.

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

@@ -0,0 +1,59 @@
+# Scopes
+
+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.
+
+## Declaring the tree
+
+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.
+
+```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.
+
+## Using them
+
+```typescript
+export const voidInvoice = pikkuFunc({
+  scopes: ['admin:invoices:void'],
+  permissions: { owner: isInvoiceOwner },
+  func: async ({ kysely }, { invoiceId }) => { ... },
+})
+```
+
+A grant satisfies a required scope if it is the scope itself, an ancestor of it, or a
+wildcard at any level: a session holding `admin` satisfies `admin:invoices:void`, and so
+does `admin:*`. A missing scope throws `MissingScopeError` naming the first one that
+failed.
+
+## Not on sessionless functions
+
+`scopes` requires a session and 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.

package/skills/pikku-react/SKILL.md

@@ -3,12 +3,10 @@ name: pikku-react
 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 / DevActorSwitcher / 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).
+  direct usePikkuRPC / usePikkuFetch calls, realtime subscriptions, and agent and workflow hooks. TRIGGER when: writing a React component that fetches or mutates backend
+  data, wiring PikkuProvider, paginating, running or tracking a workflow from the client. DO NOT TRIGGER when: working on the
+  backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), rendering fetched values such as
+  dates (use pikku-tailwind), or writing user-facing copy (use pikku-i18n).
 installGroups: [client]
 ---
 
@@ -21,25 +19,25 @@ stops.
 
 ## Pick the reference
 
-| 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` |
+| 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`   |
 
 ## Reach for what
 
-| 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()` |
+| 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()`                                     |
 
 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.

package/skills/pikku-react/references/client.md

@@ -1,6 +1,5 @@
 # Pikku React
 
-
 What is here:
 
 - [What ships](#what-ships)
@@ -174,8 +173,8 @@ helpers live in **pikku-wiring**.
 | 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          | `references/workflows.md`               |
-| Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-wiring**)      |
+| Longer-running workflow UX          | `references/workflows.md`                          |
+| Subscribe to events / SSE / channel | `usePikkuRealtime()` (see **pikku-wiring**)        |
 
 The first three live in your generated `api.gen.ts` (see the
 `references/react-query.md`). This reference covers the rest.
@@ -240,73 +239,6 @@ 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, pendingId, isPending, error } = useDevActors({
-  apiUrl: apiUrl(),
-  app: appSlug,
-  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.
-- **No credential reaches the bundle.** It lists from `/auth/sign-in/personas`
-  and `signInAs(id)` posts only the persona id to `/auth/sign-in/persona`. The
-  server decides who is offered and who may sign in, and offers nobody in
-  production — see **pikku-scenario** for `personaSignIn`.
-- **It takes `onSignedIn` rather than a router**, since every app lands
-  somewhere different.
-- `listDevActors()` and `signInAsPersona()` are exported too, for a non-React
-  caller. The endpoint only
-  signs in rows flagged `actor: true`, so it can never impersonate a real user —
-  see **pikku-auth**.
-
-Do not hand-write the list-and-sign-in pair per app; that copy-paste 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.
-
 ## What NOT to do
 
 - Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`

package/skills/pikku-react/references/react-query.md

@@ -1,5 +1,16 @@
 # Pikku React Query Hooks
 
+## Contents
+
+- [Discover what's available on the client](#discover-whats-available-on-the-client)
+- [Setup (once per app)](#setup-once-per-app)
+- [TanStack Start (SSR)](#tanstack-start-ssr)
+- [The hooks](#the-hooks)
+- [Workflow hooks](#workflow-hooks)
+- [Calling RPCs without React Query](#calling-rpcs-without-react-query)
+- [Common patterns](#common-patterns)
+- [What NOT to do](#what-not-to-do)
+
 
 ## Discover what's available on the client
 

package/skills/pikku-react/references/workflows.md

@@ -1,5 +1,16 @@
 # Pikku Workflows — Client Hooks
 
+## Contents
+
+- [Discover what workflows exist](#discover-what-workflows-exist)
+- [Setup](#setup)
+- [useRunWorkflow(name, options?) — run and wait](#userunworkflowname-options--run-and-wait)
+- [useStartWorkflow(name, options?) — fire-and-poll](#usestartworkflowname-options--fire-and-poll)
+- [useWorkflowStatus(workflowName, runId, options?) — observe](#useworkflowstatusworkflowname-runid-options--observe)
+- [Putting it together — start + observe](#putting-it-together--start--observe)
+- [Backend: streaming richer progress](#backend-streaming-richer-progress)
+- [What NOT to do](#what-not-to-do)
+
 
 ## Discover what workflows exist
 

package/skills/pikku-realtime/SKILL.md

@@ -1,9 +1,15 @@
 ---
 name: pikku-realtime
 description: >-
-  Use when making ANY view live/realtime in a Pikku app — a board, shared list, dashboard, ticker, bidding room, live count — or when adding two-way chat/presence. Covers the DEFAULT event-hub SSE path and the two-way WebSocket channel.
-  TRIGGER when: the user wants live updates, realtime, "update without refresh", a live board/feed/ticker/room, presence, or chat; or when data that MORE THAN ONE signed-in user can change should reflect others
-  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (see `pikku-wiring`'s scheduler and queue references, or `pikku-workflow`).
+  Use when making a view live in a Pikku app — a board, shared list, dashboard, ticker, bidding
+  room, live count — or when adding two-way chat or presence. Covers the default event-hub SSE path
+  (`eventHub.publish` on the backend, `PikkuRealtime.subscribeToTopic` on the client) and the
+  two-way WebSocket channel. TRIGGER when: the user wants live updates, realtime, "update without
+  refresh", a live board/feed/ticker/room, presence or chat, or data that more than one signed-in
+  user can change should reflect to others. DO NOT TRIGGER when: a one-shot query/refetch is enough
+  (data only one user changes, or a manual refresh is acceptable), for background jobs (use
+  pikku-workflow, or pikku-wiring's queue and scheduler references), or for the full wiring
+  reference of channels, SSE routes and the `/events` scaffold (use pikku-wiring).
 installGroups: [core, client]
 ---
 

package/skills/pikku-report/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: pikku-report
 description: >-
-  Use when pikku itself cost you time — wrong generated types, a check that passes when it
-  should not, output that is quietly wrong, a skill that misled you — or when the user asks you
-  to report a framework bug or file a finding. Owns `pikku fabric report` (a finding is about
-  pikku, not the app), the product-vs-harness kinds, the workaround-first ladder, and asking the
-  user at hand-over whether to send what was filed. TRIGGER when: the framework fought you,
-  codegen produced something broken, a skill told you to run something that does not exist, the
-  user says "report this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug is in the app you are building (fix it
-  there), or you are tempted to patch pikku's source (never do that from an app).
+  Use when pikku itself cost you time — wrong generated types, a check that passes when it should
+  not, output that is quietly wrong, a skill that misled you — or when the user asks you to report
+  a framework bug or file a finding. Owns `pikku cloud report` (a finding is about pikku, not the
+  app), the product-vs-harness kinds, the workaround-first ladder, and asking the user at hand-over
+  whether to send what was filed. TRIGGER when: the framework fought you, codegen produced
+  something broken, a skill told you to run something that does not exist, the user says "report
+  this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug
+  is in the app you are building (fix it there), you are debugging a deployed stage,
+  or you are tempted to patch pikku's source (never do that from an app).
 installGroups: [core]
 ---
 
-# Report a finding to Fabric
+# Report a finding to Pikku Studio Cloud
 
 A finding is about **pikku**, not about the app you are building. It is how the
 framework learns what cost its users time — the bug, the misleading skill, the
@@ -20,7 +21,7 @@ silence where a check should have complained.
 
 File each one the moment it happens. Nothing leaves the machine until the user
 says so at hand-over, and nothing is written to the repository. The command is
-spelled `pikku fabric report` — there is no top-level report command.
+spelled `pikku cloud report` — there is no top-level report command.
 
 ## Report at the moment it happens
 
@@ -61,7 +62,7 @@ baseline noise that was already failing before you started.
 - `--kind harness` — a skill misled you: it told you to run something that does
   not exist, described a flag that is spelled differently, or contradicted what
   the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
-section>"`. This is the most useful kind to file, because it is fixable
+  section>"`. This is the most useful kind to file, because it is fixable
   immediately — so file it even when the cost was small.
 
 ## The command
@@ -74,7 +75,7 @@ follows it. Quote the heredoc delimiter (`<<'EOF'`, never `<<EOF`) so the shell
 leaves the body alone.
 
 ```bash
-pikku fabric report --stdin <<'EOF'
+pikku cloud report --stdin <<'EOF'
 {
   "title": "<one-line title>",
   "kind": "product",
@@ -87,7 +88,7 @@ pikku fabric report --stdin <<'EOF'
 EOF
 ```
 
-The same fields exist as flags for a finding short enough to type; `pikku fabric
+The same fields exist as flags for a finding short enough to type; `pikku cloud
 report --help` lists them. Whichever path you use, the rules below are checked
 before anything is sent:
 
@@ -115,7 +116,7 @@ The last thing in the hand-over — after the app runs, and is deployed if they
 chose to — is:
 
 ```bash
-pikku fabric report
+pikku cloud report
 ```
 
 With no finding, it lists what this build filed. What happens next depends on
@@ -129,12 +130,12 @@ what the user said before, which the CLI keeps on their machine:
   **Never**. Then run it again with their answer:
 
   ```bash
-  pikku fabric report --consent yes|no|always|never
+  pikku cloud report --consent yes|no|always|never
   ```
 
   Yes sends and No discards what is held now; Always and Never are saved and the
   question is not asked again. If nobody answers, leave them held and say that
-  `pikku fabric report` sends them later.
+  `pikku cloud report` sends them later.
 
 Findings are anonymous: no account, no project. The receipt printed when you
 filed each one is exactly what leaves the machine. A send that fails keeps what