@pikku/skills 0.12.58 → 0.12.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.58",
+  "version": "0.12.59",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -16,23 +16,26 @@
   "scripts": {
     "embed": "bun run scripts/embed.ts",
     "tsc": "bun run embed && tsc",
-    "build": "bun run embed && tsc -b",
+    "build": "bun run clean && bun run embed && tsc -b",
     "ncu": "npx npm-check-updates",
     "test": "bash run-tests.sh",
     "test:watch": "bash run-tests.sh --watch",
     "test:coverage": "bash run-tests.sh --coverage",
-    "prepublishOnly": "bun run build"
+    "prepublishOnly": "bun run build",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "exports": {
-    ".": "./dist/index.js"
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "!dist/**/*.tsbuildinfo"
   ],
   "devDependencies": {
-    "@types/node": "^24.13.3",
-    "yaml": "^2.9.0"
+    "@types/node": "^26.6.5",
+    "yaml": "^2.9.1"
   },
   "engines": {
     "node": ">=24"

package/skills/pikku-a11y/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: pikku-a11y
 description: >-
-  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.
+  WCAG 2.2 accessibility rules for shadcn/Tailwind app UI: labeled inputs, real buttons/links,
+  keyboard and focus, contrast, modals, reduced motion. TRIGGER when: building forms or interactive
+  UI, icon-only buttons, modals/drawers, tables/lists with actions, keyboard/focus work, or the user
+  mentions accessibility, screen readers or WCAG. DO NOT TRIGGER when: backend, database or
+  deployment work with no UI.
 installGroups: [client]
 ---
 

package/skills/pikku-addon/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: pikku-addon
 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, 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).
+  Creating or consuming reusable Pikku function packages (addons): wireAddon, ref(),
+  pikkuAddonServices/pikkuAddonWireServices, package structure, shipping DB tables (pikku db
+  export), generating an addon from an OpenAPI/Swagger spec. TRIGGER when: code uses those APIs, or
+  the user asks about addons or cross-project function sharing, or hands over an OpenAPI/Swagger
+  spec (file or URL) to build on. DO NOT TRIGGER for internal function composition (use
+  pikku-wiring), general function definitions (use pikku-concepts) or n8n imports (use
+  pikku-n8n-import).
 installGroups: [core]
 ---
 
@@ -393,7 +392,7 @@ calls, one field out of fifty), or when the app adds a permission of its own.
 carries middleware, not permissions, so a rule on one addon function lives in
 the `permissions` of an app function that calls it. An addon called with the
 user's own credential is already limited upstream to what that user may do, so
-a data-aware `pikkuPermission` repeating that check (may they read *this*
+a data-aware `pikkuPermission` repeating that check (may they read _this_
 invoice?) adds nothing. A session-only `pikkuAuth` (a role, a tier) is still
 worth it: it can be checked before any input exists, so the functions a user
 can't call drop out of the tools an MCP client, an agent or a workflow is

package/skills/pikku-agent/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: pikku-agent
 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, 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).
+  Building AI agents, chatbots and LLM assistants with Pikku: pikkuAgent, ref() tools, memory,
+  streaming, tool approval, thread ownership, rpc.agent, VercelAgentRunner and its provider map,
+  voiceInput/voiceOutput. TRIGGER when: code uses
+  pikkuAgent/rpc.agent/runAgent/streamAgent/VercelAgentRunner/voiceInput, or the user asks about
+  agents, tool-calling, agent memory, model providers, speech in/out or `pikku enable agent`. DO NOT
+  TRIGGER for MCP exposure (use pikku-wiring), workflows (use pikku-workflow), React agent hooks
+  (use pikku-react) or general functions (use pikku-concepts).
 installGroups: [core]
 ---
 
@@ -21,11 +20,11 @@ than what they look like.
 
 ## Pick the reference
 
-| You are… | Read |
-| --- | --- |
-| Defining or invoking an agent — tools, memory, streaming, approval, threads, images | `references/agents.md` |
-| Wiring the runner, or pointing model strings at a provider or gateway | `references/runner-vercel.md` |
-| Adding speech in or out of an agent | `references/voice.md` |
+| You are…                                                                            | Read                          |
+| ----------------------------------------------------------------------------------- | ----------------------------- |
+| Defining or invoking an agent — tools, memory, streaming, approval, threads, images | `references/agents.md`        |
+| Wiring the runner, or pointing model strings at a provider or gateway               | `references/runner-vercel.md` |
+| Adding speech in or out of an agent                                                 | `references/voice.md`         |
 
 ## An agent is a function that reaches other functions
 
