@pikku/skills 0.12.2 → 0.12.6

package/skills/pikku-schedule/SKILL.md

@@ -36,22 +36,55 @@ yarn add @pikku/schedule
 ```typescript
 import { InMemorySchedulerService } from '@pikku/schedule'
 
-const scheduler = new InMemorySchedulerService()
+const schedulerService = new InMemorySchedulerService()
+await schedulerService.start() // registers a CronJob per wired scheduled task
 ```
 
-Implements the scheduler service interface. Schedules are held in memory — they do not survive process restarts. Suitable for development and single-instance deployments.
+It implements core's `SchedulerService` on two mechanisms: `cron` for the
+recurring tasks you declared with `wireScheduler` (see `pikku-cron`), and
+`setTimeout` for one-off delayed RPCs. Both live in process memory, so nothing
+survives a restart and nothing is shared between instances — fine for
+development and a single-instance deployment, wrong for anything else.
+
+`PikkuTaskScheduler` is a deprecated alias for the same class.
+
+### Scheduling a one-off RPC
+
+```typescript
+const taskId = await schedulerService.scheduleRPC('5m', 'sendReminder', data, session)
+await schedulerService.getTask(taskId) // { rpcName, scheduledFor, status, … } | null
+await schedulerService.getAllTasks() // pending one-offs only
+await schedulerService.unschedule(taskId) // true when it was still pending
+```
+
+The delay is milliseconds or a duration string (`'30s'`, `'5m'`, `'2h'`). This is
+also the mechanism a workflow's delayed steps use, which is why a workflow that
+sleeps needs a `schedulerService` registered.
 
 ## Usage Patterns
 
 ### Basic Setup
 
+The scheduler is a singleton service under the name **`schedulerService`**, and
+it is started in your server bootstrap — declaring it without calling `start()`
+registers no cron jobs, so nothing ever fires:
+
 ```typescript
+// start.ts
 import { InMemorySchedulerService } from '@pikku/schedule'
 
-const createSingletonServices = pikkuServices(async (config) => {
-  const scheduler = new InMemorySchedulerService()
-  return { config, scheduler }
+const schedulerService = new InMemorySchedulerService()
+const singletonServices = await createSingletonServices(config, {
+  schedulerService,
 })
+
+await appServer.start()
+await schedulerService.start()
 ```
 
-For distributed or persistent scheduling, use BullMQ (`BullSchedulerService`) or PgBoss (`PgBossSchedulerService`) from the queue packages instead. See `pikku-queue` for details.
+Call `close()` on shutdown — it stops every cron job and clears pending timers.
+
+For distributed or persistent scheduling, take the scheduler service off the
+queue factory instead (`bullFactory.getSchedulerService()`,
+`pgBossFactory.getSchedulerService()`) and register it under the same name. See
+`pikku-queue`.

package/skills/pikku-schema-ajv/SKILL.md

@@ -40,10 +40,32 @@ const schema = new AjvSchemaService(logger: Logger)
 
 **Methods:**
 
-- `compileSchema(schema: string, value: any): void` — Compile and register a JSON schema
+- `compileSchema(name: string, schema: any): void` — Compile and register a JSON schema under `name`
 - `validateSchema(schemaName: string, json: any): void` — Validate data against a compiled schema (throws on failure)
 - `getSchemaNames(): Set<string>` — Get all registered schema names
-- `getSchemaKeys(schemaName: string): string[]` — Get property keys for a schema
+- `getSchemaKeys(schemaName: string): string[]` — Top-level property keys, or `[]` if the schema has no `properties`
+
+The first argument is the **name**, the second the schema — the parameter is
+called `schema` in the source, which reads backwards.
+
+### Behaviour that matters
+
+- **Registration is name-keyed and never re-compiles.** A second
+  `compileSchema('X', …)` with a different schema is a no-op; the first one wins
+  for the process lifetime. `@pikku/schema-cfworker` *does* recompile on a
+  changed value, so a dev hot-reload after codegen picks up a changed schema
+  there but not here — restart the process instead.
+- **AJV is a module-level singleton**, shared by every `AjvSchemaService` you
+  construct, so compiled schema names are global to the process.
+- **`useDefaults: true` mutates the validated object**, filling in schema
+  defaults in place. `coerceTypes: false`, so a query-string `"1"` will not
+  become `1` — the wiring layer is what coerces, not this service.
+- `ajv-formats` is registered, so `format` keywords (`email`, `uuid`, `date-time`)
+  are enforced.
+- A failed validation throws `UnprocessableContentError` (a 422). A *missing*
+  schema throws a bare string, `Missing validator for <name>` — not an `Error`,
+  so `catch (e) { e.message }` reads `undefined`. That normally means codegen
+  didn't run.
 
 ## Usage Patterns
 

