@pikku/skills 0.12.58 → 0.12.60

package/skills/pikku-permissions/SKILL.md

@@ -1,9 +1,13 @@
 ---
 name: pikku-permissions
 description: >-
-  Use when deciding WHO may call a function: resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes and `defineScope`, `addGlobalPermission`, the three gates, `permissionsInBody`, and where ownership belongs versus where it does not.
-  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, about to write an `if` in a function body that decides whether the caller is allowed, or hitting `MissingScopeError`.
-  DO NOT TRIGGER when: the question is how a caller proves who they are, such as sign-in, sessions, tokens, API keys or seeding a virtual user (use pikku-auth), or how to shape a paginated list (use pikku-list-query).
+  Deciding WHO may call a function: resource ownership, role gates, admin-only actions, "only their
+  own rows" rules; the `permissions` field, pikkuPermission, pikkuAuth, scopes/defineScope,
+  addGlobalPermission, permissionsInBody. TRIGGER when: writing or reviewing a function that touches
+  a user-owned row, gating on a role, building the permissions half of a contract in build PHASE 2,
+  about to write an `if` in a body deciding whether the caller is allowed, or hitting
+  MissingScopeError. DO NOT TRIGGER for how a caller proves identity: sign-in, sessions, tokens, API
+  keys, seeding a virtual user (use pikku-auth), or paginated lists (use pikku-list-query).
 installGroups: [core]
 ---
 
@@ -12,7 +16,7 @@ installGroups: [core]
 ## First: is the caller a machine with a token?
 
 Then this is NOT a permissions problem. Resolve the token in `addHTTPMiddleware('*')`
-middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with
+middleware that calls `setInitialSession`, make the function a `pikkuFunc`, and gate it with
 `scopes` (pikku-auth, `../pikku-auth/references/machine-auth.md`). A `permissions` check that verifies a
 bearer token and returns `true` is authentication wearing an authorization hat, and it
 leaves the function sessionless. The only exception is a bootstrap endpoint whose caller
@@ -54,8 +58,8 @@ user's row by passing its id. Every function that takes a row id needs BOTH: `au
 for the session, and a `permissions` entry for the ownership.
 
 Equally: do NOT write an `isSignedIn` permission that returns `!!session`. That re-checks
-authentication, which `auth: true` already did. A permission answers *may this user do
-this* — role, ownership, tier — never *is there a session*.
+authentication, which `auth: true` already did. A permission answers _may this user do
+this_ — role, ownership, tier — never _is there a session_.
 
 ## Single row vs list — where ownership actually goes
 
@@ -88,11 +92,13 @@ export const isBookOwner = pikkuPermission(
       .where('bookId', '=', bookId)
       .executeTakeFirst()
     return book?.ownerId === session?.userId
-  },
+  }
 )
 
 // Session-only: no input needed. Use for role and flag gates.