@@ -47,6 +46,10 @@ session, the credentials and the RPC depth for you.
   schema on a tool-calling agent is silently inert. The pairing that wants it is
   reading an image or a document into typed data — one tool-free agent, an
   `output` schema, and the picture passed as an `attachments` entry.
+- **An `output` the model returns is validated.** The run fails with
+  `AgentOutputValidationError` (502, `issues` lists what did not match) rather
+  than handing back a malformed object; there is no retry. A `null` the model
+  sends for an optional field comes back absent, so `.optional()` holds.
 - **`auth` defaults to `false`**, because agents are normally invoked from an
   already-authenticated `pikkuFunc`. `scopes` and `permissions` are enforced
   either way — see `pikku-permissions`.

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

@@ -24,7 +24,7 @@ const runner = new VercelAgentRunner(
 **Methods:**
 
 - `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)
+- `run(params: AgentRunnerParams): Promise<AgentStepResult>` — Execute a single AI step (non-streaming). Its `object` is `unknown` and unchecked: the runner has no agent, so there is no declared `output` to validate it against
 - `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

package/skills/pikku-architect/SKILL.md

@@ -1,15 +1,13 @@
 ---
 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`. 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
-  plan, or the user asks to plan or architect a changeset. DO NOT TRIGGER when: the knowledge notes
-  themselves are still being written (use pikku-knowledge), the plan already exists and the job is
-  to build it (use pikku-changes), or the changeset was claimed with no plan needed.
+  Turn one claimed changeset into its technical plan (tables, functions, wires, roles, scopes,
+  screens, scenarios, split into passes) via `pikku knowledge plan set`. The plan is the denominator
+  `pikku knowledge plan progress` divides by, so write it BEFORE any code and never edit it to match
+  the build. TRIGGER when: `pikku changes claim` says a plan is needed, `changes done` or `pikku
+  changes next` refuses for lack of one, or the user asks to plan/architect a changeset. DO NOT
+  TRIGGER while knowledge notes are still being written (use pikku-knowledge), when the plan exists
+  and the job is building it (use pikku-changes), or when no plan was needed.
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -20,7 +18,6 @@ agent:
     verify:
       - id: knowledge-consistent
         command: pikku knowledge validate
-
 ---
 
 # Plan one changeset

package/skills/pikku-auth/SKILL.md

@@ -1,16 +1,12 @@
 ---
 name: pikku-auth
 description: >-
-  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).
+  Identity in a Pikku app: authenticating a caller via login, logout, sessions, cookies, bearer
+  tokens, API keys, JWT, OAuth/social, MFA, Better Auth, machine callers, `pikku login`. TRIGGER
+  when: the user asks about those, how a CLI/agent/sandbox authenticates, or hits
+  InvalidSessionError. DO NOT TRIGGER for who may call a function: ownership, roles, scopes,
+  MissingScopeError (use pikku-permissions); identity-free middleware mechanics (use
+  pikku-middleware); secrets and env vars (use pikku-services).
 installGroups: [core]
 ---
 
@@ -26,7 +22,7 @@ They are separate gates, and confusing them is the most common mistake in a
 Pikku app.
 
 **Authentication** answers _who is calling_. It happens in middleware, before the
-function runs, and ends in a call to `setSession`.
+function runs, and ends in a call to `setInitialSession`.
 
 **Authorization** answers _may this caller do this_. It is declared on the
 function — `scopes` and `permissions` — never checked inside its body. All of it is
@@ -39,19 +35,19 @@ middleware instead.
 
 ## Pick the reference
 
-| You are… | Read |
-| --- | --- |
-| 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` |
-| Configuring the JWT service, or rotating a signing secret | `references/jose.md` |
+| You are…                                                                         | Read                         |
+| -------------------------------------------------------------------------------- | ---------------------------- |
+| 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` |
+| Configuring the JWT service, or rotating a signing secret                        | `references/jose.md`         |
 
 ## All authentication goes through `@pikku/better-auth`
 
 There is no second auth story. A hand-rolled user table, a bespoke password
-hash, a custom OAuth dance — all of them are the wrong answer, and the console
-will not work against them. `references/better-auth.md` has the setup; the
+hash, a custom OAuth dance — all of them are the wrong answer, and nothing else
+in Pikku will 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.
 

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

@@ -48,10 +48,6 @@ Better Auth owns its own HTTP surface, database tables, and session cookie. The
 
 You do NOT hand-write routes, the session middleware, or the secret wiring — `pikkuBetterAuth` + the CLI generate all of it. Re-run `pikku all` to regenerate.
 
-### The console requires Better Auth
-
-The Pikku console (`@pikku/addon-console`, enabled via `scaffold.console` in `pikku.config.json`) is an admin surface: **every console RPC now requires an authenticated session** (the functions are `pikkuFunc`; unauthenticated calls return `403`). So `scaffold.console` alone is **no longer the minimum** — you also need an auth strategy, and Better Auth is the supported one. `pikku all` **throws** if `scaffold.console` is set but no `pikkuBetterAuth(...)` is found in the project. Baseline is "must be logged in"; finer policy (admin-only, org scoping) is layered host-side via tag/HTTP middleware. See `pikku-meta` for the console's Security screen.
-
 ---
 
 ## Standard Setup
@@ -107,6 +103,38 @@ Enabling `session: { cookieCache: { enabled: true } }` makes the CLI split out a
 
 **Tradeoff:** server-side session revocation isn't seen until the cookie cache expires (sign-out is still immediate — it deletes the cookie).
 
+**Read the cookie the way the app writes it.** The stateless middleware never builds the auth instance, so it cannot see your `betterAuth({ ... })` options. The generated one is given `advanced.cookiePrefix`, `cookieCache.strategy` and `cookieCache.version` when they are **string literals** in the `betterAuth({ ... })` call — keep them literal and there is nothing to do. When one is not (an env var, a constant from elsewhere), the CLI warns and you register your own, which runs before the generated one:
+
+- A `jwe` or `jwt` `cookieCache.strategy` is recognised from the cookie's shape. Pin it with `cookieCache: { strategy }` if you prefer.
+- A custom `advanced.cookiePrefix` must be passed as `betterAuthStatelessSession({ cookiePrefix })`.
+- A `cookieCache.version` must be passed as `cookieCache: { version }`, or cookies of an older version still verify.
+- `cookieCache.jwt` (e.g. a JWKS) is never passed through — register your own for it.
+
+`pikkuBetterAuth` logs an error at startup when a constructed stateless middleware disagrees with the auth config.
+
+```typescript
+addGlobalMiddleware([
+  betterAuthStatelessSession({
+    cookiePrefix: 'my-app',
+    cookieCache: { strategy: 'jwe', version: '2' },
+  }),
+])
+```
+
+### Store-backed sessions (`secondaryStorage`)
+
+With better-auth's `secondaryStorage`, a session token _is_ the store key, so `betterAuthStoreSession` resolves a session with one `get` and no server bundled — and, unlike the stateless path, revocation is immediate. The token arrives on `Authorization: Bearer …` (enable `bearer()`) or on the session cookie; `transports` picks which.
+
+```typescript
+const storage = inMemorySessionStore() // or your own AuthSessionStorage over Redis/KV
+
+betterAuth({ secondaryStorage: storage, plugins: [bearer()] /* … */ })
+
+addGlobalMiddleware([betterAuthStoreSession({ store: () => storage })])
+```
+
+`AuthSessionStorage` is better-auth 1.7's `SecondaryStorage` contract: `get`, `set`, `delete`, `getAndDelete` and `increment`. It was called `SessionStore` before 0.13, which clashed with `@pikku/core`'s unrelated `SessionStore`. `prefixedSessionStore(storage, 'app_1/')` namespaces one backing store for several apps.
+
 **Don't add a redundant default `addHTTPMiddleware('*', [betterAuthSession()])`** — with cookieCache on, that re-drags the stateful server into every unit and defeats the split (validate flags it as `better-auth-stateful-session-global`). If you don't need to customize the session, the generated middleware is enough.
 
 **Customizing the session bridge (`mapSession`, `impersonation`, `apiKey`, …):** you do NOT chain a second middleware on top of the generated one — register your OWN global session middleware and the CLI steps aside (it stops generating its default). This works on both paths and is detected the same way:
@@ -126,21 +154,21 @@ resolves the caller's scopes through the registered `ScopeService` and checks th
 `admin:*` tree (`ADMIN_SCOPES` exports the ids so you never spell them as bare
 strings):
 
-| Gate                                                                 | Scope required             |
-| -------------------------------------------------------------------- | -------------------------- |
-| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate`        |
-| `credentialOAuth`'s `canLinkSingleton`                               | `admin:credentials:link`   |
-| the console's user directory                                         | `admin:users:list`         |
-| create a user out of band                                            | `admin:users:create`       |
-| ban / unban                                                          | `admin:users:ban`          |
-| delete a user and their data                                         | `admin:users:remove`       |
-| revoke a user's sessions                                             | `admin:users:sessions`     |
-| set a user's password                                                | `admin:users:password`     |
-| read credential values and who holds them                            | `admin:credentials:read`   |
-| set and delete credentials                                           | `admin:credentials:manage` |
-| view declared scopes, roles, and who holds them                      | `admin:scopes:read`        |
-| create roles, change their scopes, grant them                        | `admin:scopes:manage`      |
-| read the audit trail                                                 | `admin:audit:read`         |
+| Gate                                                   | Scope required             |
+| ------------------------------------------------------ | -------------------------- |
+| `impersonation` (any of the three session middlewares) | `admin:impersonate`        |
+| `credentialOAuth`'s `canLinkSingleton`                 | `admin:credentials:link`   |
+| the admin user directory                               | `admin:users:list`         |
+| create a user out of band                              | `admin:users:create`       |
+| ban / unban                                            | `admin:users:ban`          |
+| delete a user and their data                           | `admin:users:remove`       |
+| revoke a user's sessions                               | `admin:users:sessions`     |
+| set a user's password                                  | `admin:users:password`     |
+| read credential values and who holds them              | `admin:credentials:read`   |
+| set and delete credentials                             | `admin:credentials:manage` |
+| view declared scopes, roles, and who holds them        | `admin:scopes:read`        |
+| create roles, change their scopes, grant them          | `admin:scopes:manage`      |
+| read the audit trail                                   | `admin:audit:read`         |
 
 Holding the bare `admin` scope satisfies all of them — a parent grant covers
 everything nested beneath it — so `admin` is the direct replacement for the old
@@ -148,7 +176,7 @@ everything nested beneath it — so `admin` is the direct replacement for the ol
 
 Declare the tree in your own `defineScope` (the CLI extracts it by AST, so it must
 be an inline literal; `ADMIN_SCOPE_TREE` is exported from `@pikku/better-auth`
-as the reference shape). Apps wiring `@pikku/addon-console` inherit it already.
+as the reference shape).
 
 ```typescript
 defineScope({
@@ -244,15 +272,15 @@ like any other. None is automatic — an app wires the ones it needs.
 | Plugin                   | Plugin `id`        | Adds                                                                    | Use it when                                                   |
 | ------------------------ | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
 | `pikkuBan()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