package/skills/pikku-schema-cfworker/SKILL.md

@@ -41,10 +41,30 @@ const schema = new CFWorkerSchemaService(logger: Logger)
 
 **Methods:**
 
-- `compileSchema(schema: string, value: any): void` — Compile and register a JSON schema
+- `compileSchema(name: string, schema: any): void` — Compile and register a JSON schema under `name`
 - `validateSchema(schemaName: string, json: any): void` — Validate data against a compiled schema (throws on failure)
 - `getSchemaNames(): Set<string>` — Get all registered schema names
-- `getSchemaKeys(schemaName: string): string[]` — Get property keys for a schema
+- `getSchemaKeys(schemaName: string): string[]` — Top-level property keys, or `[]` if the schema has no `properties`
+
+### Where it differs from AJV
+
+These two are not drop-in equivalents, and the differences are the kind that
+surface as behaviour changes rather than compile errors:
+
+- **No `useDefaults`.** AJV fills schema defaults into the validated object in
+  place; this validator does not. A field you relied on being defaulted arrives
+  `undefined` on Workers.
+- **It re-compiles when the schema value changes.** AJV caches by name forever;
+  here a `compileSchema` with a different value for the same name replaces the
+  validator, which is what lets a dev hot-reload pick up regenerated schemas.
+- **Each validator gets a deep clone of the schema** (`@cfworker/json-schema`
+  mutates what it is given, which throws on a frozen generated object).
+- A compile failure throws `Error('Failed to compile schema: <name>')` with the
+  underlying cause swallowed — check the schema by hand when you see it.
+
+A failed validation throws `UnprocessableContentError` (422) with the validator
+errors joined; a *missing* schema throws a bare string, `Missing validator for
+<name>`, not an `Error`.
 
 ## Usage Patterns
 

package/skills/pikku-security/SKILL.md

@@ -23,6 +23,10 @@ For **permissions** (pikkuPermission, pikkuAuth, per-function authorization) see
 
 ## Session Management
 
+`session`, `setSession` and `clearSession` live on the **wire** — the function's
+third argument — not on services. `setSession`/`clearSession` may be async
+(cookie and session-store backends write on the way out), so await them.
+
 ```typescript
 // Read session in pikkuFunc (session guaranteed to exist)
 const getProfile = pikkuFunc({
@@ -36,7 +40,7 @@ const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id })
+    await setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })
@@ -44,28 +48,31 @@ const login = pikkuFunc({
 // Clear session (logout)
 const logout = pikkuFunc({
   func: async ({}, _data, { clearSession }) => {
-    clearSession()
+    await clearSession()
   },
 })
 ```
 
+`login` is `auth: false` because the caller has no session yet — a `pikkuFunc`
+with the default `auth` would be rejected before its body ever ran.
+
 ## Built-in Auth Strategies
 
 Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '@pikku/core/http'
+import { addHTTPMiddleware } from '#pikku'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
 
-// Cookie-based sessions — auto-refreshes JWT
+// Cookie-based sessions — re-issues the cookie when the session changes
 addHTTPMiddleware('*', [
   authCookie({
     name: 'session',
     expiresIn: { value: 30, unit: 'day' },
-    options: { httpOnly: true, secure: true },
+    options: { sameSite: 'strict' },
   }),
 ])
 
