@pikku/skills 0.12.52 → 0.12.55

package/skills/pikku-theme/references/from-a-reference.md

@@ -0,0 +1,44 @@
+# Building from a reference
+
+These apply only when the user names something that already exists: a live site, a W3C design
+tokens file, a site to rebuild. With no reference, choose a preset from the domain instead. The CLI
+has no extractor: you read the design off the source and pass it to `pikku ui theme apply`.
+
+## Match an existing design
+
+1. **Read the design off the source.** Open the site (or the tokens file) and note the primary,
+   secondary and accent colours, the page background and text colour, and the heading and body
+   fonts. Note the structure hints: radius, shadow strength, density, borders.
+
+2. **Pick the structure the hints describe.** Soft shadow and large radius: `aurora` or `breeze`.
+   Bold borders and hard shadows: `brutalist`. Compact density: `monopro`. Near-black background:
+   a dark-first preset.
+
+3. **Apply.** The page background maps to `--page` and the text to `--ink`:
+
+   ```bash
+   pikku ui theme apply --preset breeze --primary '#0B6E99' --font-heading 'Manrope' --font-body 'Manrope' --page '#F7F5F0' --ink '#1C2A33'
+   ```
+
+   You are the art director: what you read is signal, not a finished theme. Check page and ink
+   against each other and against the primary for 4.5:1 before applying.
+
+4. **Build the layout craft the reference shows.** Colours, fonts, radius and shadow travel through
+   the theme. What no token carries (an asymmetric grid, a bespoke type scale, a masked image edge,
+   a hover reveal) goes in utility classes on shadcn components (or a small CSS file for what utilities cannot express), with theme variables
+   for every colour.
+
+## Rebuild an existing site
+
+When the user wants their site rebuilt or improved, not just matched:
+
+1. **Take the copy from the user.** Ask for the pages' text and images, or read the live pages
+   yourself. The CLI does not crawl or fetch stock photography; do not invent content or images.
+
+2. **Match the brand** with the recipe above.
+
+3. **Build the pages** from the shadcn components in `src/components/ui/`, filling them with the real
+   copy and the images the user supplied. Keep the meaning, discard the dated layout.
+
+If there is no copy and no imagery to work from, say so and rebuild from the brief rather than
+inventing content.

package/skills/pikku-theme/references/presets.md

@@ -0,0 +1,40 @@
+# Presets
+
+Each preset pairs a brand and a structure that share its id. `pikku ui theme list` shows the
+**listed** ones; **hidden** ones are left out of the list (they are niche or loud) but
+`pikku ui theme apply --preset <id>` and `--structure <id>` still accept them. The scheme column is
+the structure's `defaultColorScheme`; trust it over any "Dark." in a preset's description text.
+
+| id | list | scheme | radius | heading / body | primary | suits |
+| --- | --- | --- | --- | --- | --- | --- |
+| `aurora` | listed | light | lg | Sora / Inter | `#6366f1` | saas, startup, dashboard, b2b, ai |
+| `linear` | listed | light | sm | Inter | `#6366f1` | productivity, issues, dev-tools, internal tools |
+| `glass` | listed | light | lg | Inter | `#38bdf8` | dashboard, analytics, fintech, premium |
+| `breeze` | listed | light | xl | Nunito | `#14b8a6` | health, wellness, booking, clinic, fitness |
+| `monopro` | listed | light | sm | Inter | `#3b82f6` | admin, console, internal tools, CRM, enterprise |
+| `quorum` | listed | light | sm | Source Serif 4 / Public Sans | `#2E6F54` | finance, tax, legal, accounting, civic |
+| `storybook` | listed | light | xl | Baloo 2 / Lora | `#6B4E8F` | kids, stories, bedtime, family (page `#FBF5EA`) |
+| `stillness` | listed | light | lg | Spectral / Karla | `#5E7C74` | meditation, journal, sleep, habit (page `#F5F2EB`) |
+| `terminal` | listed | dark | 0 | JetBrains Mono | `#22c55e` | dev-tools, CLI, logs, monitoring |
+| `blueprint` | listed | dark | xs | Space Mono / Inter | `#38bdf8` | engineering, data, IoT, infrastructure |
+| `brutalist` | hidden | light | 0 | Space Grotesk / Inter | `#f59e0b` | marketing, agency, portfolio, landing |
+| `pop` | hidden | light | md | Poppins / Inter | `#ef4444` | campaign, sports, social, community |
+| `editorial` | hidden | light | xs | Merriweather / Inter | `#b91c1c` | blog, news, magazine, docs |
+| `neon` | hidden | dark | md | Sora / Inter | `#a855f7` | gaming, nightlife, music, events |
+| `matrix` | hidden | dark | 0 | JetBrains Mono | `#22c55e` | dev-tools, security, monitoring |
+
+## What a structure carries
+
+| Lever | Key | Effect |
+| --- | --- | --- |
+| Shadow scale | `shadows.xs`..`xl` | diffuse, hard-offset or glow; the biggest "bespoke" signal |
+| Radius | `defaultRadius`, per-component `radius` | square (brutalist, terminal) to pill (breeze, storybook) |
+| Borders | per-component `defaultProps.withBorder` / `styles.root` | hairline, thick, dashed, glow |
+| Density | `spacing` | compact (monopro) to very wide (stillness) |
+| Component defaults | `components.<Name>.defaultProps` | e.g. `Button` `variant: 'gradient'`, `Card` `shadow: 'md'` |
+| Scheme | `defaultColorScheme` | light-first or dark-first boot |
+| Dark ramp | `darkColors` | exact dark background (true black, deep navy, purple-black) |
+| Page and ink | `white`, `black` | light-mode page material and text colour |
+| Gradient | `defaultGradient` | on-brand `variant="gradient"`; derived from primary and secondary |
+
+Fonts must be Google Fonts families; the theme package loads them through `googleFontsHref`.

