@pikku/skills 0.12.9 → 0.12.11

package/skills/pikku-build-quick/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: pikku-build-quick
+description: >-
+  Build a working app on open-source Pikku fast — scaffold to running screens, skipping the
+  knowledge base and the milestone ladder. For spikes, throwaway demos, and ideas nobody has
+  committed to yet. TRIGGER when: the user asked for something quick, a prototype, a spike, a
+  demo of an idea, or "just get it running", or picked "Quick" from the build-mode question. DO
+  NOT TRIGGER when: the request is an unqualified "build me an X on Pikku" with no signal of
+  speed or throwaway-ness — App is the default and small or toy-sounding apps do not change that
+  (use pikku-build-app); the user wants a real product someone else will pick up (use
+  pikku-build-app); the user wants a demo of Pikku itself — one that shows off surfaces like
+  workflows, queues, realtime or i18n (use pikku-build-platform); or the user is adding a feature
+  to an app that already exists rather than building one from a fresh scaffold (use
+  pikku-feature).
+installGroups: [core]
+---
+
+# Build an app on Pikku, fast
+
+You have a scaffolded project with skills installed. Get it to working, seeded,
+signed-in screens in as few steps as possible.
+
+**What this mode deliberately skips**, and what that costs:
+
+| Skipped | Cost |
+|---|---|
+| `knowledge/` | Another agent — or you next week — cannot resume this. Nothing records *why*. |
+| Milestone planning | No build order, no per-piece proof. Fine at this size, painful past it. |
+| Design direction | It will look like the template. |
+| Refusal scenarios | Access control is asserted, not proven. |
+
+**Say this out loud to the user, once, when you finish.** A quick build that gets
+mistaken for a real one is the only way this mode does damage. §6 is the way out.
+
+## Agent Operating Procedure
+
+1. Read `AGENTS.md` at the project root before your first screen — routing slots,
+   `useNavItems()`, and the shipped component kit.
+2. Keep generated files generated. Never hand-edit `.pikku/`, `*.gen.*`, or the SDK.
+3. Run `pikku all` after touching functions, wirings or schemas. It is the gate,
+   and its criticals are real.
+
+## 1. One question, then build
+
+Ask **one** thing, and only if the original request left it open: **who uses
+it — one kind of person, or several?** Everything else you decide yourself.
+
+- **One kind** — no roles to declare. The rule is ownership: you see yours, not
+  theirs.
+- **Several** — declare a role each in §2 and keep the count honest. An invented
+  role becomes invented screens.
+
+Do not ask about design, deployment, or scope. This is the quick mode; the
+defaults are the point.
+
+## 2. Personas — 60 seconds, not optional
+
+`packages/functions/src/personas.ts` ships with a `visitor`. Add one persona per
+kind of person, plus **a second one of the primary kind** — that is what makes
+"you see yours, not theirs" observable when you click around.
+
+**One kind of person** — no `defineSystemRole` at all. Ownership is the only
+rule, and it lives in each function's `permissions`, not in a role:
+
+```typescript
+import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+
+definePersonas({
+  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+  amina: { name: 'Amina', jobTitle: 'Gardener', account: {} },
+  bilal: { name: 'Bilal', jobTitle: 'Gardener', account: {} },
+})
+```
+
+**Several kinds** — one role each, and only for the kinds the user actually
+named:
+
+```typescript
+import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+import { defineSystemRole } from '#pikku'
+
+defineSystemRole({
+  owner: { displayName: 'Owner', description: 'Sees only their own rows', scopes: [] },
+  tenant: { displayName: 'Tenant', description: 'Sees only their own tenancy', scopes: [] },
+})
+
+definePersonas({
+  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+  amina: { name: 'Amina', jobTitle: 'Owner', roles: ['owner'], account: {} },
+  bilal: { name: 'Bilal', jobTitle: 'Owner', roles: ['owner'], account: {} },
+  chidi: { name: 'Chidi', jobTitle: 'Tenant', roles: ['tenant'], account: {} },
+})
+```
+
+Two owners in both examples, deliberately: one owner cannot demonstrate that
+owners are separated from each other.
+
+- **Keep `visitor`.** The shipped scenarios name `actors.visitor`; removing it
+  fails `pikku all` and nothing you write after that registers.
+- **One `definePersonas` call for the whole project.**
+- **Never write an email address** — each is derived from the persona id and
+  `scenarios.emailDomain` in `pikku.config.json`.
+- `roles` is typechecked against `defineSystemRole`; an undeclared role is a
+  build error.
+
+## 3. Build
+
+Run `bunx --bun pikku bootstrap` once first. It wires the `#pikku` import alias
+codegen depends on; without it your first `db migrate` fails with
+`Cannot find package '#pikku'`.
+
+Then, in this order — it is the order codegen depends on:
+
+1. **Migration** — SQL in `db/sqlite/`, numbered on from what is there. Apply
+   with `bunx --bun pikku db migrate`, which regenerates the Kysely types.
+2. **Seed** — rows in `db/sqlite-dev-seed.sql`. There is no seed command:
+   `bunx --bun pikku db reset` wipes, migrates and seeds in one go, and is the
+   only thing that applies the file. It always starts from a wiped database, so
+   the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. **Be generous, and
+   seed rows for both personas.** An empty app demos badly, and you cannot see a
+   layout break against zero rows.
+3. **Functions** — one `pikkuFunc` per `*.function.ts`, `expose: true`. Pikku
+   generates the typed RPC client and React Query hooks; you do NOT write HTTP
+   routes. `wireHTTP` only for a real REST shape (a third-party webhook).
+4. `bunx --bun pikku all`
+5. **UI** — pages in `apps/app/src/pages/`, one route file each in
+   `apps/app/src/routes/`, calling `usePikkuQuery` / `usePikkuMutation` from
+   `@project/functions-sdk/pikku/api.gen`. Compose `@/components/<Name>` —
+   `PageHeader`, `Panel`, `StatGrid`, `DataTable` — rather than hand-rolling.
+   Register each screen in `useNavItems()`; that one file feeds the desktop
+   sidebar and the phone navigation.
+
+**Aim for two or three real entities and three screens** — a working surface, a
+detail view, and somewhere to land. One table with a form on it is not an app,
+and it is not faster to build.
+
+Rules that stay non-negotiable even here, because breaking them costs more time
+than they save:
+
+- Input and output types come from `input:`/`output:` zod schemas. Never generic
+  type params, never an inline return type. The schema is the type.
+- Permission checks go in the `permissions` field, never the function body. An
+  exposed function with no session and no permission is reachable by anyone over
+  `POST /rpc/:rpcName` (PKU574).
+- No `process.env` inside a function — use the injected `variables` / `secrets`
+  services.
+- A `z.date()` **input** arrives over RPC as an ISO string, not a `Date`.
+  `new Date(value)` before calling date methods, or it throws
+  `.getTime is not a function` at runtime.
+- On SQLite, `db/annotations.ts` is where a `DATETIME` becomes a `Date` and a
+  `JSON` column becomes a typed object. Without an entry they are `string` and
+  `unknown` (PKU481). Add the annotation rather than casting.
+- Surface errors inline next to the control that failed. No empty catch.
+- Every user-facing string is a translation key, not a literal. It is one extra
+  keystroke now and a rewrite later.
+- Never hardcode a host or port — the API base resolves to same-origin `/api`.
+
+Then run it:
+
+```sh
+bun run prebuild && bun run dev
+```
+
+API on :3000, app on the port vite prints. A frontend against a dead API looks
+exactly like an app bug, so if every request fails, check both came up.
+
+## 4. Look at it — actually
+
+Sign up, click every screen. **HTTP 200 is not evidence:** pages are
+client-rendered, so the server returns 200 with an empty shell and a page whose
+component throws still looks fine to `curl`. Open a browser, or drive it
+headlessly and assert on rendered text.
+
+**Screenshot at 390px too.** A layout that is fine at 1440 routinely breaks on a
+phone — an overflowing table, a row of buttons wrapped into a pile, a modal
+taller than the viewport. It is the most likely width your demo gets opened at.
+
+If you have five spare minutes, `npx impeccable install` (Node 22.18+) scores
+each screen against interaction heuristics and names what is wrong. Feed it
+screenshots, not source. It will polish the default look; it will not give the
+app a look — that is `pikku-build-app` §8a.
+
+## 5. One smoke scenario
+
+Not the full ladder — one journey, end to end, as a real persona, so the app has
+at least one thing that stays true.
+
+```typescript
+import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+
+export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>({
+  title: 'An owner creates a thing and sees it',
+  tags: ['scenario', 'smoke'],
+  func: async (_services, _data, { scenario, actors }) => {
+    const row = await scenario.do('creates', 'createThing', { name: 'first' }, { actor: actors.amina })
+    await scenario.then('sees it listed', 'thingShowsInList', { id: row.id }, { actor: actors.amina })
+    return { id: row.id }
+  },
+})
+```
+
+- **`do` takes an RPC name; `given`/`when`/`then` take a declared
+  `pikkuScenarioStep`.** An RPC name in a `then` will not resolve.
+- **Every scenario must assert.** A ladder with no `then` is a PKU680 critical —
+  it fails `pikku all`, stopping codegen rather than a test.
+- **Add `SCENARIO_ACTOR_SECRET` to `.env`.** `bun run dev` writes that file with
+  only a `BETTER_AUTH_SECRET`; without the actor secret
+  `/api/auth/sign-in/actor` is disabled and every scenario fails at sign-in, for
+  a reason that reads like an auth bug.
+- **There is no state reset** — scope what you create to unique ids.
+
+Keep the three shipped scenarios in `packages/functions/test/scenarios/` green.
+
+```sh
+bunx --bun pikku scenario run local --spawn
+```
+
+## 6. Hand it over honestly
+
+Tell the user, in one short paragraph: what runs, what it is seeded with, and
+that this is a quick build — no knowledge base, no milestones, no design pass,
+access control clicked-through rather than proven.
+
+**Upgrading to a real build is additive, not a rewrite.** If they want it, switch
+to `pikku-build-app` and do this, in order:
+
+1. Write `knowledge/` for what already exists — `entities/` for what you built,
+   `decisions/` for what you chose silently, `questions/` for what you guessed
+   at. Then `pikku knowledge index && pikku knowledge validate`.
+2. Backfill a milestone note per screen you built, at `status: built`, each with
+   its gherkin block.
+3. Write the refusal scenarios — the ones proving one persona cannot reach
+   another's rows. This is the gap that matters most.
+4. Then pick up `pikku-build-app` at its §4 (apps) or §5 (milestones) for
+   anything new.
+
+Nothing built here has to be thrown away to do that — which is the whole reason
+this mode is allowed to skip those steps in the first place.