-export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
+export const isAdmin = pikkuAuth(
+  async (_services, session) => session?.role === 'admin'
+)
 ```
 
 ## OR and AND

package/skills/pikku-react/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: pikku-react
 description: >-
-  Use when a React frontend talks to a Pikku backend — PikkuProvider and createPikku at the app
-  root, the generated React Query hooks (usePikkuQuery, usePikkuMutation, usePikkuInfiniteQuery),
-  direct usePikkuRPC / usePikkuFetch calls, realtime subscriptions, and agent and workflow hooks. TRIGGER when: writing a React component that fetches or mutates backend
-  data, wiring PikkuProvider, paginating, running or tracking a workflow from the client. DO NOT TRIGGER when: working on the
-  backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), rendering fetched values such as
-  dates (use pikku-tailwind), or writing user-facing copy (use pikku-i18n).
+  React frontend talking to a Pikku backend: PikkuProvider/createPikku, generated React Query hooks
+  (usePikkuQuery, usePikkuMutation, usePikkuInfiniteQuery), usePikkuRPC/usePikkuFetch, realtime
+  subscriptions, agent and workflow hooks. TRIGGER when: writing a React component that fetches or
+  mutates backend data, wiring PikkuProvider, paginating, or running/tracking a workflow from the
+  client. DO NOT TRIGGER for backend work (use pikku-wiring), defining the workflow (use
+  pikku-workflow), rendering fetched values such as dates (use pikku-tailwind) or user-facing copy
+  (use pikku-i18n).
 installGroups: [client]
 ---
 

package/skills/pikku-realtime/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: pikku-realtime
 description: >-
-  Use when making a view live in a Pikku app — a board, shared list, dashboard, ticker, bidding
-  room, live count — or when adding two-way chat or presence. Covers the default event-hub SSE path
-  (`eventHub.publish` on the backend, `PikkuRealtime.subscribeToTopic` on the client) and the
-  two-way WebSocket channel. TRIGGER when: the user wants live updates, realtime, "update without
-  refresh", a live board/feed/ticker/room, presence or chat, or data that more than one signed-in
-  user can change should reflect to others. DO NOT TRIGGER when: a one-shot query/refetch is enough
-  (data only one user changes, or a manual refresh is acceptable), for background jobs (use
-  pikku-workflow, or pikku-wiring's queue and scheduler references), or for the full wiring
-  reference of channels, SSE routes and the `/events` scaffold (use pikku-wiring).
+  Making a view live in a Pikku app (board, shared list, dashboard, ticker, bidding room, live
+  count) or adding two-way chat/presence: the default event-hub SSE path (`eventHub.publish`,
+  `PikkuRealtime.subscribeToTopic`) and the WebSocket channel. TRIGGER when: asked for live updates,
+  realtime, "update without refresh", presence or chat, or data several signed-in users can change
+  should reflect to others. DO NOT TRIGGER when a one-shot refetch is enough, for background jobs
+  (use pikku-workflow, or pikku-wiring's queue/scheduler references), or for the full
+  channel/SSE/`/events` wiring reference (use pikku-wiring).
 installGroups: [core, client]
 ---
 
@@ -115,8 +113,15 @@ import { pikkuChannelFunc, wireChannel } from '#pikku/channel'
 
 export const onMessage = pikkuChannelFunc<{ text: string }>({
   func: async ({ eventHub }, input, { channel, session }) => {
-    const message = { id: crypto.randomUUID(), text: input.text, userId: session!.userId }
-    await eventHub.publish('room', channel.channelId, { topic: 'room', data: message })
+    const message = {
+      id: crypto.randomUUID(),
+      text: input.text,
+      userId: session!.userId,
+    }
+    await eventHub.publish('room', channel.channelId, {
+      topic: 'room',
+      data: message,
+    })
     return message
   },
 })

package/skills/pikku-report/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: pikku-report
 description: >-
-  Use when pikku itself cost you time — wrong generated types, a check that passes when it should
-  not, output that is quietly wrong, a skill that misled you — or when the user asks you to report
-  a framework bug or file a finding. Owns `pikku cloud report` (a finding is about pikku, not the
-  app), the product-vs-harness kinds, the workaround-first ladder, and asking the user at hand-over
-  whether to send what was filed. TRIGGER when: the framework fought you, codegen produced
-  something broken, a skill told you to run something that does not exist, the user says "report
-  this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug
-  is in the app you are building (fix it there), you are debugging a deployed stage,
-  or you are tempted to patch pikku's source (never do that from an app).
+  Reporting Pikku itself when it cost you time (wrong generated types, a check that passes when it
+  should not, quietly wrong output, a misleading skill) or when asked to file a framework bug:
+  `pikku cloud report`, product-vs-harness kinds, the workaround-first ladder, asking the user at
+  hand-over whether to send findings. TRIGGER when: the framework fought you, codegen is broken, a
+  skill told you to run something that does not exist, the user says "report this to pikku" / "file
+  a finding", or you are handing over a build. DO NOT TRIGGER for bugs in the app you are building,
+  debugging a deployed stage, or patching pikku's source (never from an app).
 installGroups: [core]
 ---
 
@@ -62,7 +60,7 @@ baseline noise that was already failing before you started.
 - `--kind harness` — a skill misled you: it told you to run something that does
   not exist, described a flag that is spelled differently, or contradicted what
   the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
-  section>"`. This is the most useful kind to file, because it is fixable
+section>"`. This is the most useful kind to file, because it is fixable
   immediately — so file it even when the cost was small.
 
 ## The command

package/skills/pikku-scenario/SKILL.md

@@ -1,18 +1,14 @@
 ---
 name: pikku-scenario
 description: >-