@@ -73,6 +80,40 @@ addHTTPMiddleware('*', [
 addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
 ```
 
+All three share the same escape hatch: they do nothing when there is no HTTP
+request, or when a session is already set. That is what lets you stack several —
+whichever runs first and finds a credential wins, and the rest step aside — and
+it is also why none of them authenticate a queue job, a scheduled task or a
+channel message. Those need a session set another way.
+
+Each decodes its credential with the `jwt` service; without one registered, they
+silently authenticate nobody.
+
+**`authBearer` in static-token mode.** Passing `token` switches it from decoding
+a JWT to comparing (in constant time) against a fixed value — the shape to use
+for a service-to-service caller or a demo:
+
+```typescript
+authBearer({
+  token: {
+    secretId: 'AGENT_DEMO_TOKEN', // or: value: 'literal-token'
+    userSession: { userId: 'demo-user' },
+  },
+})
+```
+
+An unset secret leaves the middleware inert rather than erroring, so a template
+that ships this is safe until someone provides the secret. A malformed
+`Authorization` header (no `Bearer ` scheme) throws `InvalidSessionError` in
+either mode.
+
+**`authCookie` options.** `name`, `expiresIn` and `options` are all part of the
+config; `options` merges over the defaults `{ httpOnly: true, secure: true,
+sameSite: 'lax', path: '/' }`, so only override what you need. The cookie is
+re-issued after the request only when the session actually changed, which is how
+a rolling session extends itself without writing a `Set-Cookie` on every
+response.
+
 ## Complete Example
 
 ```typescript
@@ -84,10 +125,14 @@ export const isVerified = pikkuAuth(async (_services, session) => !!session?.ema
 
 // wirings/auth.wiring.ts
 import { authCookie } from '@pikku/core/middleware'
-import { addHTTPMiddleware } from '@pikku/core/http'
+import { addHTTPMiddleware } from '#pikku'
 
 addHTTPMiddleware('*', [
-  authCookie({ name: 'session', expiresIn: { value: 30, unit: 'day' } }),
+  authCookie({
+    name: 'session',
+    expiresIn: { value: 30, unit: 'day' },
+    options: {},
+  }),
 ])
 
 // functions/auth.functions.ts
@@ -95,14 +140,14 @@ export const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id })
+    await setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })
 
 export const logout = pikkuFunc({
   func: async ({}, _data, { clearSession }) => {
-    clearSession()
+    await clearSession()
   },
 })
 ```

package/skills/pikku-services/SKILL.md

@@ -2,11 +2,13 @@
 name: pikku-services
 description: >-
   Use when setting up dependency injection, creating custom services, or configuring the service
-  layer in a Pikku app. Covers pikkuServices (singleton), pikkuWireServices (per-request), service
-  typing, built-in services, and tree-shaking. TRIGGER when: code uses
-  pikkuServices/pikkuWireServices, user asks about services.ts, dependency injection, service
-  factories, or built-in services (ConsoleLogger, JoseJWTService). DO NOT TRIGGER when: user asks
-  about auth middleware (use pikku-security) or secrets/variables (use pikku-config).
+  layer in a Pikku app. Covers pikkuServices (singleton), pikkuWireServices (per-request),
+  pikkuServerLifecycle (startup/shutdown hooks), service typing, built-in services, and
+  tree-shaking. TRIGGER when: code uses pikkuServices/pikkuWireServices/pikkuServerLifecycle, user
+  asks about services.ts, lifecycle.ts, dependency injection, service factories, startup or
+  shutdown work, or built-in services (ConsoleLogger, JoseJWTService). DO NOT TRIGGER when: user asks
+  about middleware (use pikku-middleware), auth strategies or sessions (use pikku-security),
+  permissions (use pikku-permissions), or secrets/variables (use pikku-config).
 installGroups: [core]
 ---
 
@@ -74,6 +76,39 @@ export const createWireServices = pikkuWireServices(
 )
 ```
 
