@pikku/skills 0.12.52 → 0.12.55

package/dist/snippets.js

@@ -91,7 +91,7 @@ export const collectSnippets = async (projectDir, into = new Map(), origins = ne
 /**
  * A fence that names a region instead of carrying code:
  *
- * ```ts snippet:definePersonas
+ * ```ts snippet:defineVirtualUsers
  * ```
  *
  * The language is optional and kept. Marked fences are replaced whole — both

package/package.json

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

package/skills/pikku-a11y/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-a11y
 description: >-
-  Accessibility rules (WCAG 2.2) for the app UI: labeled inputs, real buttons/links, keyboard and focus, contrast and not-color-alone, modals, reduced motion.
+  Accessibility rules (WCAG 2.2) for shadcn/Tailwind app UI: labeled inputs, real buttons/links, keyboard and focus, contrast and not-color-alone, modals, reduced motion.
   TRIGGER when: building forms or any interactive UI, icon-only buttons, modals/drawers, tables/lists with actions, keyboard/focus work, or the user mentions accessibility / screen readers / WCAG.
   DO NOT TRIGGER when: working on backend functions, database, or deployment with no UI.
 installGroups: [client]
@@ -9,24 +9,23 @@ installGroups: [client]
 
 # Accessibility Rules
 
-Mantine components are accessible ONLY when used properly — the rules below are the
-"properly". They apply to every page; heading order, landmarks, and image alt text are
-covered in the `pikku-seo` skill and apply app-wide, not just on public pages.
+shadcn components are accessible ONLY when used properly — the rules below are the
+"properly". They apply to every page, public or logged-in. This skill owns heading hierarchy,
+landmarks and image alt text app-wide (below); `pikku-seo` covers only public-route SEO.
 
 ## Every input has a label
 
-- Use the `label` prop on every Mantine input — a placeholder is NOT a label (it
+- Give every input a `<Label htmlFor>` — a placeholder is NOT a label (it
   disappears on input and is never announced as one). Placeholder = example value only.
-- Use the `error` and `description` props for validation/help text — Mantine associates
-  them with the input for screen readers; a loose `<Text c="red">` next to the field
-  does not.
-- Icon-only controls (`ActionIcon`, icon `Button`) MUST have `aria-label={m.key()}`
+- Wire validation and help text to the input with `aria-describedby` (and `aria-invalid`) — a loose
+  red paragraph next to the field is not announced with it.
+- Icon-only controls (icon `Button`) MUST have `aria-label={m.key()}`
   naming the action ("Delete item", not "Trash icon").
 
 ## Interactive = a real button or link
 
-- Never `onClick` on a `div`/`Box`/`Card` — it is invisible to keyboard and screen
-  readers. Use `Button`, `ActionIcon`, `UnstyledButton`, or `<Link>`; navigation is a
+- Never `onClick` on a `div`/`Card` — it is invisible to keyboard and screen
+  readers. Use `Button` or `<Link>`; navigation is a
   link (href), actions are buttons.
 - Everything reachable by Tab, activatable by Enter/Space. Never remove focus outlines
   (the theme owns the focus ring), never set `tabIndex` greater than 0, never trap focus
@@ -38,14 +37,14 @@ covered in the `pikku-seo` skill and apply app-wide, not just on public pages.
 
 - Status must carry text or an icon, not only a color: a Badge says "Overdue", a form
   error has a message — a red tint by itself is invisible to colorblind users.
-- Contrast comes from the theme; don't undermine it by stacking `c="dimmed"` on small
+- Contrast comes from the theme; don't undermine it by stacking `text-muted-foreground` on small
   text over tinted backgrounds. Body copy stays at least AA-readable.
-- Touch targets: WCAG 2.2 minimum 24px — don't shrink `ActionIcon`/`Checkbox` below
-  size `sm`, and keep adjacent row actions spaced.
+- Touch targets: WCAG 2.2 minimum 24px — don't shrink icon buttons or checkboxes below
+  24px, and keep adjacent row actions spaced.
 
 ## Overlays and motion
 
-- Modals/drawers: use Mantine `Modal`/`Drawer` and ALWAYS pass `title` — that is what
+- Modals/drawers: use shadcn `Sheet`/`Dialog` and ALWAYS include a `Title` — that is what
   gets announced; focus trap and Escape come built in. (This project uses drawers, not
   dialogs.)
 - Landing-page animation (the only custom-CSS surface) respects
@@ -57,3 +56,11 @@ Tab through the page once: every control reachable and visibly focused, every in
 labeled, every icon button named, every status readable without color. A browser
 scenario proves the flow works, not that it is reachable without a mouse — this
 manual pass is the only check that does.
+
+## Headings, landmarks, alt text (app-wide)
+
+- Exactly one h1 per page, naming its topic. Below it: h1 → h2 → h3, no skipped levels.
+  Never pick a level for its font size — set the size on the correct level
+  (`<h2 className="text-sm">`).
+- Landmarks on every page: `<nav>`, `<main>`, `<footer>` where present (render the element itself, `<nav>`, rather than a `<div>` with a role).
+- Every meaningful `<img>` has alt text describing it; decorative images get `alt=""`.

package/skills/pikku-addon/SKILL.md

@@ -4,11 +4,11 @@ description: >-
   Use when creating or consuming reusable function packages (addons) in Pikku. Covers wireAddon,
   ref(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, addons that ship
   database tables (pikku db export), generating an addon from an OpenAPI/Swagger spec, and
-  cross-project function sharing. TRIGGER when: code uses wireAddon/ref()/pikkuAddonServices, user
-  asks about addons, reusable function packages, cross-project sharing, or addon package structure,
-  or the user hands over an OpenAPI/Swagger spec (file or URL) to build on. DO NOT
-  TRIGGER when: user asks about internal function composition (use pikku-wiring) or general function
-  definitions (use pikku-concepts).
+  cross-project function sharing. TRIGGER when: code uses wireAddon/ref()/pikkuAddonServices, the
+  user asks about addons, reusable function packages, cross-project sharing or addon package
+  structure, or hands over an OpenAPI/Swagger spec (file or URL) to build on. DO NOT TRIGGER when:
+  the user asks about internal function composition (use pikku-wiring), general function
+  definitions (use pikku-concepts), or importing an n8n export (use pikku-n8n-import).
 installGroups: [core]
 ---
 

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -1,5 +1,12 @@
 # Addon Package Manifest Reference
 
+## Contents
+
+- Package Structure
+- pikku.config.json
+- package.json (key fields)
+- tsconfig.json (key fields)
+
 `npx pikku new addon` scaffolds these files. You rarely hand-edit them — consult this when wiring exports or config by hand.
 
 ## Package Structure

package/skills/pikku-addon/references/openapi.md

@@ -1,5 +1,16 @@
 # An addon from an OpenAPI spec
 
+## Contents
+
+- Recognising one
+- 1 — Look at the spec first
+- 2 — Generate, from the app's root
+- 3 — Check what was generated
+- 4 — Call it from the app
+- 5 — Verify
+- 6 — Check the spec against the real API
+- Then
+
 When you are handed an OpenAPI or Swagger spec — a file, or a URL to one — the
 API it describes becomes an addon: one function per operation, each with its
 input and output schemas, behind one service that makes the HTTP calls. Say so

package/skills/pikku-agent/SKILL.md

@@ -4,11 +4,11 @@ description: >-
   Use when building AI agents, chatbots or LLM-powered assistants with Pikku — pikkuAgent, ref()
   tool registration, memory, streaming, tool approval, thread ownership, invocation via rpc.agent,
   the VercelAgentRunner and its provider map, and the voiceInput/voiceOutput middlewares. TRIGGER
-  when: code uses pikkuAgent/rpc.agent/runAgent/streamAgent/VercelAgentRunner/voiceInput, user asks
-  about AI agents, chatbots, tool-calling, agent memory or streaming, model providers, speech in or
-  out, or `pikku enable agent`. DO NOT TRIGGER when: user asks about MCP tool exposure (use
-  pikku-wiring), workflows (use pikku-workflow), or general function definitions (use
-  pikku-concepts).
+  when: code uses pikkuAgent/rpc.agent/runAgent/streamAgent/VercelAgentRunner/voiceInput, or the
+  user asks about AI agents, chatbots, tool-calling, agent memory or streaming, model providers,
+  speech in or out, or `pikku enable agent`. DO NOT TRIGGER when: the user asks about MCP tool
+  exposure (use pikku-wiring), workflows (use pikku-workflow), React agent hooks (use pikku-react),
+  or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
 
@@ -49,7 +49,7 @@ session, the credentials and the RPC depth for you.
   `output` schema, and the picture passed as an `attachments` entry.
 - **`auth` defaults to `false`**, because agents are normally invoked from an
   already-authenticated `pikkuFunc`. `scopes` and `permissions` are enforced
-  either way — see `pikku-auth`.
+  either way — see `pikku-permissions`.
 - **`approvalRequired` sits on the tool function, not on the agent.** The run
   then resolves `status: 'suspended'` with `pendingApprovals`; answer with
   `rpc.agent.approve(runId, approvals)`.

package/skills/pikku-agent/references/agents.md

@@ -1,5 +1,12 @@
 # Pikku AI Agent Wiring
 
+## Contents
+
+- Before You Start
+- API Reference
+- Usage Patterns
+- Complete Example
+
 
 ## Before You Start
 
@@ -83,7 +90,7 @@ import cycle.
 
 `auth` defaults to `false` because agents are usually invoked from an
 already-authenticated `pikkuFunc`. `scopes` and `permissions` are enforced either
-way — see `pikku-auth`.
+way — see `pikku-permissions`.
 
 ### Invoking an agent
 

package/skills/pikku-agent/references/runner-vercel.md

@@ -25,7 +25,7 @@ const runner = new VercelAgentRunner(
 
 - `stream(params: AgentRunnerParams, channel: AgentStreamChannel): Promise<AgentStepResult>` — Stream AI responses with tool calls
 - `run(params: AgentRunnerParams): Promise<AgentStepResult>` — Execute a single AI step (non-streaming)
-- `transcribe({ model, audio, … })` / `generateSpeech({ model, text, voice, … })` — what `voiceInput`/`voiceOutput` call; see `references/voice.md`
+- `transcribe({ model, audio, … })` / `generateSpeech({ model, text, voice, … })` — what `voiceInput`/`voiceOutput` call; see the voice reference
 - `generateImage`, `embed`, `embedMany`, `rerank` — the remaining AI SDK surfaces
 - `withApiKey(apiKey)` — returns a **new** runner built from `providerFactory`; returns `this` unchanged when no factory was supplied or the key is blank. This is the per-user-credential path
 
@@ -85,7 +85,7 @@ export const assistant = pikkuAgent({
 ```
 
 There is no `wireAgent` — agents are declared with `pikkuAgent` from the
-generated agent types. See `references/agents.md` for the full config.
+generated agent types. The full config is in the agents reference.
 
 ### Testing without a real provider
 

package/skills/pikku-agent/references/voice.md

@@ -1,5 +1,11 @@
 # Pikku AI Voice (Speech I/O)
 
+## Contents
+
+- `@pikku/ai-voice` is deprecated and empty
+- API Reference
+- Usage Pattern
+
 
 ## `@pikku/ai-voice` is deprecated and empty
 
@@ -9,7 +15,7 @@ dependency.
 
 Voice now lives in **`@pikku/core/agent`** as two AI middlewares, and the
 speech models are reached through the `agentRunner` (`transcribe` /
-`generateSpeech`) rather than through separate services. See `references/runner-vercel.md`.
+`generateSpeech`) rather than through separate services. The runner reference covers that wiring.
 
 ## API Reference
 

package/skills/pikku-architect/SKILL.md

@@ -3,7 +3,7 @@ name: pikku-architect
 description: >-
   Use to turn one claimed changeset into the technical plan its build is measured against —
   the tables, functions, wires, roles, scopes, screens and scenarios it owes, split into passes and
-  written through `pikku knowledge plan set <changeset>`. The plan is the denominator
+  written through `pikku knowledge plan set`. The plan is the denominator
   `pikku knowledge plan progress` divides by, so it is written BEFORE any of the changeset's code
   exists and never edited afterwards to match what got built. TRIGGER when: `pikku changes
   claim` says a changeset needs a plan, `changes done` or `pikku changes next` refuses one for having no
@@ -285,7 +285,7 @@ one, and is worth opening for any question you cannot answer with a flat yes.
 2. **Does pass 1 slice, and does the model fit inside it?** Not "pass 1: the data model, pass 2: the
    API" — and `model` holds only the tables pass 1 or 2 actually migrates, because the model slot has
    no passes and a later table is a PROBLEM from the first day.
-3. **Can each scenario actually be performed?** Name the persona; assert what the person got rather
+3. **Can each scenario actually be performed?** Name the virtual user; assert what the person got rather
    than that the code ran; write totals as deltas against a database nobody resets; check that every
    input the prose describes is a field somebody planned.
 4. **Does something produce every state and field the plan reads?** For each clause of a description,

package/skills/pikku-architect/references/plan-defects.md

@@ -5,6 +5,8 @@ item. These are the ones it cannot, each carried back from a changeset that ship
 grouped by the question that finds them, and the fastest way to use this file is to read the six
 questions and only open the group that worries you.
 
+## Contents
+
 1. [Is this a plan for THIS note?](#is-this-a-plan-for-this-note)
 2. [Does pass 1 slice, and does the model fit inside it?](#does-pass-1-slice-and-does-the-model-fit-inside-it)
 3. [Can each scenario actually be performed?](#can-each-scenario-actually-be-performed)
@@ -37,8 +39,8 @@ a second changeset — say so in `covers`.
 
 ## Can each scenario actually be performed?
 
-**Ask which persona performs it. If the answer is "nobody", it belongs one level up or to no pass
-at all.** The runner drives the app as the personas the project declares; there is no anonymous
+**Ask which virtual user performs it. If the answer is "nobody", it belongs one level up or to no pass
+at all.** The runner drives the app as the virtual users the project declares; there is no anonymous
 RPC caller, so "a caller with no session is refused" is a sentence a backend or permission
 scenario cannot perform. Signed-out is a BROWSER fact.
 
@@ -78,7 +80,7 @@ decision that nothing records.
 in this plan, or one already in the meta. Write "when the distributor is removed its companies
 fall back to the direct catalog" with no function that removes a distributor and `plan set`
 accepts it, `plan progress` passes, and the changeset ships a sentence nothing proves. Read each
-description back asking *which function does this*, and cut the half you cannot name.
+description back asking _which function does this_, and cut the half you cannot name.
 
 **Where a scenario calls the same function twice, check it for a per-period guard first.** A
 one-per-day, one-per-order or one-per-person rule makes the second call a refusal, so the journey
@@ -99,14 +101,14 @@ mark a product's countries, cannot be proven without amending the plan mid-build
 **Every state a scenario waits in needs the function that leaves the world like that — checked
 against the code ALREADY built.** Three failure shapes, in rising order of cost:
 
-- *Stale*: a staff queue of "paid orders with no invoice yet", where an earlier changeset had
+- _Stale_: a staff queue of "paid orders with no invoice yet", where an earlier changeset had
   moved invoicing to checkout. No order a customer could place was ever in that state; three
   scenarios passed once against old rows, then failed.
-- *Unreachable*: staff asked to "capture the payment on an authorised order" when no function in
+- _Unreachable_: staff asked to "capture the payment on an authorised order" when no function in
   the app or its addons could put an order in `authorized` — the addon only holds money when
   checkout was started with a flag the plan's own checkout input did not carry.
-- *Wrong person*: a distributor salon owner planned to buy from a catalogue that is scoped by
-  distributor and does not show her the product. Actors are not interchangeable.
+- _Wrong person_: a distributor salon owner planned to buy from a catalogue that is scoped by
+  distributor and does not show her the product. Virtual users are not interchangeable.
 
 **A `model` slot saying "this changeset adds no table" has to be true of the DATA the scenarios
 read, not only of the entities they name.** One promised a checkout priced by delivery country — a

package/skills/pikku-auth/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: pikku-auth
 description: >-
-  Use for anything about identity in a Pikku app — authenticating a caller (login, logout,
-  sessions, cookies, bearer tokens, API keys, JWT, OAuth/social providers, MFA, Better Auth) and
-  authorizing one (pikkuPermission, pikkuAuth, scopes, defineScope, global permissions). Covers
-  which of the two a problem actually is, the built-in auth strategies, machine-to-machine auth
-  and `pikku login`, and the JWT service. TRIGGER when: user asks about login, logout, session,
-  cookie auth, bearer tokens, API keys, JWT, Better Auth, social providers, restricting who may
-  call a function, resource ownership, roles, scopes, or hits MissingScopeError or
-  InvalidSessionError. DO NOT TRIGGER when: user asks about middleware mechanics with no identity
-  involved (use pikku-middleware) or about secrets and env vars (use pikku-services).
+  Use for identity in a Pikku app: authenticating a caller (login, logout, sessions, cookies,
+  bearer tokens, API keys, JWT, OAuth/social providers, MFA, Better Auth, machine callers,
+  `pikku login`). Covers telling authentication from authorization, the built-in strategies and
+  the JWT service. Authorization rules (ownership, roles, scopes, global permissions) live in
+  pikku-permissions. TRIGGER when: user asks about login, logout, session, cookie auth, bearer
+  tokens, API keys, JWT, Better Auth, social providers, how a CLI/agent/sandbox authenticates,
+  or hits InvalidSessionError. DO NOT TRIGGER when: the question is who may call a function,
+  such as ownership, roles, per-row checks, scopes or MissingScopeError (use pikku-permissions),
+  middleware mechanics with no identity involved (use pikku-middleware), or secrets and env
+  vars (use pikku-services).
 installGroups: [core]
 ---
 
@@ -28,7 +29,8 @@ Pikku app.
 function runs, and ends in a call to `setSession`.
 
 **Authorization** answers _may this caller do this_. It is declared on the
-function — `scopes` and `permissions` — never checked inside its body.
+function — `scopes` and `permissions` — never checked inside its body. All of it is
+covered by the pikku-permissions skill.
 
 A `permissions` entry that verifies a bearer token and returns `true` is
 authentication wearing an authorization hat: it leaves the function sessionless,
@@ -39,7 +41,7 @@ middleware instead.
 
 | You are… | Read |
 | --- | --- |
-| Restricting who may call a function — ownership, roles, scopes | `references/permissions.md` |
+| Restricting who may call a function — ownership, roles, scopes | the pikku-permissions skill |
 | Reading or setting the session, or wiring `authBearer`/`authCookie`/`authAPIKey` | `references/sessions.md` |
 | Standing up user sign-in — OAuth, email+password, MFA, organizations | `references/better-auth.md` |
 | Authenticating a CLI, agent, sandbox or worker — API keys, `pikku login` | `references/machine-auth.md` |
@@ -53,30 +55,8 @@ will not work against them. `references/better-auth.md` has the setup; the
 built-in strategies in `references/sessions.md` are how a resolved credential
 becomes a Pikku session, not a replacement for it.
 
-## The three gates
-
-Authorization is three independent gates, all of which must pass, in this order:
-
-1. **Scopes** (`scopes`) — AND'd, checked before input validation, fails closed.
-2. **Global permissions** (`addGlobalPermission`) — AND'd, an app-wide baseline.
-3. **The function's own `permissions`** — OR'd groups of AND'd entries.
-
-They are independent: a broad global gate can never satisfy a function's own
-requirement, and a scope can only ever narrow access, never grant it.
-
 ## What NOT to do
 
-- **Do not check authorization inside `func`.** The `permissions` field is
-  visible to the inspector; a check in the body is invisible to `pikku info
-  permissions` and to an audit. The one sanctioned exception is
-  `permissionsInBody`, which is purely declarative — see
-  `references/permissions.md`.
-- **Do not write an "is signed in" permission.** `auth: true` (the default on
-  `pikkuFunc`) already requires the session. A checker returning `!!session`
-  gates nothing.
-- **Do not put `scopes` on a `pikkuSessionlessFunc`.** Scopes fail closed and an
-  anonymous caller holds none, so it would reject every caller it exists to
-  serve. Gate those with `permissions`, which receive an optional session.
 - **Do not expect the built-in strategies to authenticate a non-HTTP caller.**
   `authBearer`, `authCookie` and `authAPIKey` all step aside when there is no
   HTTP request — a queue job, a scheduled task or a channel message needs its
@@ -84,6 +64,5 @@ requirement, and a scope can only ever narrow access, never grant it.
 - **Do not share one header between the human and machine paths.**
   `Authorization: Bearer` is the human session; `x-api-key` is the machine key.
   Merging them reintroduces the ambiguity the split exists to remove.
-- **Do not reach for wire-, tag- or route-level permissions.** They were removed
-  in #972. Permissions live on the function, plus the optional global gate; tags
-  are organizational only.
+- **Do not write authorization here.** Ownership, roles, scopes and global
+  permissions belong in the `permissions`/`scopes` fields; see pikku-permissions.