-  Use when writing or running Pikku scenarios, running a virtual user against a stage, or when
-  asked to test Pikku functions or improve coverage. A scenario (pikkuScenario) drives the app
-  the way users do — steps run as virtual users over the real transport against a running server — so a
-  flow doubles as an e2e test and a staged/production health check. Covers scenario.do /
-  expectEventually / expectError / expectService / expectScore, declared steps via
-  pikkuScenarioStep (browser steps driven by @pikku/playwright) written as intent rather than
-  clicks, virtual users / virtual users / environments in pikku.config.json, VIRTUAL_USER_SIGNING_KEY, the
-  `pikku scenario` and `pikku virtual-user` commands, and live coverage
-  via `pikku dev --coverage`. TRIGGER when: user asks about scenarios, testing a Pikku function,
-  coverage, e2e flows, browser/UI e2e, health checks, virtual users, or adversarial
-  runs against a stage. DO NOT TRIGGER when: user asks about running an existing suite (use
-  Bash) or CI config.
+  Writing and running Pikku scenarios (pikkuScenario): virtual users drive the app over the real
+  transport, so a flow doubles as an e2e test and a stage/production health check. Covers
+  scenario.do/expectEventually/expectError/expectService/expectScore, pikkuScenarioStep (Playwright
+  browser steps), virtual users and environments in pikku.config.json, VIRTUAL_USER_SIGNING_KEY,
+  `pikku scenario`/`pikku virtual-user`, coverage via `pikku dev --coverage`. TRIGGER when: asked
+  about scenarios, testing a Pikku function, coverage, e2e or browser flows, health checks, virtual
+  users or adversarial stage runs. DO NOT TRIGGER for running an existing suite (use Bash) or CI
+  config.
 installGroups: [core]
 ---
 

package/skills/pikku-scenario/references/steps.md

@@ -358,10 +358,9 @@ is the app's language, not the team's. Ask, or leave it `en`.
 
 **Where a non-`en` `metaLocale` still shows English, today.** The reporter composes a
 sentence as `<Keyword> <virtual user> <template>` (`composeStepProse`), and the keyword is
-an English literal. The Console translates the Given/When/Then keywords into its own
-UI language; the CLI reporter does not, so `metaLocale: "de"` gives you German step
+an English literal. The CLI reporter does not translate the Given/When/Then keywords, so `metaLocale: "de"` gives you German step
 prose inside an English frame — `Given shopper kauft 1 Äpfel`. Write templates that read
 acceptably in that frame rather than trying to defeat it. A second gap: where a
-function or scenario declares no `title`, the Console falls back to splitting the
-**identifier** into an English-looking label (`toEnglishName`), so under a
+function or scenario declares no `title`, the label falls back to splitting the
+**identifier** into English words (`toEnglishName`), so under a
 non-`en` `metaLocale` meta is worth authoring rather than leaving to the fallback.

package/skills/pikku-scenario/references/virtual-users.md

@@ -47,7 +47,7 @@ harmless but worth knowing before you align it to the surrounding code.
 One more thing worth knowing before writing a rich virtual user: **`virtualUser.converse`
 builds its prompt from `name`, `jobTitle`, `personality` and the scenario's
 `task` only.** Fields like `disposition`, `goals` and `roles` are read and
-stored, and the console shows them, but they do not reach the conversing
+stored, but they do not reach the conversing
 virtual user's instructions. Anything that must shape how someone talks belongs in
 `personality` or in the task.
 

package/skills/pikku-seo/SKILL.md

@@ -1,9 +1,12 @@
 ---
 name: pikku-seo
 description: >-
-  On-page SEO rules for the app's PUBLIC pages: per-route head() titles and meta descriptions, Open Graph tags, crawlable links and URLs, JSON-LD on the landing page, and noindex for the logged-in area.
-  TRIGGER when: building or reworking any public page (landing, pricing, about, blog/content pages), writing page titles or meta tags, or the user asks about SEO / Google / discoverability / social sharing previews.
-  DO NOT TRIGGER when: the task is accessibility, including heading order, landmarks or alt text (use pikku-a11y), or working on logged-in /app screens (they are noindexed — only the one robots rule below applies), backend functions, database, or deployment.
+  On-page SEO for the app's PUBLIC pages: per-route head() titles and meta descriptions, Open Graph,
+  crawlable links/URLs, landing-page JSON-LD, noindex for the logged-in area. TRIGGER when: building
+  or reworking a public page (landing, pricing, about, blog), writing page titles or meta tags, or
+  asked about SEO, Google, discoverability or social share previews. DO NOT TRIGGER for
+  accessibility incl. heading order, landmarks, alt text (use pikku-a11y), logged-in /app screens
+  (noindexed; only the one robots rule applies), backend, database or deployment.
 installGroups: [client]
 ---
 