+### `pikkuServerLifecycle(hooks)` — startup and shutdown work
+
+A service factory should **construct** services, not run startup side effects. Seeding a database, warming a cache, starting a background consumer or draining a queue belongs in lifecycle hooks, which receive the singleton services after they are built:
+
+```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) // before the port opens
+  },
+  afterStart: async (services) => {
+    await seedDevData(services) // server is accepting traffic
+  },
+  beforeStop: async ({ queueService }) => {
+    await queueService.drain() // services are still alive here
+  },
+  afterStop: async () => {
+    await releaseExternalLock() // services are ALREADY stopped
+  },
+})
+```
+
+Every hook is optional. Order is `beforeStart` → server starts → `afterStart`, then on SIGINT `beforeStop` → services stopped → server stopped → `afterStop`.
+
+**`afterStop` runs after the singleton services have been stopped.** It still receives the services object, but the services inside it are shut down — using one there is a use-after-close bug. Anything that needs a live service goes in `beforeStop`.
+
+Export **exactly one** `pikkuServerLifecycle` from anywhere in `srcDirectories`; the inspector finds it by the wrapper call, so the filename is free (`src/lifecycle.ts` by convention). It must be an exported `const` initialized with a direct call to `pikkuServerLifecycle` — a re-export or a conditional wrapper is invisible to the inspector.
+
+**Only `pikku dev` and `pikku serve` run these hooks.** If you bootstrap your own server (Express, Fastify, uWS, Lambda, Cloudflare, Next.js), no runtime adapter invokes them — put the work in your entrypoint instead.
+
 ### Auto-Generated Service Manifest
 
 After `npx pikku all`, Pikku generates `.pikku/pikku-services.gen.ts`, a manifest of which services are actually used by wired functions:
@@ -97,7 +132,7 @@ export type RequiredSingletonServices = Pick<
 
 ### Using Services in Functions
 
-**Every service must be declared in `SingletonServices` (or `Services`) in `application-types.d.ts`.** Never access a service via a body-level cast (`services as typeof services & { myService: MyService }`) — that means the type is missing. Add the import and the field to `SingletonServices`, then destructure inline in the function signature. The inspector emits `SERVICES_NOT_DESTRUCTURED` and tree-shaking breaks when the first param is a plain identifier rather than an object pattern. Never `new` a service inside a function — services arrive only via injection.
+**Every service must be declared in `SingletonServices` (or `Services`) in `application-types.d.ts`.** Never access a service via a body-level cast (`services as typeof services & { myService: MyService }`) — that means the type is missing. Add the import and the field to `SingletonServices`, then destructure inline in the function signature. The inspector emits `SERVICES_NOT_DESTRUCTURED` (`PKU410`) and tree-shaking breaks when the first param is a plain identifier rather than an object pattern. Never `new` a service inside a function — services arrive only via injection.
 
 ```typescript
 // ✅ Correct — inline destructure, no cast
@@ -122,15 +157,20 @@ const getUser = pikkuFunc({
 
 **Never write a `if (!service) throw ...` existence guard in a function body.** It is dead code, and it defeats the platform.
 
-Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means *"this may not be created"*, not *"this may be missing at call time"*. A service is optional precisely because **nothing destructures it**, and `requireSingletonServices` therefore never creates it. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
+Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means *"this may not be created"*, not *"this may be missing at call time"*. A service is optional precisely because **nothing destructures it**, and the generated `requiredSingletonServices` manifest therefore never marks it for creation. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
 
 The types enforce this rather than merely documenting it. The inspector records the services destructured by every wired `func`, `permissions` **and** `middleware`, and emits them as `RequiredSingletonServices`. The generated function types then default their service parameter to:
 
 ```typescript
 export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
-export type WiredServices = RequiredSingletonServices & Services
+export type WiredServices = SecretlessServices<RequiredSingletonServices & Services>
 ```
 
+The `SecretlessServices<...>` wrapper is why `secrets` never appears in a
+function's services: it is stripped at the type level, not merely omitted by
+convention. Read secrets in a service factory or middleware and hand the value
+to a service instead.
+
 so a service that is `foo?: Foo` in `SingletonServices` arrives as a non-optional `Foo` in every function, permission and middleware that uses it. There is nothing to guard against.
 
 ```typescript