-| `pikkuVirtualUser()`     | `virtualUser`      | `POST /sign-in/virtual-user`, `user.virtualUser`                        | Scenarios sign in as a virtual user         |
+| `pikkuVirtualUser()`     | `virtualUser`      | `POST /sign-in/virtual-user`, `user.virtualUser`                        | Scenarios sign in as a virtual user                           |
 | `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 |
 
 Every one carries a `pikku` prefix, because a `plugins: [...]` array mixes these
 with better-auth's own and a bare `virtualUser()` next to `organization()` says
-nothing about where it came from. The unprefixed names — `ban`, `virtualUser`,
-`credentialOAuth`, `delegatedAuth` — are still exported as deprecated
-aliases, so existing apps keep working.
+nothing about where it came from. The unprefixed names (`ban`, `virtualUser`,
+`credentialOAuth`, `delegatedAuth`) were removed; import the `pikku`-prefixed
+ones.
 
 The plugin's `id` is what better-auth stores; the **export name** is what the
 inspector reads off your `plugins` array and what generated metadata is keyed
@@ -339,6 +367,23 @@ An upstream user with no email gets one made up from the login, and the
 identity says so with `syntheticEmail: true`. A made-up address never links to
 an existing user row, so it cannot take over someone else's account.
 
+Even a real upstream email does not link to an existing local user unless you
+opt in, because it is still the upstream's word for that address:
+
+```typescript
+pikkuDelegatedAuth({
+  // false (default): a first sign-in whose email is taken is refused.
+  // 'non-admins': link unless the local user holds an admin
+  //               scope; needs scopeService, and links nobody without it.
+  // 'all': link anyone, administrators included.
+  linkExistingUsersByEmail: 'non-admins',
+  /* … */
+})
+```
+
+Roles are only ever granted: a role the upstream stops returning is not
+revoked.
+
 For an addon generated from an OpenAPI spec, none of this is written by hand:
 `pikku new addon --openapi … --auth-config <file>` generates
 `authenticate<Name>Upstream` in the addon and wires this plugin, the stored
@@ -446,19 +491,9 @@ Better Auth serves everything under `basePath` (default `/api/auth`). Call these
 
 The session cookie is `better-auth.session_token` (dev) / `__Secure-better-auth.session_token` (prod).
 
-### Dev quick login
-
-Set `PIKKU_DEV_QUICK_LOGIN=true` and `${basePath}/dev/quick-login` signs in a
-fixed dev admin (`admin@pikku.dev`), creating the user idempotently and granting
-it the bare `admin` scope. It is guarded twice — the env var _and_ a localhost
-hostname check — because a one-request path to an admin session is exactly the
-thing that must not survive a deploy. An app that has not declared the `admin`
-scope still gets a session, with a warning, since a scopeless dev user is useful.
-
 ### Virtual user sign-in (`virtualUser` plugin)
 
-A different thing from dev quick login, and the one to reach for when "sign in as
-someone" means **a particular kind of user** rather than one fixed admin.
+Signs in as **a particular kind of user**, for development and scenario runs.
 Register it explicitly — it is not automatic:
 
 ```typescript