@@ -31,7 +34,10 @@ export const Route = createFileRoute('/pricing')({
           'Simple per-seat pricing for Acme Scheduling. Start free, upgrade when your team grows — no setup fees, cancel anytime.',
       },
       { property: 'og:title', content: 'Pricing — Acme Scheduling' },
-      { property: 'og:description', content: 'Simple per-seat pricing. Start free.' },
+      {
+        property: 'og:description',
+        content: 'Simple per-seat pricing. Start free.',
+      },
     ],
   }),
   component: PricingPage,
@@ -90,16 +96,18 @@ or offers (fake schema is a Google penalty, not a boost):
 
 ```tsx
 head: () => ({
-  meta: [
-    /* title + description as above */
-  ],
+  meta: [/* title + description as above */],
   scripts: [
     {
       type: 'application/ld+json',
       children: JSON.stringify({
         '@context': 'https://schema.org',
         '@graph': [
-          { '@type': 'Organization', name: 'Acme Scheduling', description: '…' },
+          {
+            '@type': 'Organization',
+            name: 'Acme Scheduling',
+            description: '…',
+          },
           { '@type': 'WebSite', name: 'Acme Scheduling' },
         ],
       }),

package/skills/pikku-service-backends/SKILL.md

@@ -1,16 +1,14 @@
 ---
 name: pikku-service-backends
 description: >-
-  Use when picking or wiring a backend for one of Pikku's core service interfaces — ContentService
-  (S3, Backblaze B2), QueueService (SQS), SecretService (AWS Secrets Manager, Redis, MongoDB),
-  SchemaService (AJV, cfworker), ChannelStore, EventHubStore, WorkflowService, SessionStore or
-  AgentRunService (Redis, MongoDB). Covers which backend to choose, what each one silently does
-  differently, and the failures they swallow. TRIGGER when: code uses S3Content, B2Content,
-  SQSQueueService, AWSSecrets, RedisChannelStore, RedisSecretService, MongoDBChannelStore,
-  PikkuMongoDB, AjvSchemaService or CFWorkerSchemaService, or the user asks how to store files,
-  secrets, channel state or sessions. DO NOT TRIGGER when: defining service factories themselves
-  (use pikku-services), SQL via Kysely (use pikku-kysely), or the Lambda/Cloudflare runtimes
-  themselves (use pikku-deploy).
+  Picking or wiring a backend for Pikku's core service interfaces: ContentService (S3, B2),
+  QueueService (SQS), SecretService (AWS Secrets Manager, Redis, MongoDB), SchemaService (AJV,
+  cfworker), ChannelStore, EventHubStore, WorkflowService, SessionStore, AgentRunService (Redis,
+  MongoDB). Covers which to choose, silent differences, swallowed failures. TRIGGER when: code uses
+  S3Content, B2Content, SQSQueueService, AWSSecrets, Redis*/MongoDB* stores, PikkuMongoDB,
+  AjvSchemaService or CFWorkerSchemaService, or asked how to store files, secrets, channel state or
+  sessions. DO NOT TRIGGER for defining service factories (use pikku-services), Kysely SQL (use
+  pikku-kysely) or the Lambda/Cloudflare runtimes (use pikku-deploy).
 installGroups: [core]
 ---
 
@@ -26,17 +24,17 @@ behind the interface.
 
 ## Pick a backend
 
-| Interface | Backends | Package |
-| --- | --- | --- |
-| `ContentService` | `S3Content`, `B2Content` | `@pikku/aws-services`, `@pikku/backblaze` |
-| `QueueService` | `SQSQueueService` | `@pikku/aws-services` |
-| `SecretService` | `AWSSecrets`, `RedisSecretService`, `MongoDBSecretService` | `@pikku/aws-services`, `@pikku/redis`, `@pikku/mongodb` |
-| `SchemaService` | `AjvSchemaService`, `CFWorkerSchemaService` | `@pikku/schema-ajv`, `@pikku/schema-cfworker` |
-| `ChannelStore`, `EventHubStore` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
-| `PikkuWorkflowService`, `WorkflowRunService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
-| `SessionStore`, `AgentRunService`, `DeploymentService` | Redis, MongoDB | `@pikku/redis`, `@pikku/mongodb` |
-| `AgentStorageService`, `AgentRunStateService` | MongoDB **only** | `@pikku/mongodb` |
-| `LeaseService` | `RedisLeaseService` | `@pikku/redis` |
+| Interface                                              | Backends                                                   | Package                                                 |
+| ------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------- |
+| `ContentService`                                       | `S3Content`, `B2Content`                                   | `@pikku/aws-services`, `@pikku/backblaze`               |
+| `QueueService`                                         | `SQSQueueService`                                          | `@pikku/aws-services`                                   |
+| `SecretService`                                        | `AWSSecrets`, `RedisSecretService`, `MongoDBSecretService` | `@pikku/aws-services`, `@pikku/redis`, `@pikku/mongodb` |
+| `SchemaService`                                        | `AjvSchemaService`, `CFWorkerSchemaService`                | `@pikku/schema-ajv`, `@pikku/schema-cfworker`           |
+| `ChannelStore`, `EventHubStore`                        | Redis, MongoDB                                             | `@pikku/redis`, `@pikku/mongodb`                        |
+| `PikkuWorkflowService`, `WorkflowRunService`           | Redis, MongoDB                                             | `@pikku/redis`, `@pikku/mongodb`                        |
+| `SessionStore`, `AgentRunService`, `DeploymentService` | Redis, MongoDB                                             | `@pikku/redis`, `@pikku/mongodb`                        |
+| `AgentStorageService`, `AgentRunStateService`          | MongoDB **only**                                           | `@pikku/mongodb`                                        |
+| `LeaseService`                                         | `RedisLeaseService`                                        | `@pikku/redis`                                          |
 
 SQL is the third option for every store interface in that table —
 `KyselyChannelStore`, `KyselyWorkflowService`, `KyselySecretService` and friends