package/skills/pikku-ui/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: pikku-ui
+description: >-
+  How a screen gets made: it is delegated to a subagent, which is handed the project's design rules and designs it with the impeccable skill.
+  TRIGGER when: the user asks for a screen, page, view, form, dashboard or empty/error state, or asks for an existing screen to be redone or restyled.
+  DO NOT TRIGGER when: the change is backend only, copy only (use pikku-i18n), or a one-line fix to a screen that already looks right.
+installGroups: [client]
+---
+
+# Screens go to a subagent
+
+A screen the main thread draws by hand comes out generic and gets rejected. Every request for
+a screen is handed to a subagent that is told the rules and designs with `impeccable`.
+
+## Steps
+
+1. Find the design rules for this project: `DESIGN.md` and the UI section of `AGENTS.md` at the
+   repo root, and the shared component package the screens are built from. If a project has
+   none, say so and stop. Do not invent a look.
+2. Start one subagent per screen. Its prompt must contain:
+   - the screen and its route or file, and the content it has to show or do;
+   - an instruction to read `DESIGN.md` in full and the UI section of `AGENTS.md` before drawing;
+   - an instruction to build only from the shared components, and to copy the closest existing screen;
+   - an instruction to invoke the `impeccable` skill and run its design workflow before writing code,
+     with the output landing in the existing theme tokens and variants, never new styles;
+   - who the audience is, and that jargon is a defect;
+   - the checks to run (typecheck), and how to commit (path-scoped, never sweep other work in).
+3. A redesign refines what is there. The subagent keeps the hero, imagery, illustrations, copy tone
+   and composition unless the user named one of them as the problem. Fewer controls and more feeling is
+   the direction; never trade a hero or images for forms, toggles and buttons. The prompt must list what
+   must not change and quote the user's actual complaint. A result with less visual character than the
+   original is a failure. If it is not clear what is wrong, ask the user before starting.
+4. Do not draw or restyle the screen in the main thread, even for a small screen.
+5. When the subagent reports, look at the screen before telling the user it is done (one render or DOM
+   check; `pikku ui pages list` names the route and `pikku ui pages screenshot --base-url <url>` photographs it). Check that it did what it was told. If it only loaded `impeccable`
+   and skipped its workflow, send it back. Tell the user what changed and what it decided.
+
+## What stays in the main thread
+
+Wiring: routes, data hooks, state, redirects, and what a screen should contain. The subagent owns
+how it looks.

package/skills/pikku-wiring/SKILL.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/skills/pikku-workflow/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: pikku-workflow
 description: >-
-  Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku.
-  Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
-  TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows,
-  multi-step processes, durable execution, suspend/resume, or DAG orchestration. DO NOT TRIGGER
-  when: user asks about simple background jobs (use pikku-wiring) or scheduled tasks (use
-  pikku-wiring).
+  Use when building multi-step, durable workflows with Pikku — pikkuWorkflowFunc,
+  pikkuWorkflowGraph, workflow.do / sleep / suspend / approval, retries, compensate, sub-workflows,
+  and starting or resuming runs. Includes deciding whether something should be a workflow at all.
+  TRIGGER when: code uses pikkuWorkflowFunc or pikkuWorkflowGraph, or the user asks about
+  workflows, multi-step processes, durable execution, suspend/resume, approval gates, sagas or DAG
+  orchestration. DO NOT TRIGGER when: the user wants a single background job (use the queue
+  reference in pikku-wiring) or a cron task (use the scheduler reference in pikku-wiring), or is
+  converting an n8n export (use pikku-n8n-import).
 installGroups: [core]
 ---
 