@@ -604,7 +639,7 @@ await provisionVirtualUsers(
 )
 ```
 
-It writes the same `banned` column the console's ban RPC writes (so it needs the
+It writes the same `banned` column the ban RPC writes (so it needs the
 `pikkuBan()` plugin wired, and says so if it isn't), revokes the account's sessions,
 and leaves the row, its grants and its history intact — provisioning lifts the
 ban again by itself if the virtual user comes back. Deleting is deliberately not
@@ -641,7 +676,9 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables, kysely }) => be
 ```
 
 - Export exactly ONE `pikkuBetterAuth` per project; the CLI generates a single catch-all worker for all auth routes.
-- `betterAuthSession({ auth })` (generated) bridges the better-auth session into the Pikku session on every request — you never add it by hand.
+- The generated session middleware (`betterAuthSession()` or `betterAuthStatelessSession()`) bridges the better-auth session into the Pikku session on every request — you only register one yourself to customise it (`mapSession`, `impersonation`, `apiKey`; see "Stateless session" above).
+- `createAuthHandler()` takes no arguments: it reads `services.auth`. The CLI generates the catch-all route with it.
+- Outside a pikku function (Next.js route, TanStack loader), `getAuthSession(auth, request, createConfig, createSingletonServices)` reads the session. With a factory it builds the services and the instance once and reuses them across calls.
 - MFA, organizations, passkeys, etc. are better-auth plugins: add them to `betterAuth({ plugins: [...] })`. The catch-all route already forwards their endpoints.
 
 ---

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