@@ -79,12 +77,12 @@ wrapper has to be constructed and initialised before any of them.
 
 Where they diverge:
 
-| | `S3Content` | `B2Content` |
-| --- | --- | --- |
-| Signing failure | **Fails open** — logs and returns the *unsigned* URL | Throws |
-| `writeFile` memory | Streams | **Buffers the whole stream** to compute a SHA-1 |
-| Client-side upload integrity | Presigned, expires at a fixed 3600s | `X-Bz-Content-Sha1: do_not_verify` — unverified |
-| Credential rotation | Picked up by the SDK provider chain | Auth is cached for the instance's lifetime — construct a new `B2Content` |
+|                              | `S3Content`                                          | `B2Content`                                                              |
+| ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
+| Signing failure              | **Fails open** — logs and returns the _unsigned_ URL | Throws                                                                   |
+| `writeFile` memory           | Streams                                              | **Buffers the whole stream** to compute a SHA-1                          |
+| Client-side upload integrity | Presigned, expires at a fixed 3600s                  | `X-Bz-Content-Sha1: do_not_verify` — unverified                          |
+| Credential rotation          | Picked up by the SDK provider chain                  | Auth is cached for the instance's lifetime — construct a new `B2Content` |
 
 The S3 fail-open is the one to design around: on a private CloudFront
 distribution the client gets a 403, and on a public one you have just handed out
@@ -119,7 +117,7 @@ Swapping them changes behaviour without changing types:
   becomes `1` in the wiring layer, not here.
 
 Both throw `UnprocessableContentError` (422) on a failed validation, and both
-throw a **bare string** — `Missing validator for <name>` — for a *missing*
+throw a **bare string** — `Missing validator for <name>` — for a _missing_
 schema. It is not an `Error`, so `catch (e) { e.message }` reads `undefined`.
 That almost always means codegen did not run.
 

package/skills/pikku-services/SKILL.md

@@ -1,15 +1,14 @@
 ---
 name: pikku-services
 description: >-
-  Use for the service layer of a Pikku app — dependency injection with pikkuServices and
-  pikkuWireServices, startup/shutdown work with pikkuServerLifecycle, configuration through the
-  secrets, variables and credentials services, the audit sink and buffer, and structured logging.
-  TRIGGER when: code uses pikkuServices/pikkuWireServices/pikkuServerLifecycle, defineSecret,
-  defineVariable or defineCredential, user asks about services.ts, lifecycle.ts, dependency
-  injection, env vars, secrets, API credentials, audit logging, AuditService, PinoLogger, or a
-  built-in service. DO NOT TRIGGER when: user asks about middleware (use pikku-middleware),
-  authentication or permissions (use pikku-auth), or a third-party backend such as Redis, S3 or
-  MongoDB (use pikku-service-backends).
+  The Pikku service layer: dependency injection with pikkuServices/pikkuWireServices,
+  startup/shutdown via pikkuServerLifecycle, config through the secrets, variables and credentials
+  services, audit sink and buffer, structured logging. TRIGGER when: code uses
+  pikkuServices/pikkuWireServices/pikkuServerLifecycle/defineSecret/defineVariable/defineCredential,
+  or asked about services.ts, lifecycle.ts, DI, env vars, secrets, API credentials, audit logging,
+  PinoLogger or a built-in service. DO NOT TRIGGER for middleware (use pikku-middleware),
+  authentication or permissions (use pikku-auth), or third-party backends such as Redis, S3, MongoDB
+  (use pikku-service-backends).
 installGroups: [core]
 ---
 

