@pikku/skills 0.12.2 → 0.12.6

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

@@ -54,7 +54,7 @@ Better Auth owns its own HTTP surface, database tables, and session cookie. The
 1. **`pikkuBetterAuth(factory)`** — you export ONE `pikkuBetterAuth` call whose factory returns a configured `betterAuth({...})` instance. The pikku CLI inspects this export and generates everything else.
 2. **Generated `auth.gen.ts`** — a catch-all `${basePath}{/*splat}` HTTP route per method (GET + POST) that forwards every request under the base path to better-auth's own internal router. The enabled providers and plugins are written to `auth/pikku-auth-meta.gen.json` (read by the console SSO page via `getAuthProviders`).
 3. **Generated session middleware** — with `session.cookieCache` enabled (recommended), a separate `auth-middleware.gen.ts` adds the lean stateless `betterAuthStatelessSession()`; without it, `auth.gen.ts` adds the stateful `betterAuthSession()` that bundles the full server into every unit. See "Stateless session" below.
-4. **Generated `auth-secrets.gen.ts`** — a `wireSecret` for `BETTER_AUTH_SECRET` and for each social provider's OAuth credentials, plus a `wireVariable` for any non-secret provider config (e.g. `tenantId`).
+4. **Generated `auth-secrets.gen.ts`** — a `defineSecret` for `BETTER_AUTH_SECRET` and for each social provider's OAuth credentials, plus a `defineVariable` for any non-secret provider config (e.g. `tenantId`).
 
 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.
 