@@ -13,6 +13,14 @@
 third argument — not on services. `setSession`/`clearSession` may be async
 (cookie and session-store backends write on the way out), so await them.
 
+`setSession` means the same in middleware and in a function body: it signs the
+caller in — the session is marked changed, so `authCookie` re-issues the cookie,
+and it is written to the session store under its `userId`. Middleware that only
+works out who the caller is from a credential it was handed (a cookie, a bearer
+token, an API key) calls `setInitialSession` instead: the function sees that
+session, but nothing is persisted and no cookie is re-issued. Calling
+`setSession` there would rewrite the cookie and the store on every request.
+
 ```typescript
 // Read session in pikkuFunc (session guaranteed to exist)
 const getProfile = pikkuFunc({

package/skills/pikku-build/SKILL.md

@@ -1,17 +1,14 @@
 ---
 name: pikku-build
 description: >-
-  Use to build on Pikku — turning a fresh scaffold into a working app (quick spike, real product,
-  or a showcase that exercises every surface), adding a feature to an app that already exists, and
-  the one-off cleanup right after a template is cloned. Covers the knowledge base, virtual users and
-  roles, filing the work as changes, the scenario that proves each one, theming, multi-app
-  layouts and deploying. TRIGGER when: the user asks for an app to be built on
-  Pikku, a freshly scaffolded project needs turning into a product, the user asks to add a feature
-  or wire up a new endpoint in a working app, or a template was just cloned or scaffolded. DO NOT
-  TRIGGER when: the user asks for a one-off edit to an existing function, asks about Pikku concepts
-  (use pikku-concepts), wants one specific surface explained rather than built (use that surface's
-  skill), only needs the technical plan for one claimed changeset (use pikku-architect), or is
-  working items off a deployed stage's changes queue (use pikku-changes).
+  Owns app-level work on Pikku (new app, feature, conversion); load pikku-concepts first. Turn a fresh scaffold into a working app (spike, real product or showcase), add a
+  feature or endpoint to an existing app, and the cleanup after a template is cloned. Covers
+  knowledge base, virtual users, changes, proving scenarios, theming, multi-app layouts, deploying.
+  TRIGGER when: asked to build an app on Pikku, a scaffold/template was just created or cloned, or
+  asked to add a feature or wire a new endpoint in a working app. DO NOT TRIGGER for one-off
+  function edits, Pikku concepts (use pikku-concepts), explaining one surface (use that surface's
+  skill), planning one claimed changeset (use pikku-architect) or working a stage's changes queue
+  (use pikku-changes).
 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 rm *), Bash(git mv *), Bash(git log *), Bash(git branch *), Bash(yarn pikku cloud report *), Bash(npx --no pikku cloud report *)
 argument-hint: '[feature description]'
 installGroups: [core]
@@ -32,29 +29,30 @@ agent:
 
 ## Which mode
 
-| The situation                                                                  | Read                                                                                          |
-| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| A template was just cloned or scaffolded, and the tree still looks like one    | `references/post-clone.md` first, then come back                                              |
-| A real product, meant to be picked up by someone else                          | `references/app.md` — the default                                                             |
-| A spike, a throwaway demo, an idea nobody has committed to                     | `references/quick.md`                                                                         |
-| A showcase meant to exercise every Pikku surface                               | `references/platform.md`, read together with `references/app.md`                              |
-| A feature added to an app that already has its knowledge base                  | `references/feature.md`                                                                       |
-| Writing or fixing the scenarios that prove a changeset (app §7, §7a)           | `references/scenarios.md`                                                                     |
-| Before the first screen is built: a picture of the screens, a design direction | `references/design.md`                                                                        |
-| Authoring or changing the theme (app §8a)                                      | `references/theming.md`                                                                       |
-| A screen needs data no function returns yet                                    | `references/mocks.md`                                                                         |
-| Adding a second frontend (app §4), at the changeset that needs it              | `references/multi-app.md`                                                                     |
-| Shipping an app as a desktop or Android app                                    | `references/native-app.md`                                                                    |
-| Deploying, and the deploy-readiness contract (app §9)                          | `references/ship.md`                                                                          |
-| The request is built on an OpenAPI spec (auth mode, sign-in or connect screen) | `references/openapi.md`                                                                       |
+| The situation                                                                  | Read                                                                                             |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
+| A template was just cloned or scaffolded, and the tree still looks like one    | `references/post-clone.md` first, then come back                                                 |
+| A real product, meant to be picked up by someone else                          | `references/app.md` (index), then the phase file it names for the phase you are in — the default |
+| A spike, a throwaway demo, an idea nobody has committed to                     | `references/quick.md`                                                                            |
+| A showcase meant to exercise every Pikku surface                               | `references/platform.md`, read together with `references/app.md`                                 |
+| A feature added to an app that already has its knowledge base                  | `references/feature.md`                                                                          |
+| Writing or fixing the scenarios that prove a changeset (app §7, §7a)           | `references/scenarios.md`                                                                        |
+| Before the first screen is built: a picture of the screens, a design direction | `references/design.md`                                                                           |
+| Authoring or changing the theme (app §8a)                                      | `references/theming.md`                                                                          |
+| A screen needs data no function returns yet                                    | `references/mocks.md`                                                                            |
+| Adding a second frontend (app §4), at the changeset that needs it              | `references/multi-app.md`                                                                        |
+| Shipping an app as a desktop or Android app                                    | `references/native-app.md`                                                                       |
+| Deploying, and the deploy-readiness contract (app §9)                          | `references/ship.md`                                                                             |
+| The request is built on an OpenAPI spec (auth mode, sign-in or connect screen) | `references/openapi.md`                                                                          |
 
 **App is the default.** A small or toy-sounding app does not make it Quick;
 only an explicit signal of speed or throwaway-ness does. Platform is not "App
 plus more effort" — it is App plus a deliberate surface checklist: read both
 files, follow the base in full, and do not blend the two into one plan.
 
-Each reference names the topics it leans on but never tells you to open
-another file; this table is the only routing. Open a reference when its row
+Apart from `app.md`, which indexes its own phase files, each reference names
+the topics it leans on but never tells you to open another file; this table is
+the only routing. Open a reference when its row
 matches, not up front.
 
 ## Bootstrap before anything else
@@ -109,7 +107,7 @@ generated functions through `ref()`.
   calls for a scheduled task and `capabilities.scheduler` is `false`, check
   `pikku doc` for the door before concluding you cannot build it.
 - **`metaLocale` in `pikku.config.json` is the language of authored meta** —
-  every `description`, `title` and step `template` the console renders.
+  every `description`, `title` and step `template` authored in meta.
   Identifiers stay English whatever it says, and the product's own language
   lives in `messages/*.json`.
 - **`pikku all` is the gate.** Run it after touching functions, wirings or
@@ -146,8 +144,6 @@ generated functions through `ref()`.
   - **App** — the frontend's URL (`http://localhost:7104` in the template; each
     frontend in `frontends` in `pikku.config.json` has its own port)
   - **API** — `http://localhost:3000`
-  - **Console** — `http://localhost:3000/console`, plus a deep link to each
-    page that shows what this turn produced (the paths are below)
 
   A person who has to go hunting for the port assumes the app did not start.
 
@@ -166,46 +162,18 @@ again with `--consent <answer>`. If it says reporting is off, do not ask.
 ## Who you are talking to
 
 The prompt asks first how technical the person is: **not technical**,
-**technical, no code**, or **developer** (the default when unsaid). Whenever the
-build makes or changes something the console can show, give the
-`http://localhost:<port>/console/...` link instead of describing it.
+**technical, no code**, or **developer** (the default when unsaid). Report in
+plain words at that level, and give the links `bun run dev` printed (the app
+and the API). No per-feature deep links.
 
-Until the app is deployed that is the local open-source console, on the port
-`pikku dev` printed. Once it is deployed, link the hosted console for the stage
-you are talking about instead.
-
-| Level              | Links                       | Code in the conversation |
-| ------------------ | --------------------------- | ------------------------ |
-| Not technical      | Product pages only          | Never                    |
-| Technical, no code | Product and technical pages | Never                    |
-| Developer          | Product and technical pages | As normal                |
+| Level              | Code in the conversation |
+| ------------------ | ------------------------ |
+| Not technical      | Never                    |
+| Technical, no code | Never                    |
+| Developer          | As normal                |
 
 "Never" includes snippets and command lines; say what changed in the person's
-words and link to where they can see it.
-
-**Product pages** — the only ones a non-technical person gets:
-
-| Shows                 | Path                                                                       |
-| --------------------- | -------------------------------------------------------------------------- |
-| Knowledge, plans      | `/console/knowledge`, `/console/knowledge?id=<note path>`                  |
-| Virtual users              | `/console/virtual-users`, `/console/virtual-users?virtual user=<id>`                 |
-| Roles and permissions | `/console/roles`, `/console/scopes` (only with `@pikku/addon-admin` wired) |
-| Scenarios and runs    | `/console/scenarios?id=<id>`, `/console/scenarios?view=runs&run=<run id>`  |
-| Workflows             | `/console/workflow?id=<id>`                                                |
-| Agents                | `/console/agents`, `/console/agents/playground?id=<agent id>`              |
-
-**Technical pages** — never for a non-technical person: `/console/overview`,
-`/console/functions`, `/console/surface`, `/console/database`,
-`/console/changes`, `/console/wires/http`, `/console/wires/channel`,
-`/console/wires/mcp`, `/console/wires/cli`, `/console/wires/gateway`,
-`/console/async/scheduler`, `/console/async/queue`, `/console/async/trigger`,
-`/console/runtime`, `/console/emails`, `/console/webhooks`, `/console/secrets`,
-`/console/variables`, `/console/security`, `/console/auth-providers`,
-`/console/addons`, `/console/analytics`, `/console/credentials`,
-`/console/users`, `/console/audit`, `/console/flags`, `/console/scorers`.
-
-These come from `packages/console/src/App.tsx`; do not link a path that is not
-listed here.
+words and point at the running app.
 
 ## What NOT to do