package/skills/pikku-services/references/services.md

@@ -63,7 +63,7 @@ A service factory should **construct** services, not run startup side effects. S
 
 ```typescript
 // src/lifecycle.ts
-import { pikkuServerLifecycle } from '@pikku/core'
+import { pikkuServerLifecycle } from '@pikku/core/lifecycle'
 import type { SingletonServices } from '../types/application-types.js'
 
 export const lifecycle = pikkuServerLifecycle<SingletonServices>({

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

@@ -38,7 +38,7 @@ 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 `defineSecret`/`defineCredential`; 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 → `pikkuScenario` / `pikkuFeature` (see `references/tests-to-scenarios.md`). Humans resolve `migration.json.decisionsNeeded` before any generation starts.
 
 ## How uncertainty is represented
 
@@ -75,6 +75,8 @@ pikku-software-archaeology/
 ├── references/
 │   ├── blueprint.schema.json         # the output contract (JSON Schema)
 │   ├── pikku-mapping.md              # blueprint → Pikku primitives
+│   ├── tests-to-scenarios.md         # legacy test suite → blueprint scenarios → pikkuScenario
+│   ├── sources/                      # per-framework guides: rails, laravel, nestjs, express
 │   ├── second-opinion.md             # blueprint → owner-facing report: method, voice, red flags
 │   └── second-opinion-report-template.md  # the layered structure to fill in
 ├── example/
@@ -82,3 +84,12 @@ pikku-software-archaeology/
 └── scripts/
     └── validate.mjs                  # schema + cross-file validation (node, no deps)
 ```
+
+## Backlog: real-app test runs
+
+The framework guides in `references/sources/` are written from general knowledge of each framework and have not been run against a real codebase yet. Run the skill on these, scoped to one slice each (not the whole repo), clone into a scratch directory rather than a pikku repo, and fix whatever the guides miss:
+
+- **Redmine** (Rails, issue tracker, ~2006): the hardest test of `sources/rails.md` — callbacks, workflow states, plugins. Scope to issues + workflow transitions.
+- **Immich** (NestJS, photo backend): exercises `sources/nestjs.md` — guards, cron/queues, event handlers. Scope to one domain (e.g. albums or sharing).
+
+Things to check on each run: implicit events found, validator passes, which grep patterns in the guide come up empty, and how `tests-to-scenarios.md` handles the repo's own suite.

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

@@ -75,7 +75,14 @@ Build an inventory before interpreting anything:
 - TODO / FIXME / HACK / XXX / deprecated markers — each is a gaps.json candidate.
 - **The test suite** — locate it now, excavate it in Phase 2.
 
-Where intent hides, per ecosystem (read these first):
+**Framework guides.** Once you know the framework, read its guide before extracting. Each lists where intent hides, how its idioms map to blueprint concepts, the traps, and a grep checklist. Read only the ones that apply:
+
+- Rails: `references/sources/rails.md`
+- Laravel: `references/sources/laravel.md`
+- NestJS: `references/sources/nestjs.md`
+- Express (also the approach for Koa/Fastify/Hono): `references/sources/express.md`
+
+Other ecosystems fall back to this table. Where intent hides, per ecosystem (read these first):
 
 | Ecosystem                 | Highest-yield locations                                                                                                                                                                                                                                                                                                                  |
 | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -91,7 +98,7 @@ Where intent hides, per ecosystem (read these first):
 Tests are the closest thing to an executable product spec. For every test file:
 
 - `describe`/`context`/`it` names → **scenarios** (attach to the matching workflow in `workflows.json` under `scenarios[]`, with `fromTest` set).