package/skills/pikku-cli/SKILL.md

@@ -41,7 +41,7 @@ All three factories come from `#pikku` (the generated types re-export
 loses your project's service and middleware types.
 
 ```typescript
-import { wireCLI } from '#pikku'
+import { wireCLI } from '#pikku/cli'
 
 wireCLI({
   program: string,              // Program name (e.g. 'todos')
@@ -65,7 +65,7 @@ wireCLI({
 ### `pikkuCLICommand(config)`
 
 ```typescript
-import { pikkuCLICommand } from '#pikku'
+import { pikkuCLICommand } from '#pikku/cli'
 
 pikkuCLICommand({
   parameters?: string,          // Positional args (e.g. '<text>', '<username> <email>')
@@ -111,7 +111,7 @@ How the parser reads them, which is worth knowing before you name one:
 ### `pikkuCLIRender(fn)`
 
 ```typescript
-import { pikkuCLIRender } from '#pikku'
+import { pikkuCLIRender } from '#pikku/cli'
 
 const renderer = pikkuCLIRender<OutputType>((services, data) => {
   // Format and print output to terminal
@@ -122,10 +122,10 @@ const renderer = pikkuCLIRender<OutputType>((services, data) => {
 ### Wire object (`wire.cli`)
 
 ```typescript
-wire.cli.program   // program name
-wire.cli.command   // string[] — the resolved command path
-wire.cli.data      // all positionals and options, merged
-wire.cli.channel   // the channel when served remotely (see below)
+wire.cli.program // program name
+wire.cli.command // string[] — the resolved command path
+wire.cli.data // all positionals and options, merged
+wire.cli.channel // the channel when served remotely (see below)
 ```
 
 ## Usage Patterns

package/skills/pikku-cli/references/complete-example.md

@@ -32,7 +32,7 @@ export const deleteUser = pikkuFunc({
 })
 
 // wirings/cli.wiring.ts
-import { wireCLI, pikkuCLICommand, pikkuCLIRender } from '#pikku'
+import { wireCLI, pikkuCLICommand, pikkuCLIRender } from '#pikku/cli'
 
 const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
   console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)

package/skills/pikku-concepts/SKILL.md

@@ -27,7 +27,7 @@ Pikku is a TypeScript framework that separates business logic from transport mec
 
 For deep-dive on each topic, see the dedicated skills:
 
-- **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-ai-agent`, `pikku-workflow`
+- **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-agent`, `pikku-workflow`
 - **Authorization**: `pikku-security` (authentication/sessions), `pikku-permissions` (permission checks, scopes), `pikku-middleware` (global/tag/route middleware)
 - **Infrastructure**: `pikku-services`, `pikku-config`
 - **Project introspection**: `pikku-info`
@@ -44,7 +44,7 @@ pikkuFunc (pure business logic)
     ├── wireMCPTool     → Model Context Protocol (AI tools)
     ├── wireCLI         → CLI commands
     ├── wireTrigger     → Event-driven (Redis pub/sub, PG LISTEN/NOTIFY)
-    ├── pikkuAIAgent    → AI agents / chatbots
+    ├── pikkuAgent    → AI agents / chatbots
     ├── pikkuWorkflow   → Multi-step durable workflows
     └── wire.rpc        → Internal function-to-function calls
 ```
@@ -122,7 +122,7 @@ pikkuFunc({
   permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
   middleware?: PikkuMiddleware[], // See pikku-middleware
 
-  // Agent tooling — see pikku-ai-agent
+  // Agent tooling — see pikku-agent
   approvalRequired?: boolean,
   approvalDescription?: (services, data) => Promise<string>,
 
@@ -144,7 +144,7 @@ reject every caller it exists to serve. Gate those with `permissions`, which
 receive the optional session and may pass anonymous.
 
 **Generics XOR `input`/`output` — never both.** A function's data and return
-types come from *one* source: either the `input`/`output` schemas (preferred —
+types come from _one_ source: either the `input`/`output` schemas (preferred —
 they double as runtime validation and OpenAPI) or type generics
 (`pikkuFunc<In, Out>({ ... })`). Passing both makes the two disagree and forces
 `as any` casts. Do not annotate the `func` return type inline either — let the
@@ -230,13 +230,15 @@ await server.start()
 
 **Lifecycle hooks do not run on this path** — only `pikku dev` and `pikku serve` invoke them. Do your startup work directly in the entrypoint instead.
 
-`pikku validate` warns when a project starts a server by hand *and* depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
+`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter, since that combination means path 1 was available and unused. Silence it with `"lint": { "customServerBootstrap": "off" }` in `pikku.config.json`.
 
 ## Code Generation
 
 Run `npx pikku all` to generate:
 
-- `pikku-types.gen.ts` — Typed function factories and wiring functions
+- one directory per wiring (`function/`, `http/`, `workflow/`, …), each with an
+  `index.ts` reached as `#pikku/<name>` — typed function factories and wiring
+  functions, split so an app pulls in only the wirings it uses
 - `pikku-fetch.gen.ts` — Type-safe HTTP client
 - `pikku-websocket.gen.ts` — Type-safe WebSocket client
 - `pikku-bootstrap.gen.ts` — Runtime initialization (auto-imports all wirings)
@@ -271,7 +273,8 @@ src/
 ├── middleware.ts         # Middleware definitions (see pikku-security)
 ├── permissions.ts       # Permission definitions (see pikku-security)
 └── .pikku/              # Generated (gitignored)
-    ├── pikku-types.gen.ts
+    ├── function/        # #pikku/function
+    ├── http/            # #pikku/http
     ├── pikku-fetch.gen.ts
     └── pikku-bootstrap.gen.ts
 ```

package/skills/pikku-concepts/references/concept-mapping.md

@@ -472,7 +472,7 @@ if (!canEdit(user, todo)) {
 **Pikku:**
 
 ```typescript
-import { NotFoundError, ForbiddenError } from '@pikku/core/errors'
+import { NotFoundError, ForbiddenError } from '#pikku/error'
 
 const updateTodo = pikkuFunc(async (services, { id, title }, wire) => {
   const todo = services.todoStore.getTodo(id)

package/skills/pikku-config/SKILL.md

@@ -75,7 +75,9 @@ greppable. Call it at the point the value reaches the thing that needs it:
 ```typescript
 // services.ts — allowed
 const createSingletonServices = pikkuServices(async (config, { secrets }) => ({
-  stripe: new StripeService((await secrets.getSecret('STRIPE_CONFIG')).reveal()),
+  stripe: new StripeService(
+    (await secrets.getSecret('STRIPE_CONFIG')).reveal()
+  ),
 }))
 
 // functions/*.ts — ask the service, never the secret store
@@ -162,7 +164,7 @@ defineCredential({
 
 ### Usage
 
-```typescript
+````typescript
 // Per-user API key — no oauth2 block
 defineCredential({
   name: 'stripe',
@@ -208,7 +210,7 @@ export const createWireServices = pikkuWireServices(async (_services, wire) => {
 export const postMessage = pikkuFunc({
   func: async ({ slack }, { channel, text }) => slack.postMessage(channel, text),
 })
-```
+````
 
 A `wire` credential resolves per user, so an unconnected user hits
 `MissingCredentialError` rather than silently acting as someone else; a

package/skills/pikku-deploy-azure/SKILL.md

@@ -59,10 +59,11 @@ import { createAzureHandler } from '@pikku/azure-functions'
 import { createConfig, createSingletonServices } from './services.js'
 import './.pikku/pikku-bootstrap.gen.js'
 
-const handlers = createAzureHandler(
-  { createConfig, createSingletonServices },
-  ['fetch', 'queue', 'scheduled']
-)
+const handlers = createAzureHandler({ createConfig, createSingletonServices }, [
+  'fetch',
+  'queue',
+  'scheduled',
+])
 
 app.http('api', {
   methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],

package/skills/pikku-deploy-cloudflare/SKILL.md

@@ -42,14 +42,14 @@ export default createCloudflareHandler(
 )
 ```
 
-| Factory | For |
-| --- | --- |
-| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled` |
-| `createCloudflareWorkerHandler(factories)` | HTTP / agent / RPC / workflow-orchestrator units |
-| `createCloudflareCronHandler(factories)` | cron units |
-| `createCloudflareQueueHandler(factories)` | queue-consumer and workflow-step units |
-| `createCloudflareMCPHandler(factories)` | MCP units (same HTTP transport) |
-| `createCloudflareWebSocketHandler(factories)` | channel units, delegating to the DO |
+| Factory                                            | For                                              |
+| -------------------------------------------------- | ------------------------------------------------ |
+| `createCloudflareHandler(factories, handlerTypes)` | combined `fetch`/`queue`/`scheduled`             |
+| `createCloudflareWorkerHandler(factories)`         | HTTP / agent / RPC / workflow-orchestrator units |
+| `createCloudflareCronHandler(factories)`           | cron units                                       |
+| `createCloudflareQueueHandler(factories)`          | queue-consumer and workflow-step units           |
+| `createCloudflareMCPHandler(factories)`            | MCP units (same HTTP transport)                  |
+| `createCloudflareWebSocketHandler(factories)`      | channel units, delegating to the DO              |
 
 `factories` is `{ createConfig, createSingletonServices, createPlatformServices? }`.
 
@@ -71,7 +71,7 @@ const services = await setupServices(env, {
 **Do not hand-roll this.** Beyond building `LocalVariablesService` /
 `LocalSecretService` and caching the result, it calls `setSingletonServices()` —
 and the core runners (`fetchData`, `runQueueJob`, `runScheduled`) resolve
-services through that global slot, *not* through the value you were returned. A
+services through that global slot, _not_ through the value you were returned. A
 setup function that only returns the services leaves every request throwing
 "Singleton services not initialized" as a CF `1101`. It also stashes the env via
 `setCloudflareEnv`, which `getCloudflareEnv()` reads for bindings.

package/skills/pikku-deploy-uws/SKILL.md

@@ -102,14 +102,17 @@ yarn add @pikku/ws
 ```
 
 ```typescript
-import { pikkuWebsocketHandler } from '@pikku/ws'
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
 import { stopSingletonServices } from '@pikku/core'
 import { Server } from 'http'
 import { WebSocketServer } from 'ws'
 import './.pikku/pikku-bootstrap.gen.js'
 
 const server = new Server()
-const wss = new WebSocketServer({ noServer: true })
+const wss = new WebSocketServer({
+  noServer: true,
+  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+})
 
 pikkuWebsocketHandler({
   server,

package/skills/pikku-deps/SKILL.md

@@ -4,8 +4,11 @@ description: >-
   Use for the Pikku dependency security audit: the `pikku audit` CLI command, the
   `.pikku/audit.json` artifact, the `SecurityAuditReport` type in @pikku/core, and the console
   Security screen (getSecurityAudit / runSecurityAudit / updateDependency + SecurityAuditView).
-  TRIGGER when: user asks about `pikku audit`, dependency vulnerabilities/advisories, outdated
-  dependencies, the Security screen/page in the console, updating a vulnerable dependency, or
+  Also covers `pikku update`, which moves the @pikku/* dependency set forward and reports the
+  peers those versions need.
+  TRIGGER when: user asks about `pikku audit` or `pikku update`, dependency
+  vulnerabilities/advisories, outdated dependencies, upgrading Pikku itself, peer dependency
+  conflicts, the Security screen/page in the console, updating a vulnerable dependency, or
   reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT
   (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use
   pikku-config).
@@ -43,11 +46,47 @@ installGroups: [core]
   `bun outdated`, normalised into one `SecurityAuditReport` with per-severity /
   per-update-level counts). Other PMs are detected but **stubbed** with a `note`
   field until their shapes are normalised — issues/updates come back empty.
-- `bun audit` exits non-zero when it *finds* advisories but still writes the
+- `bun audit` exits non-zero when it _finds_ advisories but still writes the
   payload to stdout, so a non-zero exit **with output** is data. A non-zero exit
   with **no** output — or a launch failure, timeout, or a blown 32MB buffer —
   throws, precisely so a failed run can't masquerade as "0 advisories".
 
+## The `pikku update` command
+
+Narrower than `audit --outdated`, and the only one that writes: it moves the
+**@pikku/\* set** forward and reports the peers those versions need. Use `audit`
+to learn a dependency is vulnerable; use `update` to move Pikku itself.
+
+- `pikku update` — reports only. Nothing is written without `--update`.
+- `pikku update --update` — writes the new ranges into every covered
+  package.json, then runs an install. `--no-install` writes and stops.
+- `pikku update --update-peers` — implies `--update` and additionally writes the
+  ranges unsatisfied peers require, **for peers the project already declares**.
+  A peer it does not declare is reported and never added — adding a dependency
+  is not an update. Separate from `--update` because a peer bump can cross a
+  **major** of a third-party package (`ai` 5 → 6), which is not a call to make
+  on the user's behalf.
+- `--tag <dist-tag>` (default `latest`) reads each package's own dist-tag, so
+  `--tag next` moves the whole set onto prereleases. `--registry <url>` defaults
+  to `npm_config_registry`.
+- Coverage is the nearest package.json walking up from the project root, plus
+  every workspace it declares — a monorepo updates in one pass. All four
+  dependency fields are read, `peerDependencies` included, so an addon's own
+  declared peer range moves with it.
+
+Statuses, per dependency: `outdated` (the range floor is behind latest — this is
+what `--update` writes), `stale-install` (the range already admits latest but
+node_modules is behind — an install fixes it, no edit needed), `linked` (a
+`workspace:`/`file:`/`link:`/`portal:` range — a deliberate local checkout,
+counted but never listed), `manual` (a registry range we refuse to substitute
+into: a union, an x-range, a `*`), `unresolved` (the registry had no such tag —
+this must **never** read as "current", the same rule as a failed audit).
+
+Peers are read off the version the run **lands on**, not the one installed —
+the point is what the target needs. An @pikku peer the same run already brings
+forward is not reported, and an unsatisfied _optional_ peer the project never
+declared is skipped.
+
 ## Console integration (@pikku/addon-console)
 
 Three RPCs, all reading/writing the same artifact via the meta service. Shared

package/skills/pikku-emails/SKILL.md

@@ -36,8 +36,8 @@ generated output is never edited by hand.
 ```jsonc
 // pikku.config.json
 {
-  "emailTemplatesDir": "emails",   // relative to rootDir; omit to disable emails
-  "outDir": ".pikku"               // gen lands in <outDir>/email/
+  "emailTemplatesDir": "emails", // relative to rootDir; omit to disable emails
+  "outDir": ".pikku", // gen lands in <outDir>/email/
 }
 ```
 
@@ -121,9 +121,9 @@ render with sample data and read the result rather than trusting that it compile
 
 ```ts
 const rendered = renderEmailTemplate({
-  name: 'verify-email',        // EmailTemplateName (autocompleted)
-  locale: 'en',                // optional, defaults to 'en'
-  data: { verifyUrl: url },    // EmailTemplateVariables<'verify-email'>
+  name: 'verify-email', // EmailTemplateName (autocompleted)
+  locale: 'en', // optional, defaults to 'en'
+  data: { verifyUrl: url }, // EmailTemplateVariables<'verify-email'>
 })
 // rendered: { name, locale, subject, html, text?, variables, hash }
 ```

package/skills/pikku-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-fabric
-description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
+description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. TRIGGER when: user asks about a `pikku fabric validate` finding, including app-missing-actor-quick-login. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
 installGroups: [fabric]
 ---
 
@@ -115,7 +115,7 @@ and refuses a database outside the runtime directory. Anything a real environmen
 needs — accounts, role grants — is provisioning, not seeding, and belongs in
 `pikku persona sync` or a migration.
 
-A Better Auth app has a second constraint: the plugins you enable (`admin()`,
+A Better Auth app has a second constraint: the plugins you enable (`ban()`,
 `actor()`, …) each declare columns, and `pikku db migrate` refuses to run while
 the applied schema is missing any of them. `pikku db generate` writes the
 migration that closes the gap.
@@ -311,13 +311,37 @@ Always call the `pikku-verify` tool after modifying functions, wirings, or schem
 
 The output card shows whether any breaking changes were detected.
 
+### `app-missing-actor-quick-login-<app>`
+
+The `fabric validate` finding people most often misread. It fires when an app has
+a **login screen** but no dev actor switcher, and it is not a style nit: a sandbox
+reviewer has no seed password, so without the control they are locked out of the
+app they were asked to look at.
+
+Satisfy it with `<DevActorSwitcher />` from `@pikku/mantine/dev`, or with your
+own UI built on `useDevActors()` from `@pikku/react` — validate accepts either
+call site as evidence, so custom rendering passes. See **pikku-react** for the
+props and **pikku-scenario** for where the actor list comes from.
+
+The validator also accepts the shapes that predate the package — a hand-rolled
+`signInAsActor()` or a literal `POST /auth/sign-in/actor` — so an older app does
+not fail the build. **Treat that as a grace period, not the target: migrate those
+to `<DevActorSwitcher />`.** The hand-copied version is exactly the duplication
+the package exists to remove, and the copies drift — the ones that prompted this
+had already diverged on the `import.meta.env.DEV` gate that keeps the shared
+secret out of production bundles.
+
+Do **not** satisfy it with Better Auth's `/dev/quick-login`. That is a different
+endpoint with a different purpose — one fixed admin, not the declared personas —
+and it does not clear this rule.
+
 ## Hard rules
 
 These apply in every Fabric app:
 
 - **No `process.env`** — use `variables.get('NAME')` and `secrets.getSecret('NAME')`. Declare with `defineVariable` / `defineSecret`.
 - **No `as any`** — fix types properly.
-- **No generic `Error`** — throw `NotFoundError`, `ConflictError`, `BadRequestError`, `UnauthorizedError` from `@pikku/core/errors`.
+- **No generic `Error`** — throw `NotFoundError`, `ConflictError`, `BadRequestError`, `UnauthorizedError` from `#pikku/error`.
 - **No auth checks in function bodies** — use `permissions:` field on the function config with a `pikkuPermission` factory.
 - **No hand-editing `.pikku/db/schema.gen.ts`** — write a migration and re-run `pikku db migrate`.
 - **One runtime unit per file** — never define multiple functions/workflows in a single source file.

package/skills/pikku-fabric-debug/SKILL.md

@@ -87,7 +87,7 @@ without it, even though the flag reads as optional.
 pikku fabric status     # active + in-flight deployment, per stage, with gitSha
 ```
 
-Check this *before* deep-diving. A stage still serving an older `gitSha`, or a
+Check this _before_ deep-diving. A stage still serving an older `gitSha`, or a
 deploy stuck in flight, explains a whole class of "my fix did nothing".
 
 ## Known gaps — do not misread these as bugs in your app

package/skills/pikku-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-feature
-description: 'Drive create-a-feature work for a Pikku project: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "build a todo app", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, or asks about Pikku concepts (use pikku-concepts).'
+description: 'Drive create-a-feature work inside a Pikku project that already exists: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
 installGroups: [core]
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *)
 argument-hint: '<feature description>'
@@ -121,7 +121,7 @@ in-app features don't.
   queue-dispatched.
 - **Auth checks belong on the function or wiring**, not in function bodies.
   Use the `permissions` field with a `pikkuPermission` factory.
-- **Throw typed errors** from `@pikku/core/errors` — `NotFoundError`,
+- **Throw typed errors** from `#pikku/error` — `NotFoundError`,
   `ConflictError`, `BadRequestError`. Never bare `Error`.
 - **Migrations are inline SQL files** in the project's migrations dir
   (typically `sql/`). Use a numbered prefix matching existing files.
@@ -141,8 +141,9 @@ Some patterns vary by project; **read a neighbour file before writing**:
   `CreateTodoOutput`) passed to `input`/`output` on the func config — vs
   generic-typed config. Schema name **must match codegen expectations** (the
   exported const name = the schema name in generated `.gen.json`).
-- **Imports**: usually `'#pikku'` for `pikkuFunc` / `pikkuSessionlessFunc`
-  etc. Copy what neighbours do.
+- **Imports**: `#pikku` is a namespace, not a module — one subpath per wiring.
+  `pikkuFunc` / `pikkuSessionlessFunc` come from `'#pikku/function'`, `wireHTTP`
+  from `'#pikku/http'`. Copy what neighbours do.
 - **Service usage**: e.g. `kysely`, `redis`. Look at how an existing function
   destructures services from its first arg. **Check `application-types.d.ts`**
   to see whether services like `kysely` are typed (`Kysely<DB>`) or untyped