@pikku/skills 0.12.52 → 0.12.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.52",
+  "version": "0.12.54",
   "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-admin-to-fabric/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pikku-admin-to-fabric
-description: 'Port a legacy back-office admin (ActiveAdmin, Django admin, Rails Admin, Laravel Nova, Filament) to Fabric admin screens, driven by a `.knowledge/` Product Blueprint. Covers the admin-DSL→Fabric mapping (resources→screens, index/column→tables, filter→query params, scope→query variants, member_action/collection_action→pikkuFuncs, permit_params→input schemas), the "the admin is half your app" audit, and admin-specific permissions. TRIGGER when: porting/rebuilding a legacy app that has a generated/DSL-driven admin, or the user says "port the admin screens" / "implement the admin". DO NOT TRIGGER when: no legacy admin exists (use pikku-fabric to build screens fresh), or the app is being extended rather than ported (use pikku-build).'
+description: 'Port a legacy back-office admin (ActiveAdmin, Django admin, Rails Admin, Laravel Nova, Filament) to Fabric admin screens, driven by a `.knowledge/` Product Blueprint. Covers the admin-DSL→Fabric mapping (resources→screens, index/column→tables, filter→query params, scope→query variants, member_action/collection_action→pikkuFuncs, permit_params→input schemas), the "the admin is half your app" audit, and admin-specific permissions. TRIGGER when: the legacy app being ported has a generated/DSL-driven admin, or the user says "port the admin screens" / "implement the admin"; used per resource alongside pikku-blueprint-to-fabric, which owns the rest of the port. DO NOT TRIGGER when: no legacy admin exists (use pikku-fabric to build screens fresh), no blueprint exists yet (use pikku-software-archaeology), or the app is being extended rather than ported (use pikku-build).'
 installGroups: [fabric]
 argument-hint: '<path to .knowledge/> [resource to port next]'
 ---
 
 # Legacy admin → Fabric admin screens
 
-## Agent Operating Procedure
+## Operating procedure
 
 1. **Count first.** How many commands cite the admin? That number decides whether this is a chore or a third of the project.
 2. **The blueprint already has the commands.** Do not re-derive them from the DSL. Map to them.