-- User-flow/journey harnesses (`pikkuUserFlow` stories, `.feature` files, Playwright journeys) are the highest-grade scenario source — they already ARE given/when/outcome sequences; extract them verbatim.
+- Journey harnesses (`pikkuScenario` flows, `.feature` files, Playwright/Capybara journeys, request/feature/e2e specs) are the highest-grade scenario source — they already ARE given/when/outcome sequences; extract them verbatim. Triage every test by kind first: see `references/tests-to-scenarios.md`.
 - Assertions → confirmations of policies and invariants (upgrade their `confidence` to `high`, add the test as evidence).
 - Fixtures/factories → entity attribute shapes and realistic example data.
 - Edge-case tests → business rules that exist **nowhere else in the code** (e.g. "replayed webhook events are idempotent" may only be stated in a test).

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

@@ -14,7 +14,7 @@ The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pi
 | `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 |
+| `workflows.json` `scenarios[]`                                              | **`pikkuScenario` + `pikkuFeature` — this is the canonical target** (`pikkuUserFlow` was renamed to scenario in #862). Each blueprint scenario's given/when/outcome maps onto `scenario.given/when/then` steps; group by workflow into one scenario per journey and by domain into a `pikkuFeature`. Pure system workflows (cron sweeps, webhook ingest) are still scenarios: fire them with `scenario.runScheduledTask` or the webhook route, then `expectEventually`. See `tests-to-scenarios.md` |
 | `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`                                                                                                                                                                   |

package/skills/pikku-software-archaeology/references/sources/express.md

@@ -0,0 +1,75 @@
+# Source guide: Express (Node.js)
+
+Read this when the survey finds `express` in `package.json`. Express has no conventions, so every Express app is its own framework. The same product can be one 3,000-line `server.js` or a layered app that imitates Nest. Your job is to find which, then trace the request path by hand. The same approach works for Koa, Fastify and Hono; adjust the registration syntax.
+
+## Detect
+
+`express` in dependencies, `app.listen`, `express.Router()`. Note the module system (CJS vs ESM), TypeScript or not, the ORM or query layer (Prisma, Sequelize, Knex, Mongoose, raw `pg`/`mysql2`), the session/auth approach (Passport, JWT, express-session) and the entry point named in `package.json` `main`/`scripts.start`.
+
+## Where intent hides
+
+Start at the entry file and follow `app.use`. **Order is behavior**: middleware registered before a route applies to it, middleware registered after does not.
+
+| Location                                                                  | Blueprint concept                                                 |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| entry file (`app.js`, `server.js`, `index.js`, `src/app.ts`): every `app.use` in order | global middleware chain, raw-body routes, CORS, mounts, architecture constraints |
+| `routes/`, `routers/`, `api/`: `router.get/post/...`, `app.route()`       | api surfaces; track the mount prefix (`app.use('/v1/invoices', r)`) |
+| auth middleware (`requireAuth`, `isAdmin`, `passport.authenticate`, `jwt.verify`) | authorization policies; note which routes use it and which do not |
+| handlers/controllers: inline `if (...) return res.status(4xx)`            | preconditions and policies (every guard is one)                   |
+| validation: `joi`, `zod`, `yup`, `express-validator`, `celebrate`, hand-rolled `if (!req.body.x)` | command `input[]` + validation policies          |
+| models: Mongoose schemas, Sequelize models, Prisma schema, SQL files, migrations (`knex`, `umzug`), or raw SQL strings | entities, constraints          |
+| `services/`, `lib/`, `utils/`, `helpers/`                                 | business logic; the real commands usually live here               |
+| `jobs/`, `workers/`, `cron/`, `node-cron`, `agenda`, `bull`/`bullmq`, `setInterval` at module scope | system workflows            |
+| webhook routes (`/webhooks/stripe`, signature checks, `express.raw`)      | integration ingress; command + signature policy                   |
+| `socket.io` / `ws` setup                                                  | realtime interface                                                |
+| `process.env.*`, `config/`, `dotenv`                                      | integrations, toggles, deployment constraints                     |
+| `test/`, `__tests__/`, `*.test.js` (supertest/jest/mocha)                 | scenarios; edge cases not in the code                             |
+
+## Idiom -> blueprint -> Pikku
+
+| Express idiom                                         | Blueprint concept                                  | Pikku shortcut                                         |
+| ----------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------ |
+| `router.post('/:id/send', auth, handler)`             | command (`SendInvoice`), not "POST /:id/send"      | `pikkuFunc` + `wireHTTP` keeping path for compatibility |
+| `router.use(requireAuth)` before a set of routes      | authorization policy `enforcedAt` each route in scope | auth by default; list public routes explicitly      |
+| `if (resource.userId !== req.user.id) return 403`     | ownership policy, repeated per handler             | one named permission function, wired everywhere        |
+| `req.body` hand-checks / Joi schema                   | `input[]` + validation policy                      | Zod schema                                             |
+| `res.status(409)` on duplicate / state conflict       | precondition on entity state                       | guard clause inside the func                           |
+| `await sendEmail(...)` at the end of a handler        | **implicit event consumer**                        | emit event, consumer in `wireQueueWorker`              |
+| `setTimeout`/`setInterval`/`node-cron` in module scope | system workflow (often undocumented)              | `wireScheduler`                                        |
+| `emitter.emit/on` (`EventEmitter`)                    | in-process event (not durable)                     | EventHub / queue; note the lost-on-crash gap           |
+| Mongoose/Sequelize hooks (`pre('save')`, `beforeCreate`) | implicit events / validation                    | explicit step in command                               |
+| `express.raw()` / `bodyParser.raw` for one route      | deployment constraint (signature verification)     | raw-body config on that `wireHTTP` route               |
+| `app.use(express.static)` + SPA fallback              | frontend hosting                                   | separate deploy / TanStack Start                       |
+| `res.render` (EJS/Pug/Handlebars)                     | server-rendered frontend (see SKILL.md note)       | TanStack route + `usePikkuQuery`                       |
+| `req.session` / `req.user` set by Passport            | session model                                      | Pikku session                                          |
+
+## Traps
+
+- **Public by omission.** The unguarded route is the default. Build a table of every route vs which middleware applies and look for ones that have none; the legacy apps that "have auth" often have three unguarded admin endpoints. Each is a gaps.json security entry.
+- **Middleware order bugs.** A route registered before `app.use(auth)` is public even though it sits in the same file. Read order top to bottom, with mounts.
+- **`next(err)` and the error handler** define the real error contract (status codes, shapes). Read the final `app.use((err, req, res, next) => ...)` and record the mapping.
+- **Business logic in handlers.** If no service layer exists, the handler IS the command: its guards, DB writes, side effects and response form one concept. Name it from the effect.
+- **Duplicated handlers.** Copy-pasted routes (`/v1` and `/v2`, or admin and user versions) that drifted. List both, flag the difference as a gap.
+- **Hidden writers.** Several routes and a cron job may all write one status column. Grep the column to find every transition, as with Rails.
+- **Callbacks and fire-and-forget.** `doThing().catch(console.error)` without `await` means a side effect that can fail silently: an invariant with `enforcedBy: nothing`.
+- **Tenancy by hand.** Whether `WHERE tenant_id = req.user.tenantId` appears on every query is the question. Missing on one is a gap.
+- **Mongo and loose schemas.** With schemaless data, the entity shape is spread across writers. Reconstruct attributes from schemas, fixtures and serializers, and say which are optional in practice.
+- **Env-driven branches** (`if (process.env.NODE_ENV === 'production')`, feature flags): record the flag and the behavior difference.
+- **Monolith with many entry points**: `server.js`, `worker.js`, `cron.js`, `scripts/`. Each runnable is a component in `architecture.json`.
+
+## Search checklist
+
+```
+grep -rnE "app\.use\(|router\.use\(" .          # middleware + mounts, in file order
+grep -rnE "(app|router)\.(get|post|put|patch|delete|all|route)\(" --include=*.{js,ts} .
+grep -rnE "status\((401|403|404|409|422)\)" --include=*.{js,ts} .   # guards = policies
+grep -rnE "req\.user|req\.session|req\.auth" --include=*.{js,ts} .
+grep -rnE "setInterval|setTimeout\(.*[0-9]{4,}|cron\.schedule|new CronJob|agenda\.define|\.process\(" .
+grep -rnE "express\.raw|bodyParser\.raw|stripe\.webhooks|constructEvent|createHmac" .
+grep -rnE "emit\(|\.on\('" --include=*.{js,ts} .
+grep -rnE "process\.env\.[A-Z_]+" -o --include=*.{js,ts} . | sort | uniq -c | sort -rn
+```
+
+## Confidence notes
+
+Behavior in a handler plus a supertest scenario is `high`. A rule that only appears in one route of several similar ones is `medium` (decide whether the others should have it, and record the decision needed). Because there is no declarative structure, expect more `medium` than in Nest, and prefer a short `decisionsNeeded` list over guessing.