@pikku/skills 0.12.57 → 0.12.59

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]
 ---
 
@@ -31,13 +27,13 @@ installGroups: [core]
 This skill covers writing and running scenarios end to end. Five topics are one level down, and
 each says when to open it:
 
-| Read                             | For                                                                                                                                 |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `references/steps.md`            | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given                                                           |
-| `references/browser.md`          | Browser bindings, and locating by message key in a translated app                                                                   |
+| Read                             | For                                                                                                                               |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `references/steps.md`            | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given                                                         |
+| `references/browser.md`          | Browser bindings, and locating by message key in a translated app                                                                 |
 | `references/virtual-users.md`    | Virtual users vs virtual users, `defineVirtualUsers`, upstream credentials for virtual users, and human sign-in as a virtual user |
-| `references/coverage.md`         | Live coverage, filling it, and unit tests for pure logic                                                                            |
-| `references/virtual-user-run.md` | Running a model-driven virtual user against a stage                                                                                 |
+| `references/coverage.md`         | Live coverage, filling it, and unit tests for pure logic                                                                          |
+| `references/virtual-user-run.md` | Running a model-driven virtual user against a stage                                                                               |
 
 ## What a scenario is
 
@@ -321,6 +317,7 @@ pikku scenario run local --spawn --exclude-tags ai-live
 | `--api-url` / `--app-url`  | Override the environment's URLs — for a target that only exists at run time       |
 | `--trace`                  | Keep every stack frame on failure (default shows only the project's own)          |
 | `--coverage`               | Reset/snapshot server coverage per scenario                                       |
+| `--run-id <id>`            | Record the run under this id rather than a fresh one, so a caller can follow it   |
 
 Output is `PASS <name> (<ms>) → <output>` / `FAIL <name> (<ms>): <error>`, then `N/M scenarios passed against '<env>'`. A scenario inside a feature is named `<Feature> › <scenario> <data>`.
 

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.

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

@@ -0,0 +1,77 @@
+# Source guide: Laravel (PHP)
+
+Read this when the survey finds `composer.json` with `laravel/framework` and an `artisan` file. Laravel is conventional like Rails, but a lot of behavior is wired by service providers and the event system, so read those before the controllers.
+
+## Detect
+
+`artisan`, `bootstrap/app.php`, `routes/`, `app/Http`, `database/migrations`. Check the Laravel version in `composer.lock`: before 11, middleware lives in `app/Http/Kernel.php`; from 11, in `bootstrap/app.php`. Also check for Livewire, Inertia, Filament or Nova, which change what the frontend and admin are.
+
+## Where intent hides
+
+| Location                                                                  | Blueprint concept                                                       |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `database/migrations/*` (replay in order), `database/schema/*.sql`        | entities, attributes, DB-enforced invariants                            |
+| `app/Models/*`: `$fillable`/`$guarded`, `$casts`, relations, scopes, `booted()` | entities, relationships, tenancy scopes                           |
+| `app/Observers/*`, model `$dispatchesEvents`, `boot()` hooks              | **implicit events** (`created`, `updated`, `deleted`)                   |
+| `app/Events` + `app/Listeners` + `EventServiceProvider`                   | explicit events and their consumers (`explicit: true`)                  |
+| `routes/web.php`, `api.php`, `channels.php`, `console.php`                | api surfaces, realtime, CLI                                             |
+| `app/Http/Controllers/**`                                                 | commands/queries; invokable controllers are one command each            |
+| `app/Http/Requests/*` (FormRequest): `rules()`, `authorize()`             | input shape + validation and authorization policies                     |
+| `app/Policies/*`, `Gate::define` in `AuthServiceProvider`                 | policies (authorization)                                                |
+| `app/Http/Middleware/*` + middleware groups                               | cross-cutting policies (auth, tenancy, throttling, locale)              |
+| `app/Jobs/*`, `config/queue.php`, `app/Console/Kernel.php` / `routes/console.php` `schedule()` | system workflows, async effects      |
+| `app/Console/Commands/*`                                                  | operator workflows and CLI interface                                    |
+| `app/Notifications/*`, `app/Mail/*`                                       | event consumers + integrations (channels: mail, Slack, SMS)             |
+| `app/Providers/*`                                                         | bindings, global scopes, gates, macros: read for hidden wiring          |
+| `config/*.php` + `.env.example`                                           | integrations, feature toggles, tenancy mode                             |
+| `tests/Feature`, `tests/Unit` (Pest/PHPUnit)                              | scenarios; rules that exist only in tests                               |
+| `app/Filament/**`, `app/Nova/**`, Livewire `app/Livewire/**`              | admin workflows; Livewire components are UI **and** commands            |
+
+## Idiom -> blueprint -> Pikku
+
+| Laravel idiom                                          | Blueprint concept                                  | Pikku shortcut                                           |
+| ------------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------------- |
+| `Model::created` observer / `$dispatchesEvents`        | implicit event, consumers = observer body          | emit event; consumer = `wireQueueWorker`                 |
+| `event(new X)` + `Listener` (`ShouldQueue`)            | explicit event + async consumer                    | EventHub topic + queue worker                            |
+| `FormRequest::rules()`                                 | validation policy + command `input[]`              | Zod schema on `input`                                    |
+| `FormRequest::authorize()`, `$this->authorize()`, `Gate::allows`, `->can()` | authorization policy             | one named permission function                            |
+| `Route::middleware('auth:sanctum', 'can:...')`         | auth policy `enforcedAt` the route group           | auth middleware + permission                             |
+| `Policy` class methods (`view`, `update`, `delete`)    | per-entity authorization policies                  | permission functions per action                          |
+| `dispatch(new Job)` / `Bus::chain` / `Bus::batch`      | command effect: async step / multi-step workflow   | `wireQueueWorker` / `pikkuWorkflowFunc`                  |
+| `$schedule->command(...)->dailyAt(...)`                | system workflow with `schedule`                    | `wireScheduler`                                          |
+| `Notification::send` (mail/database/slack)             | event consumer + integration                       | service call in consumer                                 |
+| `Gate::before`, super-admin bypass                     | invariant exception: **record it**                 | explicit permission, never a global bypass               |
+| global scope (`addGlobalScope`, `SoftDeletes`, tenant trait) | tenancy scoping / soft-delete state            | session filter on reads; `archived` state                |
+| Eloquent accessors/mutators, `$casts`                  | derived/normalized attributes                      | Zod transforms or query mapping                          |
+| Sanctum / Passport / Fortify / Breeze                  | `LogInUser` etc. + token issuance                  | auth middleware / `better-auth`                          |
+| Livewire component (`wire:click`, public props)        | UI route + commands in one class: split them      | TanStack route + funcs                                   |
+| Blade + Alpine/Inertia pages                           | frontend (see SKILL.md server-rendered note)       | TanStack route; Alpine behaviors = `custom-logic` candidates |
+
+## Traps
+
+- **Observers and model `boot()` are invisible from controllers.** A controller that only calls `$order->save()` may trigger emails, stock updates and audit logs. Read the model's observers before naming the command's effects.
+- **Mass assignment shapes the API.** `$fillable` is the real allowed-input list; `$guarded = []` means any column is writable (a gap if exposed to users).
+- **Service providers run before everything.** Macros, global scopes, gates and route model bindings registered there change behavior across the app.
+- **Route model binding** (`Route::get('/invoices/{invoice}')`) silently adds a lookup + 404 + possibly a scope. Count it as a precondition, and check `Route::bind` customisations.
+- **Queued vs sync.** `ShouldQueue` on a listener/notification changes consistency semantics (eventual vs immediate). Record which.
+- **Duplicated rules between FormRequest, controller and model** are common; list every location in `enforcedAt`, and flag drift as a gap.
+- **Config in `.env` drives behavior** (`FEATURE_X`, `TENANCY_MODE`). Collect every `env(` / `config(` that gates a branch.
+- **Third-party packages carry product behavior** (Spatie `laravel-permission` = roles/permissions, `laravel-medialibrary`, Cashier = billing, `laravel-activitylog` = audit events). Read the package config, not the vendor code, and map to policies/integrations.
+- **Raw `DB::` queries and `DB::statement`** often hold reporting logic and tenancy bypasses. Grep and review each.
+
+## Search checklist
+
+```
+grep -rnE "Observer|\$dispatchesEvents|static::(created|updated|deleted|saving)" app
+grep -rnE "event\(|Event::dispatch|::dispatch\(|dispatch\(new" app
+grep -rnE "Gate::|->authorize\(|->can\(|@can|middleware\('can" app routes
+grep -rnE "addGlobalScope|withoutGlobalScope|SoftDeletes|withTrashed" app
+grep -rnE "DB::(raw|select|statement|table)" app
+grep -rnE "env\(|config\('.*feature" app config
+grep -rn "schedule->" app routes
+cat composer.json | grep -E "spatie|laravel/(cashier|sanctum|passport|fortify|nova)|livewire|filament"
+```
+
+## Confidence notes
+
+A validation in a FormRequest backed by a Feature test is `high`. Behavior reconstructed only from an observer with no test is `medium`. Anything resting on a Livewire component's public properties alone is `low`; confirm through the Blade template and its tests.

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

@@ -0,0 +1,73 @@
+# Source guide: NestJS
+
+Read this when the survey finds `@nestjs/core` in `package.json` and `nest-cli.json`. NestJS is the closest source to Pikku: modules, controllers, guards and providers map almost one-to-one. The risk is not finding things, it is over-mirroring the structure instead of recovering the product.
+
+## Detect
+
+`nest-cli.json`, `src/main.ts` (`NestFactory.create`), `*.module.ts`. Check the platform adapter (Express or Fastify), transports (`@nestjs/microservices`, GraphQL, WebSockets) and monorepo mode (`apps/`, `libs/`): each app is a component, each lib may be a shared domain.
+
+## Where intent hides
+
+| Location                                                                    | Blueprint concept                                                    |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `*.module.ts` (imports/providers/exports)                                   | domain candidates; the dependency graph shows ownership              |
+| `*.controller.ts`: `@Get/@Post/...`, `@UseGuards`, `@Roles`, `@HttpCode`    | api surfaces, command/query split, authorization                     |
+| `*.service.ts`                                                              | the actual command/query logic (controllers are usually thin)        |
+| `dto/*.ts` with `class-validator` (`@IsString`, `@Min`), `class-transformer` | command `input[]` + validation policies                             |
+| `*.entity.ts` (TypeORM), `schema.prisma`, `*.schema.ts` (Mongoose), `*.model.ts` (Sequelize/MikroORM) | entities, relations, constraints         |
+| `*.guard.ts`, `@Roles()`/`@Public()` decorators, `APP_GUARD` providers      | policies (authorization), including global defaults                  |
+| `*.pipe.ts`, global `ValidationPipe` options                                | validation policies (check `whitelist`, `forbidNonWhitelisted`)      |
+| `*.interceptor.ts`, `*.filter.ts`, `*.middleware.ts`                        | cross-cutting behavior: audit, caching, error mapping, tenancy       |
+| `@nestjs/schedule` (`@Cron`, `@Interval`), `@nestjs/bull`/`bullmq` (`@Processor`, `@Process`) | system workflows, queue consumers                |
+| `@nestjs/event-emitter` (`@OnEvent`, `emitter.emit`), `@nestjs/cqrs`        | explicit events and consumers; CQRS gives commands/queries for free  |
+| `@nestjs/microservices` (`@MessagePattern`, `@EventPattern`)                | event/command ingress from other services                            |
+| `*.gateway.ts` (`@WebSocketGateway`, `@SubscribeMessage`)                   | realtime interface                                                   |
+| `*.resolver.ts` (GraphQL)                                                   | queries/commands via `@Query`/`@Mutation`                            |
+| `@nestjs/config` + `.env.example`, `config/*.ts`                            | integrations, toggles                                                |
+| `*.spec.ts` (unit), `test/*.e2e-spec.ts` (supertest)                        | scenarios; e2e specs are the best source                             |
+
+## Idiom -> blueprint -> Pikku
+
+| NestJS idiom                                         | Blueprint concept                              | Pikku shortcut                                              |
+| ---------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------- |
+| `@Controller` method + service method                | one command or query                           | one `pikkuFunc`, wired with `wireHTTP`                      |
+| DTO class + `class-validator`                        | `input[]` + validation policy                  | Zod schema                                                  |
+| `@UseGuards(AuthGuard, RolesGuard)` / `@Roles`       | authorization policy                           | permission functions / middleware                           |
+| `APP_GUARD` global guard + `@Public()` opt-out       | default-deny policy + exceptions list          | auth by default, `auth: false` for the listed routes        |
+| `@Injectable` provider                               | service or domain logic                        | class in `services.ts`                                      |
+| `@Cron`, `@Interval`, `@Timeout`                     | system workflow with `schedule`                | `wireScheduler`                                             |
+| `@Processor` / `@Process`                            | queue consumer                                 | `wireQueueWorker`                                           |
+| `emitter.emit('x')` + `@OnEvent('x')`                | explicit event + consumer                      | EventHub topic / queue                                      |
+| CQRS `CommandHandler`, `QueryHandler`, `EventsHandler`, sagas | commands, queries, events, workflow  | direct 1:1; sagas become `pikkuWorkflowFunc`                |
+| `@Interceptor` (logging/caching/transform)           | cross-cutting concern                          | middleware, only if behavior matters to the product         |
+| Exception filter mapping errors to status codes      | error contract of the API                      | keep status/code mapping explicit in the func               |
+| Request-scoped provider (`Scope.REQUEST`), `AsyncLocalStorage`, `nestjs-cls` | session / tenant context       | Pikku session / services                                    |
+| `@nestjs/swagger` decorators                         | documented contract (check for drift)          | generated from `wireHTTP` + schemas                         |
+
+## Traps
+
+- **Structure is not intent.** Nest makes it easy to produce a service-per-table with CRUD controllers. Do not turn `UsersController.update` into `UpdateUser` unless it is a real business action; look at what the service does (status flips, notifications) and name the command from that.
+- **Services calling services.** Cross-module calls (`this.billing.charge`) are the real dependency graph. Derive domains from entity ownership, not from module folders.
+- **Guards can be bypassed by omission.** Check every controller for a missing `@UseGuards` when the rest have one, and read `APP_GUARD` registrations to see whether the default is secure. Missing coverage is a gaps.json security entry.
+- **Global setup in `main.ts`**: `app.useGlobalPipes`, `useGlobalGuards`, `enableCors`, `setGlobalPrefix`, `enableVersioning`, raw-body config for webhooks. These change every route's behavior and belong in `architecture.json`.
+- **Decorators carry semantics.** `@Transform`, `@Exclude`, `@Expose`, `@SerializeOptions` shape responses; `@Exclude` on a password field is an invariant about never exposing it.
+- **Dynamic modules** (`forRoot`, `forRootAsync`) hide which features are on. Read the module's config call and the env it reads.
+- **ORM hooks** (`@BeforeInsert`, `@AfterUpdate`, TypeORM subscribers, Prisma middleware/extensions) are implicit events like Rails callbacks.
+- **Event emitter is in-process.** `@OnEvent` handlers run in the same process and are lost on crash, unlike real queues. Record that delivery guarantee as an invariant (`enforcedBy: nothing`).
+- **Hybrid apps** (HTTP + microservice + WebSocket in one `main.ts`): each transport is an `interfaces.json` entry.
+
+## Search checklist
+
+```
+grep -rnE "@(Get|Post|Put|Patch|Delete|All)\(" src apps libs
+grep -rnE "@UseGuards|@Roles|@Public|APP_GUARD|@SetMetadata" src apps libs
+grep -rnE "useGlobal(Pipes|Guards|Interceptors|Filters)|enableCors|setGlobalPrefix|rawBody" src apps
+grep -rnE "@(Cron|Interval|Timeout|Process|Processor|OnEvent|EventPattern|MessagePattern|SubscribeMessage)" src apps libs
+grep -rnE "@(BeforeInsert|AfterInsert|BeforeUpdate|AfterUpdate|EventSubscriber)|\$use\(" src apps libs
+grep -rnE "forRootAsync?\(|ConfigService|process\.env" src apps libs
+ls test *.e2e-spec.ts 2>/dev/null
+```
+
+## Confidence notes
+
+A DTO validation exercised by an e2e spec is `high`. A guard-based rule with no test is `medium`. Because Nest's structure is declarative, most extraction is `high`; keep `medium`/`low` for logic buried in service methods that mix concerns and for anything decided by dynamic module config.