@pikku/skills 0.12.58 → 0.12.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.58",
+  "version": "0.12.60",
   "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-addon/references/addon-package-manifest.md

@@ -5,6 +5,7 @@
 - Package Structure
 - pikku.config.json
 - package.json (key fields)
+- Platform service contributors (`pikku.contributors`)
 - tsconfig.json (key fields)
 
 `npx pikku new addon` scaffolds these files. You rarely hand-edit them — consult this when wiring exports or config by hand.
@@ -98,6 +99,58 @@ live in a file that never imports `#pikku` — see "Functions" in the skill.
 writes `@my-org/addon-todos/.pikku/rpc/...`, exactly as it would in an
 application, and the leaf stays the package's own business.
 
+## Platform service contributors (`pikku.contributors`)
+
+An addon can ship code that runs in the **host's** generated
+`createPlatformServices` — a log source over the host's database, a client
+built from a host secret. `wireAddon` has no field for it; the package declares
+it in its own `package.json`, the same shape as the host's `dev.contributors`:
+
+```json
+{
+  "exports": {
+    "./contributors": {
+      "types": "./dist/src/contributors.d.ts",
+      "import": "./dist/src/contributors.js"
+    }
+  },
+  "pikku": {
+    "contributors": [
+      { "module": "@my-org/addon-logs/contributors", "export": "logSources" }
+    ]
+  }
+}
+```
+
+`module` resolves from the addon's package directory. Every app that wires the
+addon (not `wireRemoteAddon`) picks the contributors up: `pikku all` emits them
+into `.pikku/pikku-dev-platform-services.gen.ts` for `pikku dev`, and
+`pikku deploy plan` / `apply` hands them to the provider adapter, after the
+app's own `deploy.contributors`.
+
+Declare what a contributor reads and sets, rather than relying on list order:
+
+```ts
+export const logSources: PlatformServiceContributor = {
+  name: 'log-sources',
+  needs: ['kysely'], // runtime.kysely, or a contributor's services.kysely
+  provides: ['logSources', 'logSources.workspace'],
+  imports: [`import { kyselyLogSource } from '@my-org/addon-logs/log-source'`],
+  emit: () => [
+    `  services.logSources = { workspace: kyselyLogSource(runtime.kysely) }`,
+  ],
+}
+```
+
+Contributors are sorted so each runs after every contributor providing one of
+its `needs`; a dotted need (`logSources.stage`) is met by a provider of the key
+or of its prefix. Emitted lines read services the entry built before them as
+`runtime.<name>` — `pikku dev` has logger, variables, secrets, schema and (with
+`db`) kysely; the standalone entry has logger, kysely (with a database) and its
+scheduler/queue/workflow/trigger services and event hub. Codegen **fails** on a
+need nothing meets, on two contributors providing the same key, and on a cycle,
+naming the contributors involved.
+
 ## tsconfig.json (key fields)
 
 ```json

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({