@@ -86,7 +86,12 @@ export const auth = pikkuBetterAuth(async ({ secrets }) => {
     secret: BETTER_AUTH_SECRET,
     // memoryAdapter needs an array per model — `{}` throws "Model user not found"
     // at runtime. Swap for the Kysely adapter in production (see below).
-    database: memoryAdapter({ user: [], session: [], account: [], verification: [] }),
+    database: memoryAdapter({
+      user: [],
+      session: [],
+      account: [],
+      verification: [],
+    }),
     emailAndPassword: { enabled: true },
     // ALWAYS enable for deployed apps — see "Stateless session" below.
     session: { cookieCache: { enabled: true } },
@@ -98,7 +103,8 @@ export const auth = pikkuBetterAuth(async ({ secrets }) => {
 ```
 
 **Key points:**
-- `socialProviders` keys must be string literals — the CLI reads them statically to emit a `wireSecret` per provider. Provider keys mirror better-auth's built-in ids exactly (e.g. `microsoft`, NOT `microsoft-entra-id`; `cognito`; `github`).
+
+- `socialProviders` keys must be string literals — the CLI reads them statically to emit a `defineSecret` per provider. Provider keys mirror better-auth's built-in ids exactly (e.g. `microsoft`, NOT `microsoft-entra-id`; `cognito`; `github`).
 - The factory runs lazily on the first auth request, so it pulls secrets/DB off the injected `services`.
 - The default `basePath` is `/api/auth`. Override it by passing `basePath` to `betterAuth`.
 - **Enable `session: { cookieCache: { enabled: true } }`** so non-auth units tree-shake the better-auth server out (see below).
@@ -115,36 +121,42 @@ Enabling `session: { cookieCache: { enabled: true } }` makes the CLI split out a
 
 **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:
 
-- **Stateless (cookieCache on):** register `betterAuthStatelessSession({ mapSession })` **globally** — `addHTTPMiddleware('*', [...])` or `addGlobalMiddleware([...])`. The CLI sees the global registration and skips emitting `auth-middleware.gen.ts` (pikkujs/pikku#754), so you keep cookieCache's lean bundles *and* your custom fields.
+- **Stateless (cookieCache on):** register `betterAuthStatelessSession({ mapSession })` **globally** — `addHTTPMiddleware('*', [...])` or `addGlobalMiddleware([...])`. The CLI sees the global registration and skips emitting `auth-middleware.gen.ts` (pikkujs/pikku#754), so you keep cookieCache's lean bundles _and_ your custom fields.
 - **Stateful (cookieCache off):** register `betterAuthSession({ mapSession, impersonation })` **globally**. The CLI detects it (`hasUserSessionMiddleware`) and omits its own `addHTTPMiddleware('*', [betterAuthSession()])` from `auth.gen.ts` — so there's exactly one session bridge in the chain, yours.
 
 In both cases a **route-scoped** registration (`addHTTPMiddleware('/some/path', [...])`) does NOT count — only a global one suppresses the generated default. The generated middleware in a `.gen.ts` file is also ignored by the detector, so regeneration never self-suppresses.
 
 ### Admin capabilities are scopes, not a role
 
-Pikku does **not** use better-auth's `admin()` plugin, and nothing in this
-package reads a `role` column. A role is not a permission: "who may impersonate"
-and "who may rebind a shared credential" are different capabilities one user can
-hold independently, which a single `role` string cannot express. Every gate the
-package owns therefore resolves the caller's scopes through the registered
-`ScopeService` and checks the `admin:*` tree:
-
-| Gate | Scope required |
-| --- | --- |
-| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate` |
-| `credentialOAuth`'s `canLinkSingleton` | `admin:credentials:link` |
-| the console's user directory | `admin:users:list` |
+Scopes are the source of truth for what an admin may do; nothing in pikku reads
+a `role`. A role is not a permission: "who may impersonate" and "who may rebind a
+shared credential" are different capabilities one user can hold independently,
+which a single `role` string cannot express. Every gate the package owns
+resolves the caller's scopes through the registered `ScopeService` and checks the
+`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`   |
 
 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
 `role === 'admin'`.
 
-Declare the tree in your own `wireScope` (the CLI extracts it by AST, so it must
+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.
 
 ```typescript
-wireScope({
+defineScope({
   admin: {
     displayName: 'Administration',
     description: 'Capabilities that act on the application as a whole',
@@ -158,7 +170,14 @@ wireScope({
       },
       users: {
         description: 'The user directory',
-        scopes: { list: { description: 'List and search users' } },
+        scopes: {
+          list: { description: 'List and search users' },
+          create: { description: 'Create users out of band' },
+          ban: { description: 'Ban and unban users' },
+          remove: { description: 'Delete users and all their data' },
+          sessions: { description: "Revoke a user's sessions" },
+          password: { description: "Set a user's password" },
+        },
       },
     },
   },
@@ -172,9 +191,22 @@ a scope, so nothing is authorized, and the denial is logged at `warn` because
 that is a configuration bug rather than a permissions decision. Pass your own
 `canImpersonate` / `canLinkSingleton` to override the default entirely.
 
-Sibling concerns — banning a user, listing users from your own screens — are
-actions your app *invokes*, not things pikku gates. Put them on your own
-functions with `scopes: ['admin:users:ban']` and friends.
+### If you do wire better-auth's `admin()` plugin
+
+The last five capabilities in the table are implemented by better-auth's own
+`admin()` endpoints, which authorize against `user.role` — a column pikku
+otherwise ignores. Rather than making you maintain two grant systems,
+`syncProjectedAdminRole` keeps that column as a *projection* of the scope set:
+at the session boundary it writes `role = 'admin'` when the user holds any of
+`admin:users:{create,ban,remove,sessions,password}`, and the plugin's
+`defaultRole` otherwise. `projectedAdminRole(scopes, defaultRole)` computes the
+value if you need it yourself.
+
+The projection is deliberately not "any `admin:*` scope": `impersonate` and
+`users:list` are pikku's own gates, and rolling them in would hand ban and delete
+rights to someone granted only the ability to look. The plugin is auto-detected
+from the live instance, so an app without it never writes to a column that does
+not exist.
 
 ### 2. Production database adapter
 
@@ -184,9 +216,9 @@ For real deployments swap `memoryAdapter` for the Kysely adapter backed by an in
 import { kyselyAdapter } from 'better-auth/adapters/kysely'
 
 export const auth = pikkuBetterAuth(async ({ secrets, kysely }) => {
-  const { BETTER_AUTH_SECRET } = await secrets.getSecrets<{ BETTER_AUTH_SECRET: string }>([
-    'BETTER_AUTH_SECRET',
-  ])
+  const { BETTER_AUTH_SECRET } = await secrets.getSecrets<{
+    BETTER_AUTH_SECRET: string
+  }>(['BETTER_AUTH_SECRET'])
   return betterAuth({
     secret: BETTER_AUTH_SECRET,
     database: kyselyAdapter(kysely, { type: 'postgres' }),
@@ -204,7 +236,7 @@ If you place `auth.ts` under `srcDirectories` it is inspected automatically. The
 
 ## Social Providers needing extra config
 
-Some providers require non-secret config alongside the OAuth secret — the CLI emits a `wireVariable` for these:
+Some providers require non-secret config alongside the OAuth secret — the CLI emits a `defineVariable` for these:
 
 - `microsoft` → `MICROSOFT_TENANT_ID` (or `"common"`)
 - `cognito` → `COGNITO_DOMAIN`, `COGNITO_REGION`, `COGNITO_USER_POOL_ID`
@@ -221,7 +253,12 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables }) => {
 
   return betterAuth({
     secret: BETTER_AUTH_SECRET,
-    database: memoryAdapter({ user: [], session: [], account: [], verification: [] }),
+    database: memoryAdapter({
+      user: [],
+      session: [],
+      account: [],
+      verification: [],
+    }),
     socialProviders: {
       microsoft: { ...MICROSOFT_OAUTH, tenantId: MICROSOFT_TENANT_ID },
     },
@@ -258,18 +295,27 @@ For public endpoints that optionally vary by viewer, use `pikkuSessionlessFunc`
 
 Better Auth serves everything under `basePath` (default `/api/auth`). Call these directly — the Pikku SDK does not wrap them.
 
-| Action | Request | Result |
-|---|---|---|
-| Sign up | `POST /api/auth/sign-up/email` `{ name, email, password }` | 200 + `better-auth.session_token` cookie |
-| Log in | `POST /api/auth/sign-in/email` `{ email, password }` | 200 + cookie; wrong creds → 401 `{ code: "INVALID_EMAIL_OR_PASSWORD" }` |
-| Session | `GET /api/auth/get-session` | `{ session, user }` or `null` |
-| Social sign-in | `POST /api/auth/sign-in/social` `{ provider, callbackURL }` | 200 `{ url, redirect }` (authorize URL) |
-| Sign out | `POST /api/auth/sign-out` | 200, clears cookie |
+| Action         | Request                                                     | Result                                                                  |
+| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Sign up        | `POST /api/auth/sign-up/email` `{ name, email, password }`  | 200 + `better-auth.session_token` cookie                                |
+| Log in         | `POST /api/auth/sign-in/email` `{ email, password }`        | 200 + cookie; wrong creds → 401 `{ code: "INVALID_EMAIL_OR_PASSWORD" }` |
+| Session        | `GET /api/auth/get-session`                                 | `{ session, user }` or `null`                                           |
+| Social sign-in | `POST /api/auth/sign-in/social` `{ provider, callbackURL }` | 200 `{ url, redirect }` (authorize URL)                                 |
+| Sign out       | `POST /api/auth/sign-out`                                   | 200, clears cookie                                                      |
 
 **`Origin` header on state-changing POSTs:** better-auth enforces an `Origin` header matching `baseURL` on POSTs such as sign-out — omit it and you get `403`. Browsers send it automatically; server-to-server callers must set it.
 
 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.
+
 ---
 
 ## Secret Management

package/skills/pikku-cli/SKILL.md

@@ -36,19 +36,23 @@ See `pikku-concepts` for the core mental model.
 
 ### `wireCLI(config)`
 
+All three factories come from `#pikku` (the generated types re-export
+`cli/pikku-cli-types.gen.js`). Importing them from `@pikku/core/cli` compiles but
+loses your project's service and middleware types.
+
 ```typescript
-import { wireCLI } from '@pikku/core/cli'
+import { wireCLI } from '#pikku'
 
 wireCLI({
   program: string,              // Program name (e.g. 'todos')
-  options?: {                   // Global options
-    [key: string]: {
-      description: string,
-      short?: string,           // Single char alias (e.g. 'v')
-      default?: any,
-    }
-  },
+  description?: string,
+  summary?: string,
+  options?: CLIOptions,         // Global options — see below
   render?: PikkuCLIRender,      // Default renderer for all commands
+  middleware?: PikkuMiddleware[],
+  tags?: string[],              // Targets tag middleware
+  errors?: string[],
+  auth?: boolean,               // Only affects the websocket backend, not local runs
   commands: {
     [name: string]: PikkuCLICommand | {
       description: string,
@@ -65,24 +69,49 @@ import { pikkuCLICommand } from '#pikku'
 
 pikkuCLICommand({
   parameters?: string,          // Positional args (e.g. '<text>', '<username> <email>')
-  func: PikkuFunc,              // Business logic function
+  func?: PikkuFunc,             // Business logic function — omit on a pure command group
+  title?: string,
   description?: string,
   render?: PikkuCLIRender,      // Custom output renderer
-  options?: {
-    [key: string]: {
-      description: string,
-      short?: string,
-      default?: any,
-      choices?: string[],       // Restrict to values
-    }
-  },
+  options?: CLIOptions,
+  subcommands?: { [name: string]: PikkuCLICommand },  // nests to any depth
+  middleware?: PikkuMiddleware[],
+  permissions?: PermissionGroup,
+  auth?: boolean,
+  isDefault?: boolean,          // Runs when the group is invoked with no subcommand
 })
 ```
 
+`parameters` is checked against the func's input at compile time — a name that is
+not a key of the input makes the type `never`, so a typo'd positional fails to
+build rather than arriving as `undefined`.
+
+### Options
+
+```typescript
+{
+  description: string,
+  short?: string,        // Single char alias (e.g. 'v')
+  default?: any,
+  choices?: any[],       // Restrict to these values
+  array?: boolean,       // Collect every value up to the next flag
+  required?: boolean,
+}
+```
+
+How the parser reads them, which is worth knowing before you name one:
+
+- **Flag names are camel-cased**, so `--api-url` and `--apiUrl` both fill `apiUrl`.
+- **`--no-x` negation only works when `x` has a boolean `default`.** Without one,
+  `--no-x` parses as an option literally named `noX` — which is why boolean flags
+  should always declare their default.
+- Short flags cluster (`-abc`), and only the last in a cluster may take a value.
+- An unknown `--flag` warns rather than throwing.
+
 ### `pikkuCLIRender(fn)`
 
 ```typescript
-import { pikkuCLIRender } from '@pikku/core/cli'
+import { pikkuCLIRender } from '#pikku'
 
 const renderer = pikkuCLIRender<OutputType>((services, data) => {
   // Format and print output to terminal
@@ -90,6 +119,15 @@ 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)
+```
+
 ## Usage Patterns
 
 ### Basic Commands
@@ -193,6 +231,17 @@ wireCLI({
 
 The func's input is the positional `parameters` plus `options`, merged (e.g. `parameters: '<username> <email>'` + an `admin` option → func input `{ username, email, admin }`).
 
+A renderer's full signature is `(services, data, session?)`. It returns nothing —
+printing is its job.
+
+### Running the program over a websocket
+
+Codegen emits a `<program>-channel.gen.ts` beside your wiring: a `wireChannel`
+that serves the same commands remotely, so a local binary and a hosted session
+run identical code. `auth` on `wireCLI` guards **that channel only** — a locally
+executed CLI has no connection to authenticate, so it is not a way to require a
+session for local runs. Don't hand-write or edit the generated channel file.
+
 ## Complete Example
 
 For a full functions + renderers + nested-subcommand wiring walkthrough, see `references/complete-example.md`.

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

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

package/skills/pikku-concepts/SKILL.md

@@ -28,7 +28,8 @@ 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`
-- **Infrastructure**: `pikku-services`, `pikku-security`, `pikku-config`
+- **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`
 
 ## Core Mental Model
@@ -58,7 +59,7 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-Controllers/routes → `pikkuFunc`; middleware/auth/permissions → `pikku-security`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
+Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
@@ -95,22 +96,53 @@ Services can be destructured inline in the `func` signature (e.g. `async ({ logg
 
 ```typescript
 pikkuFunc({
+  // Identity and documentation
   title?: string,           // Human-readable name
   description?: string,     // What the function does
-  version?: number,         // Contract version (see pikku-config for versioning)
+  version?: number,         // Contract version (see pikku-versioning)
+  override?: string,        // Logical name override, so several exports share a versioned base
   tags?: string[],          // For grouping and middleware targeting
+
+  // Contract
+  input?: ZodSchema,        // Input validation schema
+  output?: ZodSchema,       // Output validation schema
+  errors?: Array<typeof PikkuError>,  // Errors this function may throw
+
+  // Reachability
   expose?: boolean,         // Allow external RPC calls (see pikku-rpc)
   remote?: boolean,         // Allow remote RPC calls
   mcp?: boolean,            // Expose as MCP tool (see pikku-mcp)
+  readonly?: boolean,       // Declares the function performs no writes
+  deploy?: 'serverless' | 'server' | 'auto',
+
+  // Authorization — see pikku-permissions
   auth?: boolean,           // Override default auth requirement
-  input?: ZodSchema,        // Input validation schema
-  output?: ZodSchema,       // Output validation schema
-  permissions?: PermissionGroup,  // See pikku-security
-  middleware?: PikkuMiddleware[], // See pikku-security
+  scopes?: ScopeId[],       // AND-ed, checked before permissions; session required
+  permissions?: PermissionGroup,  // OR-ed pool
+  permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
+  middleware?: PikkuMiddleware[], // See pikku-middleware
+
+  // Agent tooling — see pikku-ai-agent
+  approvalRequired?: boolean,
+  approvalDescription?: (services, data) => Promise<string>,
+
+  // Workflow step behavior — see pikku-workflow
+  workflowQueued?: boolean, // Dispatch via queue instead of inline
+  workflowRetries?: number,
+  workflowTimeout?: string, // e.g. '30s', '5m'
+
+  audit?: boolean | { durability?: 'best-effort' | 'transactional' },
+
   func: async (services, data, wire) => { ... },
 })
 ```
 
+`scopes` is the one option `pikkuSessionlessFunc` does not accept, and the
+omission is deliberate: scopes are AND-ed and fail closed, so an anonymous
+caller holds none and satisfies none — a sessionless function with scopes would
+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 —
 they double as runtime validation and OpenAPI) or type generics
@@ -145,7 +177,35 @@ Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI doc
 
 ## Server Bootstrap
 
-Every Pikku app follows the same bootstrap pattern regardless of runtime:
+There are two ways to start a Pikku app. Pick based on whether you need to own the HTTP server.
+
+**1. Let Pikku own the server (preferred when you don't need a specific runtime)**
+
+`pikku dev` and `pikku serve` create the config and singleton services, start the server, and shut it down cleanly. You write no bootstrap code at all — startup and shutdown work goes in lifecycle hooks:
+
+```typescript
+// src/lifecycle.ts
+import { pikkuServerLifecycle } from '@pikku/core'
+import type { SingletonServices } from '../types/application-types.js'
+
+export const lifecycle = pikkuServerLifecycle<SingletonServices>({
+  beforeStart: async ({ kysely }) => {
+    await runMigrations(kysely)
+  },
+  afterStart: async ({ logger }) => {
+    logger.info('accepting traffic')
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain()
+  },
+})
+```
+
+Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
+
+**2. Bootstrap it yourself (required for a specific runtime)**
+
+Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
 
 ```typescript
 import '../../functions/.pikku/pikku-bootstrap.gen.js' // Generated — registers all wirings
@@ -168,6 +228,10 @@ await server.init()
 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 workspace 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:
@@ -175,7 +239,7 @@ Run `npx pikku all` to generate:
 - `pikku-types.gen.ts` — Typed function factories and wiring functions
 - `pikku-fetch.gen.ts` — Type-safe HTTP client
 - `pikku-websocket.gen.ts` — Type-safe WebSocket client
-- `pikku-bootstrap.gen.js` — Runtime initialization (auto-imports all wirings)
+- `pikku-bootstrap.gen.ts` — Runtime initialization (auto-imports all wirings)
 - `pikku-services.gen.ts` — Service factory types
 
 Config lives in `pikku.config.json`:
@@ -203,12 +267,13 @@ src/
 │   └── queue.wiring.ts
 ├── schemas.ts           # Zod/Valibot schemas
 ├── services.ts          # Service factories (see pikku-services)
+├── lifecycle.ts         # Server lifecycle hooks (pikku dev/serve only)
 ├── middleware.ts         # Middleware definitions (see pikku-security)
 ├── permissions.ts       # Permission definitions (see pikku-security)
 └── .pikku/              # Generated (gitignored)
     ├── pikku-types.gen.ts
     ├── pikku-fetch.gen.ts
-    └── pikku-bootstrap.gen.js
+    └── pikku-bootstrap.gen.ts
 ```
 
 ## Environment Variables
@@ -221,6 +286,13 @@ const apiKey = services.variables.get('API_KEY')
 
 `process.env` belongs in server bootstrap code (`start.ts`) only.
 
+## Secrets
+
+`secrets` is not part of a function's services. It is available only in
+`pikkuServices`, `pikkuWireServices`, addon service factories and middleware —
+read it there, give the value to a service, and have the function ask that
+service. Reaching for it through a cast throws at runtime.
+
 ## Testing
 
 Functions are easily testable because they're pure:

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

@@ -18,8 +18,8 @@ Authoritative mapping table plus side-by-side code examples showing how common b
 | **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
 | **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
 | **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
-| **Type-safe API client**                | `npx pikku all` generates clients                          | `pikku-concepts`  |
-| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
+| **Type-safe API client**                | `npx pikku all` generates clients                               | `pikku-concepts`  |
+| **Secrets / Config**                    | `defineSecret`, `defineVariable`, `services.variables`          | `pikku-config`    |
 
 ## Route Handler / Controller → pikkuFunc