@@ -232,7 +272,7 @@ export const createSingletonServices = pikkuServices(async (config) => {
 
 export const createWireServices = pikkuWireServices(
   async (singletonServices, wire) => ({
-    scopedLogger: new ScopedLogger(wire.session?.initial?.userId),
+    scopedLogger: new ScopedLogger(wire.session?.userId),
   })
 )
 

package/skills/pikku-services/references/audit-wire-service.md

@@ -23,7 +23,8 @@ The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions
 ```typescript
 const deleteUser = pikkuFunc({
   func: async ({ audit }, { userId }) => {
-    await audit.audit({ type: 'user.deleted', actor_user_id: userId })
+    // The user identity comes from the wire session — the payload is metadata.
+    await audit.write({ type: 'user.deleted', source: 'explicit', metadata: { userId } })
     // ...
   },
 })

package/skills/pikku-software-archaeology/README.md

@@ -6,7 +6,7 @@ Reverse-engineers an existing repository into a **Product Blueprint**: the produ
 Existing Repository → pikku-software-archaeology → .knowledge/ blueprint → new Pikku application
 ```
 
-This is **not** a code indexer or doc generator. It extracts *intent over implementation*: `POST /api/users/:id/status` becomes the command `ActivateUser`; three scattered `if (inv.user_id !== req.user.id)` checks become one `InvoiceOwnerOnly` policy with three `enforcedAt` citations.
+This is **not** a code indexer or doc generator. It extracts _intent over implementation_: `POST /api/users/:id/status` becomes the command `ActivateUser`; three scattered `if (inv.user_id !== req.user.id)` checks become one `InvoiceOwnerOnly` policy with three `enforcedAt` citations.
 
 ## Design decision: the AI is the parser
 
@@ -19,8 +19,9 @@ In Claude Code, from (or pointing at) the target repo:
 > Use the pikku-software-archaeology skill to extract a product blueprint from /path/to/repo
 
 The agent then:
+
 1. **Surveys** the repo (manifests, entry points, routes, jobs, webhooks, schema, config, TODO/HACK markers) — facts only.
-2. **Excavates the test suite** — `describe`/`it` names become workflow scenarios; assertions confirm policies and upgrade confidence; rules that exist *only* in tests are captured.
+2. **Excavates the test suite** — `describe`/`it` names become workflow scenarios; assertions confirm policies and upgrade confidence; rules that exist _only_ in tests are captured.
 3. **Extracts** through twelve lenses (domains, entities, commands, …) per the pipeline in `SKILL.md`. Large repos fan out subagents per lens and merge.
 4. **Cross-checks and validates**:
    ```bash
@@ -37,15 +38,23 @@ Concept names are the stable IDs. On re-run after code changes, re-extract only
 
 ## How Pikku consumes the blueprint
 
-Full mapping table in `references/pikku-mapping.md`. Summary: entities → Kysely migrations + Zod schemas; commands/queries → `pikkuFunc`s; api surfaces → `wireHTTP`; policies → shared permission functions (collapsing duplicated legacy checks); system workflows → `wireScheduler`/`wireQueueWorker`/`pikkuWorkflowFunc`; integrations → injected services with `wireSecret`/`wireCredential`; test-derived scenarios → `pikkuUserFlow` stories / e2e tests. Humans resolve `migration.json.decisionsNeeded` before any generation starts.
+Full mapping table in `references/pikku-mapping.md`. Summary: entities → Kysely migrations + Zod schemas; commands/queries → `pikkuFunc`s; api surfaces → `wireHTTP`; policies → shared permission functions (collapsing duplicated legacy checks); system workflows → `wireScheduler`/`wireQueueWorker`/`pikkuWorkflowFunc`; integrations → injected services with `defineSecret`/`defineCredential`; test-derived scenarios → `pikkuUserFlow` stories / e2e tests. Humans resolve `migration.json.decisionsNeeded` before any generation starts.
 
 ## How uncertainty is represented
 
 Every extracted concept carries:
 
 ```json
-{ "evidence": [{ "file": "controllers/invoices.js", "lines": "52", "note": "guard: only drafts editable" }],
-  "confidence": "high" }
+{
+  "evidence": [
+    {
+      "file": "controllers/invoices.js",
+      "lines": "52",
+      "note": "guard: only drafts editable"
+    }
+  ],
+  "confidence": "high"
+}
 ```
 
 - **high** — the behavior itself is in the cited code/schema/test. Generates directly.
@@ -53,7 +62,8 @@ Every extracted concept carries:
 - **low** — plausible reconstruction. Never auto-generated; surfaced for human review.
 
 Two further distinctions keep facts and guesses separate:
-- `events[].explicit: false` — the event was *reconstructed* from side-effect clusters (email + status flip), not emitted by the code.
+
+- `events[].explicit: false` — the event was _reconstructed_ from side-effect clusters (email + status flip), not emitted by the code.
 - Comments/docs vs code: comments describe intent, code describes behavior. Disagreements are recorded as the code's behavior plus a `gaps.json` entry.
 
 ## Repo layout

package/skills/pikku-software-archaeology/references/pikku-mapping.md

@@ -2,36 +2,36 @@
 
 The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pikku primitive. A generator (or an agent following `pikku-feature`) walks the JSON files in this order:
 
-| Blueprint source | Pikku target |
-|---|---|
-| `entities.json` attributes + relationships + constraints | Kysely migrations + generated `DB` types; Zod schemas per entity |
-| `entities.json` states/transitions | a `status` column + transition guards inside the owning commands (or a state-machine helper) |
-| `commands.json` | `pikkuFunc` / `pikkuSessionlessFunc` with `input:` Zod schema built from `input[]`; `preconditions` become guard clauses; name is the camelCased command name (`SendInvoice` → `sendInvoice`) |
-| `queries.json` | `pikkuFunc` reads; `scoping` becomes the mandatory `WHERE` / session filter |
-| `events.json` | EventHub topics (realtime) or queue messages; `consumedBy` become `wireQueueWorker` handlers — implicit events (`explicit: false`) get promoted to real emissions |
-| `policies.json` (authorization) | Pikku `permissions` / middleware; one policy = one named permission function, wired everywhere `enforcedAt` listed — this collapses duplicated legacy checks into a single definition |
-| `policies.json` (validation) | Zod schema refinements on the command's `input` |
-| `workflows.json` kind=user | frontend flows + the commands they chain |
-| `workflows.json` kind=system, with `schedule` | `wireScheduler` entries |
-| `workflows.json` multi-step / checkpointing | `pikkuWorkflowFunc` with one `workflow.do(...)` step per blueprint step |
-| `workflows.json` `scenarios[]` | **`pikkuUserFlow` stories — this is the canonical target.** Each scenario's given/when/outcome maps 1:1 onto a user-flow step sequence; group scenarios by their workflow into one flow per journey. Only scenarios with no user-facing surface (pure system workflows: cron sweeps, webhook ingest) fall back to API/e2e tests |
-| `api.json` | `wireHTTP` routes: keep `path`+`method` for compatibility, point at the mapped command/query func; `auth: none`/capability-URL surfaces get `auth: false` |
-| `api.json` kind=webhook-in | `wireHTTP` with `auth: false` + signature-verification middleware from the integration |
-| `integrations.json` | services in `services.ts` (constructor-injected classes); `configVia` env vars become `wireSecret` / config; per-user credentials become `wireCredential` |
-| `architecture.json` notes | deployment config (ports, raw-body routes, proxy expectations) |
-| `invariants.json` enforcedBy=db-constraint | migration constraints (UNIQUE, CHECK, FK) |
-| `invariants.json` enforcedBy=code-guard/nothing | guard clauses + a test each; `atRiskBecause` entries get a hardening task |
-| `gaps.json` | excluded from generation; `open-product-decision` + `migration.json.decisionsNeeded` go to a human BEFORE generation starts |
-| `migration.json.mappings` | the work plan: one mapping = one migration slice |
-| `interfaces.json` kind=cli | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose |
-| `interfaces.json` kind=mcp | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates) |
-| `interfaces.json` kind=openapi-rest / sdk | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen |
-| `interfaces.json` kind=websocket-realtime | `pikku-realtime` EventHub topics / channels |
-| `frontend.json` | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto |
-| `frontend-routes.json` | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views |
-| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk |
-| `frontend-components.json` rebuild=`custom-logic` | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items |
-| `frontend-components.json` rebuild=`custom-style` | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported |
+| Blueprint source                                                            | Pikku target                                                                                                                                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `entities.json` attributes + relationships + constraints                    | Kysely migrations + generated `DB` types; Zod schemas per entity                                                                                                                                                                                                                                                                |
+| `entities.json` states/transitions                                          | a `status` column + transition guards inside the owning commands (or a state-machine helper)                                                                                                                                                                                                                                    |
+| `commands.json`                                                             | `pikkuFunc` / `pikkuSessionlessFunc` with `input:` Zod schema built from `input[]`; `preconditions` become guard clauses; name is the camelCased command name (`SendInvoice` → `sendInvoice`)                                                                                                                                   |
+| `queries.json`                                                              | `pikkuFunc` reads; `scoping` becomes the mandatory `WHERE` / session filter                                                                                                                                                                                                                                                     |
+| `events.json`                                                               | EventHub topics (realtime) or queue messages; `consumedBy` become `wireQueueWorker` handlers — implicit events (`explicit: false`) get promoted to real emissions                                                                                                                                                               |
+| `policies.json` (authorization)                                             | Pikku `permissions` / middleware; one policy = one named permission function, wired everywhere `enforcedAt` listed — this collapses duplicated legacy checks into a single definition                                                                                                                                           |
+| `policies.json` (validation)                                                | Zod schema refinements on the command's `input`                                                                                                                                                                                                                                                                                 |
+| `workflows.json` kind=user                                                  | frontend flows + the commands they chain                                                                                                                                                                                                                                                                                        |
+| `workflows.json` kind=system, with `schedule`                               | `wireScheduler` entries                                                                                                                                                                                                                                                                                                         |
+| `workflows.json` multi-step / checkpointing                                 | `pikkuWorkflowFunc` with one `workflow.do(...)` step per blueprint step                                                                                                                                                                                                                                                         |
+| `workflows.json` `scenarios[]`                                              | **`pikkuUserFlow` stories — this is the canonical target.** Each scenario's given/when/outcome maps 1:1 onto a user-flow step sequence; group scenarios by their workflow into one flow per journey. Only scenarios with no user-facing surface (pure system workflows: cron sweeps, webhook ingest) fall back to API/e2e tests |
+| `api.json`                                                                  | `wireHTTP` routes: keep `path`+`method` for compatibility, point at the mapped command/query func; `auth: none`/capability-URL surfaces get `auth: false`                                                                                                                                                                       |
+| `api.json` kind=webhook-in                                                  | `wireHTTP` with `auth: false` + signature-verification middleware from the integration                                                                                                                                                                                                                                          |
+| `integrations.json`                                                         | services in `services.ts` (constructor-injected classes); `configVia` env vars become `defineSecret` / config; per-user credentials become `defineCredential`                                                                                                                                                                   |
+| `architecture.json` notes                                                   | deployment config (ports, raw-body routes, proxy expectations)                                                                                                                                                                                                                                                                  |
+| `invariants.json` enforcedBy=db-constraint                                  | migration constraints (UNIQUE, CHECK, FK)                                                                                                                                                                                                                                                                                       |
+| `invariants.json` enforcedBy=code-guard/nothing                             | guard clauses + a test each; `atRiskBecause` entries get a hardening task                                                                                                                                                                                                                                                       |
+| `gaps.json`                                                                 | excluded from generation; `open-product-decision` + `migration.json.decisionsNeeded` go to a human BEFORE generation starts                                                                                                                                                                                                     |
+| `migration.json.mappings`                                                   | the work plan: one mapping = one migration slice                                                                                                                                                                                                                                                                                |
+| `interfaces.json` kind=cli                                                  | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose                                                                                                                                                                                                                                                   |
+| `interfaces.json` kind=mcp                                                  | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates)                                                                                                                                                                                                                        |
+| `interfaces.json` kind=openapi-rest / sdk                                   | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen                                                                                                                                                                                                                    |
+| `interfaces.json` kind=websocket-realtime                                   | `pikku-realtime` EventHub topics / channels                                                                                                                                                                                                                                                                                     |
+| `frontend.json`                                                             | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto                                                                                                                                                        |
+| `frontend-routes.json`                                                      | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views                                                                                                                                         |
+| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk                                                                                                                                                                                                                           |
+| `frontend-components.json` rebuild=`custom-logic`                           | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items                                                                                             |
+| `frontend-components.json` rebuild=`custom-style`                           | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported                                                                                                                                                                                                                                                   |
 
 ## Order of generation
 

package/skills/pikku-template-clone/SKILL.md

@@ -18,11 +18,16 @@ commit, separate from any feature work.
    _template_, not the user's project — leaving it in place is misleading.
    Either delete it (`git rm README.md`) or rewrite it with the new project's
    name and purpose. Never ship a clone with the generic template README.
-2. **Keep the lockfile committed.** Templates ship a committed `yarn.lock`; do
-   NOT re-add `yarn.lock` to `.gitignore`. A real project commits its lockfile
-   for reproducible installs. The correct pattern is `yarn.lock` followed by
-   `!/yarn.lock`, which commits the root lockfile while keeping generated
-   per-unit lockfiles under `.deploy/` (and `e2e/`) ignored.
+2. **Keep the lockfile committed.** Do NOT re-add `yarn.lock` to `.gitignore`.
+   A real project commits its lockfile for reproducible installs. The correct
+   pattern is `yarn.lock` followed by `!/yarn.lock`, which commits the root
+   lockfile while keeping generated per-unit lockfiles under `.deploy/` (and
+   `e2e/`) ignored.
+
+   `create-pikku` keeps only the chosen package manager's lockfile and deletes
+   the other, and for yarn it may have written an **empty** `yarn.lock` as a
+   marker. Commit the lockfile *after* the first install has filled it in —
+   committing the empty placeholder pins nothing.
 3. **Rename template identifiers.** Update `name` in the root `package.json`
    (and any `@project/*` or other placeholder names) to the real project.
 4. **Drop template-only artifacts.** Remove any `TEMPLATE.md`, demo docs, or

package/skills/pikku-trigger/SKILL.md

@@ -35,16 +35,23 @@ See `pikku-concepts` for the core mental model.
 
 ## API Reference
 
+All three come from `#pikku`. A trigger is deliberately split in two: the
+**source** owns the connection to the outside world and the **trigger** names the
+function to run, so one source can be swapped (Redis → PG) without touching the
+handler, and a handler can exist before any source is wired.
+
 ### `wireTrigger(config)`
 
 Define the target function that handles trigger events:
 
 ```typescript
-import { wireTrigger } from '@pikku/core/trigger'
+import { wireTrigger } from '#pikku'
 
 wireTrigger({
   name: string, // Trigger name (matches source)
   func: PikkuFunc, // Function to call when event fires
+  description?: string,
+  tags?: string[],
 })
 ```
 
@@ -53,18 +60,24 @@ wireTrigger({
 Define the event source that fires triggers:
 
 ```typescript
-import { wireTriggerSource } from '@pikku/core/trigger'
+import { wireTriggerSource } from '#pikku'
 
 wireTriggerSource({
-  name: string, // Must match wireTrigger name
-  func: PikkuTriggerFunc, // Source function (sets up listener)
-  input: object, // Configuration for the source
+  name: string, // Must match a wireTrigger name
+  func: PikkuTriggerFunc, // Source function (sets up the listener)
+  input: object, // Configuration handed to the source
 })
 ```
 
+`input` is required whenever the source function declares an input type, and the
+name must be unique — wiring the same source name twice throws
+`Trigger source already exists`.
+
 ### `pikkuTriggerFunc<TInput, TEvent>`
 
-Define a trigger source function. Returns a cleanup function.
+A trigger source function runs **once at startup**, not once per event. It sets
+up a listener, calls `trigger.invoke(...)` for each event it sees, and returns a
+teardown function:
 
 ```typescript
 import { pikkuTriggerFunc } from '#pikku'
@@ -83,6 +96,37 @@ const source = pikkuTriggerFunc<
 })
 ```
 
+It receives **singleton services only** — there is no session, no request and no
+per-wire services, because a listener outlives every event it will ever emit.
+The config-object form (`pikkuTriggerFunc({ func, title, description, tags,
+input, output })`) is also accepted when you want schemas or metadata on the
+source.
+
+## Starting triggers
+
+Nothing fires until a `TriggerService` is started. For a single process,
+`InMemoryTriggerService` walks every wired source that has at least one matching
+target and sets it up:
+
+```typescript
+import { InMemoryTriggerService } from '@pikku/core/services'
+
+const triggerService = new InMemoryTriggerService()
+await triggerService.start()
+// on shutdown
+await triggerService.stop() // runs every source's teardown
+```
+
+A source with no matching `wireTrigger` is logged and skipped rather than
+erroring — the two halves are wired independently, so a half-wired trigger is a
+normal intermediate state.
+
+**If a wiring is silently skipped**, look for
+`Skipping trigger … metadata not found` in the logs. Both wirings read metadata
+generated by the inspector, and it warns rather than throwing; the usual fix is
+the one the warning suggests — move the wiring into its own file so codegen
+picks it up.
+
 ## Usage Patterns
 
 ### Redis Pub/Sub Source