@@ -282,7 +284,7 @@ compensated. The error arrives as `wire.graph.recoveringFrom`
 object (`{ success: false, reason }`) instead.
 
 Full step options: `description`, `retries`, `retryDelay`, `compensate: false`
-(plus `actor`, which is scenario-only — see `pikku-scenario`).
+(plus `virtualUser`, which is scenario-only — see `pikku-scenario`).
 
 ### Parallel fan-out
 

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

@@ -1,212 +0,0 @@
----
-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).'
-installGroups: [fabric]
-argument-hint: '<path to .knowledge/> [resource to port next]'
----
-
-# Legacy admin → Fabric admin screens
-
-## Agent 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.
-3. **Port the actions before the screens.** A screen with no action behind it is a table; the actions are the product.
-4. **One resource per slice**, same as `pikku-blueprint-to-fabric`. Verify green before the next.
-5. **An admin permission is not a checkbox.** Legacy admins routinely authenticate and do not authorize. Do not port that.
-6. **Record what you did NOT port**, per resource, in the parity report.
-
-## The mistake this skill exists to prevent
-
-> "It's just the admin — CRUD screens over the same tables. We'll scaffold it at the end."
-
-This is wrong in a specific, measurable way, and you can check it in one command
-before you believe anything else in this file:
-
-```bash
-node -e "
-const c = require('./.knowledge/commands.json').commands
-const admin = c.filter(x => (x.evidence||[]).some(e => (e.file||'').match(/admin/)))
-console.log(admin.length + ' of ' + c.length + ' commands live in the admin')
-"
-```
-
-On a real Rails app (Applause, 39 ActiveAdmin resources, 5,545 lines of DSL) the
-answer was **82 of 187 — 44%**, plus 71 of 223 API surfaces. The admin was not a
-side panel over the customer-facing app. It was nearly **half the application's
-write surface**, and a large share of those commands existed *nowhere else*:
-issue a refund, retrigger a payment, queue a sync, impersonate a user, mark a
-blade returned, reassign a company. There is no customer screen for any of them.
-
-So: the admin is not the last 10% of the port. Budget it as what the count says.
-
-**Corollary — the admin is where the unguarded capabilities live.** A
-`member_action :impersonate` or `:create_stripe_refund` is a command that moves
-money or identity, defended in legacy by nothing more than "you reached an
-`/admin` URL". Every one of these needs a real `pikkuPermission` in the rebuild,
-and writing them is the point of the port, not overhead on top of it.
-
-## Stage 0 — Preflight
-
-- The `.knowledge/` blueprint must exist and validate (`0 error(s)`). If not, run
-  **pikku-software-archaeology** first. This skill maps to the blueprint; it does
-  not parse Ruby.
-- Read `parity-*.md` for the domains you are about to touch. Renames decided in an
-  earlier slice (a `tenant` that became a `Market`, a `membership_level` that
-  became a `certification_level`) are binding here. An admin screen that reintroduces
-  the old word undoes the decision.
-- Run the count above and say the number out loud in your plan.
-
-## Stage 1 — Inventory the DSL
-
-Every generated admin is the same six ideas under different syntax. Inventory
-them, do not read them line by line:
-
-```bash
-# ActiveAdmin
-grep -rhoE "^\s{0,4}(index|show|form|filter|scope|action_item|member_action|collection_action|batch_action|permit_params|csv|sidebar|panel|actions)\b" app/admin/*.rb | sort | uniq -c | sort -rn
-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 |
-| `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 |
-| `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 |
-| `batch_action` | admin action | a `pikkuFunc` taking ids[] |
-| `csv do … end` | export | a readonly func returning rows; render client-side |
-| `panel`/`sidebar` | inlines, `relations` | a section on the show screen, fed by a related query |
-| `action_item` | — | a button. It is not a capability; find the action it calls. |
-
-**`action_item` vs `member_action` is the distinction that matters.** An
-`action_item` is a *button*; a `member_action` is a *capability*. Legacy files
-pair them, and a fast reader counts the buttons. Count the capabilities.
-
-## Stage 2 — Map actions to blueprint commands (do this before any UI)
-
-For each `member_action`/`collection_action`, find its command in
-`commands.json`. Three outcomes, and the third is the valuable one:
-
-1. **Found** — the archaeology already lifted it (`ArchiveProduct`,
-   `CancelInvoice`). Wire the screen to it. Nothing to build.
-2. **Found under a different name** — the blueprint names concepts in domain
-   language, the DSL names them after routes. `member_action :rerun` may be
-   `RetryWebhookDelivery`. Match on behaviour, not spelling. **Use the blueprint's
-   name.**
-3. **Not found** — stop. Either the archaeology missed a command (fix
-   `.knowledge/`, do not paper over it here) or the action is dead code. Both are
-   findings. Do not quietly invent a command to fill the gap: a command with no
-   blueprint entry has no evidence, no policy and no actor, and you will not
-   notice which.
-
-Two legacy shapes to expect and *not* reproduce:
-
-- **`*_form` + `*` action pairs** (`create_stripe_refund_form` +
-  `create_stripe_refund`, `issue_payment_form` + `issue_payment`). The `_form` half
-  is a GET that renders a modal — it is a *screen*, not a capability. It collapses
-  into the screen; only the second half is a `pikkuFunc`. Porting both doubles your
-  command count with phantoms.
-- **A `member_action` that only redirects** to another action. That is routing.
-- **An action disabled in the production environment is not a live capability.**
-  Grep the environment guards before porting:
-  ```bash
-  grep -rn "env.production?\|env\.development?\|ENV\[" app/admin/*.rb
-  ```
-  On Applause, both halves of `create_stripe_refund` open with
-  `return redirect_to … if Rails.env.production?` — the admin refund screen has
-  never run in production, and refunds are actually issued in the Stripe dashboard.
-  Porting it faithfully would ship a prominent button for a capability the business
-  does not use through this app, and quietly move refunds into a surface nobody has
-  ever tested. Whether it should now exist is a **product decision**, not a port.
-  Check the guard is on the *mutating* half too: if the form is blocked and the POST
-  is not, you have found a hole rather than a dead feature.
-
-## Stage 3 — Permissions (the part legacy skipped)
-
-Generated admins authenticate and then trust. The whole admin sits behind one
-"is an admin" check, and every action inside it is equally reachable — refunds,
-impersonation and editing an FAQ all guarded identically.
-
-- Read `policies.json` for the real rule per command. If the blueprint says the
-  policy is `enforcedBy: nothing`, that is a **gap you are now closing**, not a
-  behaviour to port.
-- With Better Auth's `admin()` plugin, `user.role` is the platform role and
-  `session.impersonated_by` is set during impersonation. Both are yours already.
-- **Money and identity actions deserve their own permission**, not the blanket one.
-  If the blueprint offers no rule, that is a `decisionsNeeded` entry — ask, do not
-  invent.
-- **Impersonation:** Better Auth's `impersonateUser`/`stopImpersonating` replace the
-  hand-rolled version. If the legacy audit table recorded only the *start* of an
-  impersonation (no `ended_at`, no session id), do not port it — the Fabric audit
-  table already answers "what did they do while impersonating", which was the whole
-  question it failed to answer.
-
-## Stage 4 — Screens
-
-- The list query is `pikkuSessionlessFunc` + `readonly: true`; filters and scopes
-  are **input fields on one function**, not one function per scope. Legacy needs a
-  method per scope because the DSL has no parameters. You do not.
-- 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
-  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
-  one genuinely expensive screen in most admins — cost it separately.
-- **Drag-and-drop reordering** (`acts_as_list`, sortable tables) is custom logic,
-  not a table. Port the position semantics deliberately.
-
-## Stage 5 — Verify and report
-
-```bash
-pikku all && pikku fabric validate --json
-```
-
-Per resource, the parity report records:
-
-- **Ported** — screens + which blueprint commands back them.
-- **Deliberately not ported** — with the reason. Expect: `*_form` halves, dead
-  actions, single-member enums, screens over dropped tables.
-- **Now authorized** — every action that was guarded by "reached an /admin URL"
-  and now has a real permission. This is the port's dividend; name it.
-- **Still open** — actions whose rule the blueprint could not settle.
-
-## Red Flags
-
-| Thought | Reality |
-|---|---|
-| "The admin is just CRUD, scaffold it last" | Run the count. It was 44% of commands on a real app, and those commands exist nowhere else. |
-| "I'll read the DSL and write the commands" | The blueprint already has them, with evidence, actors and policies. Map; don't re-derive. |
-| "One function per scope" | A scope is a filter argument. The DSL needed a method because it has no parameters. |
-| "`action_item` count = capability count" | Buttons aren't capabilities. Count `member_action`/`collection_action`. |
-| "Port `create_stripe_refund_form` too" | It is a GET that renders a modal. It is a screen. Only the non-`_form` half is a command. |
-| "Admins are admins; one permission is fine" | That is the legacy bug. Refunds and FAQ edits are not the same risk. |
-| "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.