@@ -71,10 +71,10 @@ grep -rhoE "(member_action|collection_action) :[a-z_]+" app/admin/*.rb | sort -u
 | Legacy | Also called | Becomes in Fabric |
 |---|---|---|
 | `ActiveAdmin.register X` / `class XAdmin` | resource, ModelAdmin, Nova Resource | one TanStack route + one screen |
-| `index do … column :x` | `list_display`, `columns()` | a Mantine `Table`/`DataTable`, columns from the query's return type |
+| `index do … column :x` | `list_display`, `columns()` | a shadcn `Table`/data table, columns from the query's return type |
 | `filter :x` | `list_filter`, `searchable` | typed input fields on the list query |
 | `scope :active` | `get_queryset` variants, `Nova::Filters` | a named variant of the list query — NOT a new function per scope |
-| `form do f.input …` | `fields()`, `fieldsets` | a Mantine form; inputs from the command's zod input schema |
+| `form do f.input …` | `fields()`, `fieldsets` | a shadcn form; inputs from the command's zod input schema |
 | `permit_params` | `fields`, `$fillable` | you already have this: it is the command's input schema. Cross-check, don't re-derive. |
 | `member_action :foo` | custom action, `Nova::Actions` | **a `pikkuFunc`** — almost always already in `commands.json` |
 | `collection_action :foo` | bulk action | a `pikkuFunc` taking a set |
@@ -154,7 +154,7 @@ impersonation and editing an FAQ all guarded identically.
 - Columns come from the query's return type. If a column exists in the DSL but not
   in the type, the DSL was computing it in Ruby per row — that is an N+1 wearing a
   column, and it belongs in the query.
-- Reuse the app's Mantine theme. An admin styled differently from the product is
+- Reuse the app's theme. An admin styled differently from the product is
   how design systems fork.
 - **Server-computed charts** (chartkick/groupdate and friends) do not port. The
   aggregation becomes a real query; the plot becomes a chart component. This is the
@@ -190,23 +190,9 @@ Per resource, the parity report records:
 | "The admin action isn't in commands.json, I'll add it" | Stop. Either the archaeology missed it (fix the blueprint) or it is dead. Both are findings. |
 | "I'll restyle the admin, it's internal" | An admin off the product's theme is how a design system forks. |
 
-## Quick Reference
-
-```bash
-# 1. how much of the app is actually the admin?
-node -e "const c=require('./.knowledge/commands.json').commands;console.log(c.filter(x=>(x.evidence||[]).some(e=>(e.file||'').match(/admin/))).length+'/'+c.length)"
-
-# 2. inventory the capabilities (not the buttons)
-grep -rhoE "(member_action|collection_action) :[a-z_]+" app/admin/*.rb | sort -u
-
-# 3. per resource: map actions -> commands.json, then build the screen
-# 4. verify
-pikku all && pikku fabric validate --json
-```
-
 ## Related skills
 
 - **pikku-software-archaeology** — produces the `.knowledge/` blueprint this needs.
 - **pikku-blueprint-to-fabric** — the parent port; run this per-domain alongside it.
-- **pikku-auth** — roles, ban and impersonation, and the scopes that gate them.
-- **pikku-fabric** — screens, theme, Mantine conventions.
+- **pikku-auth** — roles, ban and impersonation; **pikku-permissions** — the scopes that gate them.
+- **pikku-fabric** — screens, theme, shadcn conventions.

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

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)

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.

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

@@ -238,7 +238,7 @@ never needs to know about scopes or roles.
 
 ### The plugins `@pikku/better-auth` ships
 
-Five, all imported from the package root and passed to `betterAuth({ plugins })`
+Four, all imported from the package root and passed to `betterAuth({ plugins })`
 like any other. None is automatic — an app wires the ones it needs.
 
 | Plugin                   | Plugin `id`        | Adds                                                                    | Use it when                                                   |
@@ -247,12 +247,11 @@ like any other. None is automatic — an app wires the ones it needs.
 | `pikkuActor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
 | `pikkuCredentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
 | `pikkuDelegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
-| `pikkuFabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
 
 Every one carries a `pikku` prefix, because a `plugins: [...]` array mixes these
 with better-auth's own and a bare `actor()` next to `organization()` says
 nothing about where it came from. The unprefixed names — `ban`, `actor`,
-`credentialOAuth`, `delegatedAuth`, `fabric` — are still exported as deprecated
+`credentialOAuth`, `delegatedAuth` — are still exported as deprecated
 aliases, so existing apps keep working.
 
 The plugin's `id` is what better-auth stores; the **export name** is what the
@@ -348,21 +347,6 @@ in the `pikku-build` skill's `references/openapi.md`. When the upstream later
 refuses the stored token, the addon throws `CredentialRejectedError` (403,
 `reauth: 'sign-in'`): the UI shows the sign-in again.
 
-#### `pikkuFabric()` — control-plane operator sign-in
-
-```typescript
-pikkuFabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
-```
-
-`POST /sign-in/fabric` verifies a short-lived RS256 token that the Fabric
-control plane signed for an operator session, then signs them into a synthetic
-`fabric-<id>@fabric.internal` row holding the `admin` scope. Asymmetric on
-purpose: the app holds only the public key, so it can never forge an operator
-login, and the same `FABRIC_AUTH_PUBLIC_KEY` is distributed to every stage with
-no per-environment secret. A missing or empty key disables the endpoint, and a
-token whose `purpose` claim is not `fabric-admin` is rejected. Without a
-`ScopeService` the operator signs in holding nothing.
-
 ### 2. Production database adapter
 
 For real deployments swap `memoryAdapter` for the Kysely adapter backed by an injected DB. Better Auth owns its own tables (`user`, `session`, `account`, `verification`, plus plugin tables) — generate its schema with `npx @better-auth/cli generate` and apply it as a migration.
@@ -534,9 +518,9 @@ an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
 in as the personas the deployment provisioned when it started and refuses
 everything else (`No actor account exists for that address`), so holding the
 secret on such a stage does not let anyone invent identities. Those rows are
-written by the fabric plugin when an operator asks to act as an address the
-stage has no account for, so provisioning needs no actor secret and works on a
-stage whose endpoint is shut.
+written by `provisionPersonas` when an operator sign-in route is asked to act
+as an address the stage has no account for, so provisioning needs no actor
+secret and works on a stage whose endpoint is shut.
 
 **`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
 persona.** Provisioning grants declared roles to actor accounts, so an
@@ -566,32 +550,27 @@ id to `/sign-in/persona`, both served by
 
 ### Provisioning personas
 
-Anywhere but `pikku dev`, the accounts have to exist before anyone signs in. The
-stage creates them itself, from the personas you hand `pikkuFabric`:
+Anywhere but `pikku dev`, the accounts have to exist before anyone signs in.
+`provisionPersonas` creates them from the generated personas:
 
 ```ts
-import { pikkuFabric } from '@pikku/better-auth'
+import { provisionPersonas } from '@pikku/better-auth'
 import {
   personaConfigs,
   personaEnvironments,
 } from '#pikku/pikku-personas.gen.js'
 
-pikkuFabric({
-  publicKey,
-  audience,
-  scopeService,
-  personas: {
-    personas: personaConfigs,
-    environments: personaEnvironments,
-  },
-})
+await provisionPersonas(
+  { auth, scopeService, logger },
+  { personas: personaConfigs, environments: personaEnvironments }
+)
 ```
 
-There is nothing else to call and nothing to schedule. The plugin's operator
-endpoint resolves the address the caller wants to act as; a miss provisions the
-declaration and looks again. On a stage that already holds the persona that is
-one query, and the pass only runs when there is genuinely something absent to
-create.
+`auth` only needs to resolve `{ $context }`, so the singleton `services.auth`
+works as is. Call it from whatever route resolves the address a caller wants to
+act as: a miss provisions the declaration and looks again. On a stage that
+already holds the persona that is one query, and the pass only runs when there
+is genuinely something absent to create.
 
 **Do not reach for `pikkuServerLifecycle`'s `afterStart` for this.** That hook is
 invoked by `pikku serve` and `pikku dev` and by nothing else — no deploy runtime
@@ -619,16 +598,14 @@ open. By default provisioning warns about those accounts and changes nothing.
 `orphans: 'ban'` shuts them:
 
 ```ts
-pikkuFabric({
-  publicKey,
-  audience,
-  scopeService,
-  personas: {
+await provisionPersonas(
+  { auth, scopeService, logger },
+  {
     personas: personaConfigs,
     environments: personaEnvironments,
     orphans: 'ban',
-  },
-})
+  }
+)
 ```
 
 It writes the same `banned` column the console's ban RPC writes (so it needs the

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

@@ -1,5 +1,11 @@
 # Pikku Jose (JWT Service)
 
+## Contents
+
+- [Installation](#installation)
+- [API Reference](#api-reference)
+- [Usage Patterns](#usage-patterns)
+
 
 ## Installation
 

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

@@ -1,5 +1,11 @@
 # Pikku Machine Auth
 
+## Contents
+
+- [Human path — `pikku login`](#human-path-pikku-login)
+- [Machine path — API keys](#machine-path-api-keys)
+- [Gotchas](#gotchas)
+
 Unified authentication for humans **and** machines against a Pikku + better-auth
 server. Two paths, two headers, one resolver:
 

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

@@ -1,5 +1,11 @@
 # Pikku Security (Authentication & Sessions)
 
+## Contents
+
+- [Session Management](#session-management)
+- [Built-in Auth Strategies](#built-in-auth-strategies)
+- [Complete Example](#complete-example)
+
 
 ## Session Management
 

package/skills/pikku-blueprint-to-fabric/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: pikku-blueprint-to-fabric
-description: 'Rebuild a legacy app as a Pikku Fabric app from a `.knowledge/` Product Blueprint (produced by pikku-software-archaeology). Covers the blueprint→Fabric mapping (domains→slices, commands/queries→pikkuFuncs, entities→SQLite migrations, policies→permissions, invariants→DB constraints, workflows→schedulers, frontend-routes→TanStack+Mantine), the decisions gate, and the parity report. TRIGGER when: a `.knowledge/` blueprint exists and the user wants to rebuild/port/recreate that app in Pikku or Fabric, or says "rebuild this from the blueprint". DO NOT TRIGGER when: no blueprint exists (run pikku-software-archaeology first), or the user wants a single new feature in an existing app (use pikku-build).'
+description: 'Rebuild a legacy app as a Pikku Fabric app from a `.knowledge/` Product Blueprint (produced by pikku-software-archaeology). Covers the blueprint→Fabric mapping (domains→slices, commands/queries→pikkuFuncs, entities→SQLite migrations, policies→permissions, invariants→DB constraints, workflows→schedulers, frontend-routes→TanStack+shadcn), the decisions gate, and the parity report. TRIGGER when: a `.knowledge/` blueprint exists and the user wants to rebuild/port/recreate that app in Pikku or Fabric, or says "rebuild this from the blueprint". Admin screens are ported by pikku-admin-to-fabric alongside it. DO NOT TRIGGER when: no blueprint exists (run pikku-software-archaeology first), the user wants a single new feature in an existing app (use pikku-build), or the task is only the legacy admin screens of an already-started port (use pikku-admin-to-fabric).'
 installGroups: [fabric]
 argument-hint: '<path to .knowledge/> [domain to slice next]'
 ---
 
 # Blueprint → Fabric
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
+## Operating procedure
 
 1. **Validate the blueprint before you trust it.** Run the archaeology validator; `0 error(s)` or stop.
 2. **Clear the decisions gate.** Unresolved `decisionsNeeded` block the domains they touch. Ask; do not invent.
@@ -271,7 +269,7 @@ Two rules:
 
 ## Stage 7 — Frontend
 
-Only when `frontend*.json` is present. Target: TanStack Start + Mantine.
+Only when `frontend*.json` is present. Target: TanStack Start + Tailwind + shadcn.
 
 `frontend.json` records the legacy stack as facts. **It is context, not a port target** — a bespoke Sass system, a server-rendered template stack, or a different component library all land on the same target. Read `designSystemConsistency` and `designFindings` to know what _not_ to carry: findings are the drift (hardcoded colors, forked-per-locale pages, duplicated components), and the rebuild is the moment they cost nothing to drop.
 
@@ -287,9 +285,9 @@ Only when `frontend*.json` is present. Target: TanStack Start + Mantine.
 
 | `rebuild`             | What to do                                                                |
 | --------------------- | ------------------------------------------------------------------------- |
-| `mantine-standard`    | Use the Mantine component. Do not port.                                   |
-| `mantine-composition` | Compose from Mantine primitives. Do not port.                             |
-| `custom-style`        | Normalize to Mantine + theme tokens. The divergence is the thing to drop. |
+| `library-standard`    | Use the shadcn component. Do not port.                                   |
+| `library-composition` | Compose from shadcn primitives. Do not port.                             |
+| `custom-style`        | Normalize to shadcn + theme tokens. The divergence is the thing to drop. |
 | **`custom-logic`**    | **Port the behaviour.** Read `customLogic` and `dependencies`.            |
 
 The first three are the bulk and they're cheap — they're a re-expression, not a migration. **`custom-logic` is the actual project**: the bespoke chart, the virtualized table, the map surface, the rich editor, the drag interaction. Each has real behaviour that must survive, and `customLogic` says what it is.
@@ -348,19 +346,6 @@ Per domain:
 | "Verify once it's all built"                                           | No bisect point. Verify per slice; that's what slices are for.                                                                     |
 | "The blueprint has a `low`-confidence entry, I'll build my best guess" | That's inventing product. It's a gate question.                                                                                    |
 
-## Quick reference
-
-```bash
-node <archaeology-skill>/scripts/validate.mjs <repo>/.knowledge   # Stage 0 — must be 0 errors
-# Stage 1 — decisions gate: ask, don't invent
-# Stage 2 — clone starter template, then the post-clone cleanup (pikku-build)
-# Stage 3 — entities.json -> db/sqlite/NNNN-*.sql ; pikku db migrate
-# Stage 4..7 — one domain slice at a time, dependency order
-pikku fabric validate --json
-yarn pikku all && yarn tsc --noEmit
-# Stage 9 — .knowledge/parity-<domain>.md per slice
-```
-
 ## Relationship to the other skills
 
 ```

package/skills/pikku-blueprint-to-fabric/scripts/inventory.mjs

@@ -334,7 +334,7 @@ p('')
 if (feComponents.length) {
   p('## Frontend')
   p('')
-  p(`- **${cheapComponents.length}** components are a cheap re-expression in Mantine (standard / composition / restyle).`)
+  p(`- **${cheapComponents.length}** components are a cheap re-expression in the component library (standard / composition / restyle).`)
   p(`- **${customLogic.length}** carry \`custom-logic\` and must be **ported**. This is the real frontend project.`)
   p(`- **${feRoutes.length}** routes → TanStack routes; their \`dataFrom\` names are already the function names above.`)
   p('')