@pikku/skills 0.12.57 → 0.12.59

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

@@ -0,0 +1,72 @@
+# Source guide: Ruby on Rails
+
+Read this when the survey finds `Gemfile` + `config/routes.rb`. Rails is convention-heavy, so most intent sits in places the framework names for you. The traps are the things Rails does implicitly: callbacks, concerns, `default_scope`, and the console.
+
+## Detect
+
+`Gemfile` with `rails`, `config/application.rb`, `app/models`, `db/schema.rb` or `db/structure.sql`. Note the Rails version (`Gemfile.lock`) and whether it is API-only (`config.api_only`). Also note engines under `engines/` or `gems/`: each is a candidate domain.
+
+## Where intent hides
+
+| Location                                                                 | Blueprint concept                                                          |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| `db/schema.rb` / `structure.sql` (+ `db/migrate` for history)            | entities, attributes, DB-enforced invariants (unique indexes, FKs, checks) |
+| `app/models/*.rb`: validations, associations, scopes, enums              | entities, relationships, policies (validation), states                     |
+| `aasm`, `state_machines`, `enum status:` + every `update(status:)`       | entity lifecycle: each write site is a transition                          |
+| `config/routes.rb` (+ `routes/*.rb`, `concerns`)                         | api surfaces; `resources` generates 7 routes, so list only those enabled   |
+| `app/controllers/**`: `before_action`, `rescue_from`, strong params      | commands/queries, policies, input shapes                                   |
+| `app/policies/*` (Pundit), `app/models/ability.rb` (CanCanCan)           | policies (authorization)                                                   |
+| `app/services`, `app/interactors`, `app/commands`, `app/operations`      | commands, usually already named in domain language                         |
+| `app/jobs`, `app/workers` (Sidekiq/ActiveJob/Resque), `config/schedule.rb` (whenever), `sidekiq.yml`, `config/recurring.yml` | system workflows, event consumers |
+| `app/mailers`, `app/views/*_mailer`                                      | integration + implicit event consumer ("InvoicePaid sends receipt")        |
+| `app/admin`, `activeadmin`, `rails_admin`, `administrate`                | admin workflows and the real list of manageable entities                   |
+| `lib/tasks/*.rake`                                                       | operator workflows (data fixes, imports, nightly sweeps)                   |
+| `config/initializers/*`                                                  | integrations, global middleware, feature flags, hardcoded constants        |
+| `spec/` (RSpec) or `test/`: request, model, system specs                 | scenarios; edge-case rules that exist nowhere else                         |
+| `db/seeds.rb`, `spec/factories`                                          | realistic entity shapes and the roles/plans the product assumes            |
+
+## Idiom -> blueprint -> Pikku
+
+| Rails idiom                                       | Blueprint concept                                  | Pikku shortcut                                            |
+| ------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
+| `after_create` / `after_commit` / `after_save`    | **implicit event** (`explicit: false`), consumers = what the callback does | emit via EventHub/queue; consumer becomes `wireQueueWorker` |
+| `before_validation`, `validates`, `validate :x`   | policy (validation)                                | Zod refinement on the command `input`                     |
+| `before_action :authenticate_user!` / `authorize` | policy (authorization), `enforcedAt` per controller | one named permission function, wired once                 |
+| `has_secure_password`, Devise, `devise_for`       | `LogInUser` / `RegisterUser` commands; session policy | auth middleware / `better-auth`; do not hand-port Devise internals |
+| `enum` / `aasm event :x`                          | entity states + transitions                        | `status` column + guards inside the owning command        |
+| `default_scope`, `acts_as_tenant`, `Current.account` | **tenancy scoping on every query**              | session filter on every read; missing scope = gap         |
+| `dependent: :destroy` / `:nullify`                | invariant on deletion + cascade side effects       | FK `ON DELETE` in migration, or explicit command steps    |
+| `counter_cache`, `touch: true`                    | derived state (invariant, may drift)               | computed in query, or updated inside the command          |
+| ActiveJob `perform_later`                         | command effect: async step                         | `wireQueueWorker`                                         |
+| `ActionCable` channels                            | realtime interface                                 | EventHub topics                                           |
+| `ActiveStorage` / `CarrierWave` / `Shrine`        | integration (file storage) + attachment on entity  | storage service                                           |
+| `Rails.application.routes` `mount Sidekiq::Web`   | operator tooling, not product: drop                | excluded                                                  |
+| ERB/Slim/Haml + ViewComponent + Stimulus/Turbo    | frontend (see SKILL.md server-rendered note)       | TanStack route + `usePikkuQuery`; Stimulus = `custom-logic` candidate |
+
+## Traps
+
+- **Callbacks are the event system and nobody wrote it down.** Read every model's callback list, not just the controller. A status flip that also sends an email and bumps a counter is one event, `InvoicePaid`, with two consumers.
+- **Concerns hide behavior.** `include Trackable` or `include Archivable` may add scopes, callbacks and validations to ten models. Open the concern and attribute its rules to every including model.
+- **`default_scope` and `unscoped`.** A default scope silently filters deleted/other-tenant rows; every `unscoped` call is a deliberate escape worth a gap entry (security or reporting).
+- **Fat controllers with no service layer**: the action body is the command. Name the command from the action plus its effects, not the route.
+- **Monkeypatches and gems that override behavior** (`lib/core_ext`, `config/initializers`): grep for `class_eval`, `prepend`, `Module#refine`.
+- **Soft delete** (`paranoia`, `discard`, `deleted_at`): the entity has an `archived` state; "delete" is a command with different semantics from the DB row removal.
+- **Rails console and rake tasks are product surface.** If ops fix data in the console regularly (check READMEs, runbooks, `lib/tasks`), those fixes are missing commands. Record them in gaps.json.
+- **Feature flags** (`flipper`, `rollout`, ENV): a flagged-off path is not dead; record the flag and who flips it.
+- **Schema drift:** `schema.rb` is the truth, migrations are history. If they disagree, trust schema and note it. Raw SQL in migrations (`execute`) often hides triggers and views.
+
+## Search checklist
+
+```
+grep -rnE "after_(create|commit|save|update|destroy)|before_(save|destroy)" app/models
+grep -rnE "default_scope|unscoped|acts_as_tenant|Current\." app
+grep -rnE "aasm|state_machine|enum |update(_attribute|_column)?s?\(.*status" app
+grep -rnE "perform_(later|async|in)|\.deliver_(later|now)" app lib
+grep -rnE "authorize|policy_scope|can\?|load_and_authorize" app
+grep -rnE "Flipper|feature_enabled|ENV\[" app config lib
+ls lib/tasks config/schedule.rb config/recurring.yml 2>/dev/null
+```
+
+## Confidence notes
+
+A rule enforced by both a model validation and a request spec is `high`. A rule that only a callback implies (nobody tests it) is `medium`. Anything inferred from a view template alone is `low`.

package/skills/pikku-software-archaeology/references/tests-to-scenarios.md

@@ -0,0 +1,72 @@
+# Legacy tests -> blueprint scenarios -> Pikku scenarios
+
+Phase 2 reads the legacy test suite as a product spec. This file covers the two hops: legacy test -> `workflows.json` `scenarios[]` (extraction), then scenario -> `pikkuScenario` (rebuild). Pikku's side is defined by the `pikku-scenario` skill (`steps.md`, `coverage.md`); read it before generating, this file only records how legacy tests meet it.
+
+## Step 1: triage every test by kind
+
+Not every test is a scenario. Classify first; only some become `scenarios[]`.
+
+| Legacy test                                                                                 | Becomes in the blueprint                                 | Becomes in Pikku                                                  |
+| ------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------- |
+| Request / feature / e2e (Rails request spec, Laravel Feature, Nest e2e, supertest)          | `scenarios[]` on the workflow, `fromTest` set            | `pikkuScenario` (`given`/`when`/`then`)                           |
+| Browser journey (Playwright, Capybara, Dusk, Cypress)                                       | `scenarios[]` with a UI surface                          | `pikkuScenarioStep` with a `browser` binding, written as intent   |
+| Model / validation test                                                                     | upgrades a policy or invariant to `high`, cites the test | Zod refinement + a negative step (`expectError`), or a unit test  |
+| Authorization test (policy spec, "cannot see another user's invoice")                       | upgrades an authorization policy to `high`               | scenario as the owner and as another virtual user, `expectError`  |
+| Job / cron / webhook test                                                                   | `scenarios[]` on the **system** workflow                 | `scenario.runScheduledTask`, or post to the webhook, then `expectEventually` |
+| Pure-logic unit test (calculation, parser, state machine table)                             | an invariant, with examples                              | plain `node:test` calling `func` directly                         |
+| Heavily mocked unit test (RSpec doubles, Jest DB mocks, "expects `save` called once")       | nothing: it pins the old implementation                  | drop it, and note it in `gaps.json` only if it hid a real rule    |
+| Skipped / pending / commented-out test                                                      | `gaps.json` (intended behavior never finished)           | not generated                                                     |
+| Snapshot test of rendered HTML or JSON                                                      | at most a weak scenario                                  | rewrite as an assertion on the outcome, not the markup            |
+
+A rule attested by an implementation guard **and** a passing test is `high`. A scenario from a suite that does not run today is at most `medium`, because nobody has checked it still holds.
+
+## Step 2: write scenarios as intent
+
+Extract each test as given / when / outcome in domain language (`reads a credential nobody stored`), not as HTTP verbs or selectors. Pikku step names describe what the user wanted, in English identifiers, and the prose is third-person with no virtual user in it (the reporter supplies the subject). Keep the legacy test name in `fromTest`; do not copy its phrasing if it is a method name (`test_returns_404_for_deleted`).
+
+One scenario per **journey**, not per function and not per test. Several legacy tests that walk the same journey with different inputs become one scenario, or entries in a `pikkuFeature` (see table-driven tests below).
+
+## Step 3: translate the setup, because Pikku has no back door
+
+A Pikku step runs in the CLI process and reaches the app **only over the wire as a virtual user**: `virtualUser.invoke`, `invokeRaw`, or a plain `fetch` to the target. There is no database handle, no secrets, and no state reset. Legacy tests lean on all of those, so most of the translation effort is here.
+
+| Legacy setup                                                              | Pikku equivalent                                                                 |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Factories / fixtures inserting rows directly (`factory_bot`, `Model::factory()`, `repo.save`) | `given` steps that call the app's own commands as a virtual user. **If no command can create the state, the product is missing one: record it in `gaps.json`.** |
+| Clean database per test (transactions, `RefreshDatabase`, truncate)       | None. Use unique ids per run and scope what you create; `before`/`after` hooks for reset RPCs |
+| Logged-in user helpers (`sign_in user`, `actingAs`, forged JWTs)          | `defineVirtualUsers`: one entry per person/role, signed in by the runner         |
+| Roles built inline per test                                               | one virtual user per role actually used (`shopper`, `support`, `admin`)          |
+| Frozen / travelled time (`travel_to`, `Carbon::setTestNow`, fake timers)  | Not available against a live server. Fire schedulers with `runScheduledTask`; for time-based rules, expose the rule as testable input or keep it as a unit test |
+| Stubbed externals / recorded HTTP (VCR, nock, `Http::fake`, Mockery)      | stubbed services with the server in `--test` mode, asserted with `expectService`; or a mock server in the feature's `before`/`after` |
+| `sleep` / waiting for the queue                                           | `expectEventually(..., { within, interval })`                                    |
+| Direct DB assertions (`expect(Order.count)`, `assertDatabaseHas`)         | assert through a query the app exposes. If no query shows it, the fact is invisible to users: question whether it matters, or expose it |
+
+## Step 4: assertions
+
+- Every scenario must assert (PKU680): a flow of only `given`/`when` fails the inspector. Convert each legacy `expect`/`assert` into a `then`.
+- A negative test (`returns 403`, `raises`, `assertForbidden`) becomes `expectError`, or `invokeRaw` when the refusal itself is the assertion. Authorization tests need two virtual users: the owner succeeds, someone else is refused.
+- Do not assert on legacy status codes or response shapes unless they are part of a public contract (a documented API with outside consumers). Otherwise assert the outcome (the invoice is paid, the user sees it) and let `decisionsNeeded` record whether the old shape must be kept.
+- A `then` runs every binding it declares and fails if they disagree (API says paid, browser still shows a spinner). When a legacy journey had both an API test and a browser test for the same outcome, they are witnesses of one `then`, not two scenarios.
+
+## Table-driven tests
+
+RSpec `shared_examples`, PHPUnit `@dataProvider` / Pest `with()`, `it.each`, `test.each`: these are Examples. In Pikku, put the cases in a `pikkuFeature` as `{ scenario, data }` entries (one run per entry) or loop the steps. Do not write a scenario per row.
+
+## What each legacy idiom looks like
+
+| Framework      | Where the journey tests are                                     | Idioms to translate                                                                       |
+| -------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Rails          | `spec/requests`, `spec/system`, `test/integration`              | `let`/`before` blocks and `factory_bot` = setup; `travel_to` = time; `VCR` = externals    |
+| Laravel        | `tests/Feature`, `tests/Browser` (Dusk)                         | `RefreshDatabase`, `actingAs`, `Queue::fake`, `Mail::fake`, `Http::fake`                  |
+| NestJS         | `test/*.e2e-spec.ts` (supertest + `Test.createTestingModule`)   | `overrideProvider` = stubbed service; `beforeEach` truncate = no reset in Pikku           |
+| Express        | `test/`, `__tests__` (supertest, mocha/jest)                    | `nock` = externals; DB seeded in `beforeEach`; auth via forged token helper               |
+
+## Coverage as the acceptance check
+
+Do not invent a parallel coverage file. Pikku already computes coverage from scenarios: run `pikku scenario run <env> --coverage` against `pikku dev --coverage` and read `<outDir>/coverage/scenario-coverage.json`. For the rebuild, the useful comparison is:
+
+1. Every blueprint command, policy and invariant should be reachable from at least one scenario (check against the coverage output).
+2. Anything uncovered either has no legacy test (record it in `gaps.json` as untested-but-critical) or its test was dropped as implementation-pinning (confirm that was deliberate).
+3. The legacy suite's passing journeys should pass against the rebuild, so migrate them first and treat them as the regression bar.
+
+Scenarios are flows and coverage is their consequence, so close gaps by extending a real journey, not by adding a scenario per function.

package/skills/pikku-tailwind/SKILL.md

@@ -1,13 +1,12 @@
 ---
 name: pikku-tailwind
 description: >-
-  Use when building a Tailwind + shadcn/ui interface on top of a Pikku backend — rendering dates that
-  came back from a generated client, keeping layout flow-relative so the app survives an RTL locale,
-  branching on colour scheme without hardcoding a shade, and choosing components. TRIGGER when:
-  putting a value from usePikkuQuery or an RPC response on screen, writing margins/padding/alignment
-  classes, choosing a date input or any shadcn component, handling light/dark, or fixing a
-  `@shadcn/lint` error. DO NOT TRIGGER when: the data does not come from a Pikku client (this is only
-  about what the generated clients hand you), or for user-facing copy (use pikku-i18n).
+  Tailwind + shadcn/ui on a Pikku backend: rendering dates from a generated client, flow-relative
+  layout that survives RTL, colour-scheme branching without hardcoded shades, choosing components.
+  TRIGGER when: putting a usePikkuQuery/RPC value on screen, writing margin/padding/alignment
+  classes, picking a date input or shadcn component, handling light/dark, or fixing a `@shadcn/lint`
+  error. DO NOT TRIGGER when the data does not come from a Pikku client, or for user-facing copy
+  (use pikku-i18n).
 installGroups: [client]
 ---
 
@@ -83,15 +82,15 @@ All of this applies to stub and fixture dates exactly as it does to real data.
 Write layout classes flow-relative so the UI works in both LTR and RTL languages. Pikku's i18n ships
 Arabic, Hebrew, Farsi and Urdu support, and a physical margin is what breaks under it.
 
-| Avoid                    | Use instead                 |
-| ------------------------ | --------------------------- |
-| `ml-*`, `mr-*`           | `ms-*`, `me-*`              |
-| `pl-*`, `pr-*`           | `ps-*`, `pe-*`              |
-| `left-*`, `right-*`      | `start-*`, `end-*`          |
-| `text-left`, `text-right`| `text-start`, `text-end`    |
-| `border-l`, `border-r`   | `border-s`, `border-e`      |
-| `rounded-l`, `rounded-r` | `rounded-s`, `rounded-e`    |
-| `flex-row-reverse`       | the `dir` attribute         |
+| Avoid                     | Use instead              |
+| ------------------------- | ------------------------ |
+| `ml-*`, `mr-*`            | `ms-*`, `me-*`           |
+| `pl-*`, `pr-*`            | `ps-*`, `pe-*`           |
+| `left-*`, `right-*`       | `start-*`, `end-*`       |
+| `text-left`, `text-right` | `text-start`, `text-end` |
+| `border-l`, `border-r`    | `border-s`, `border-e`   |
+| `rounded-l`, `rounded-r`  | `rounded-s`, `rounded-e` |
+| `flex-row-reverse`        | the `dir` attribute      |
 
 Directional icons (chevrons, arrows) flip with `rtl:rotate-180`.
 

package/skills/pikku-theme/SKILL.md

@@ -1,15 +1,13 @@
 ---
 name: pikku-theme
 description: >-
-  Use when giving a Pikku Tailwind + shadcn/ui app its look: picking and applying a theme with `pikku
-  ui theme list|apply`, composing brand colours, fonts, page and ink over a preset's structure, matching
-  an existing look by hand, declaring component variants in the component's `cva` definition,
-  replacing template names (`pikku validate` flags them), and keeping emails/theme.json on-brand.
-  Also the light/dark and WCAG contrast rules a theme must clear. TRIGGER when: the user asks to
-  theme, restyle, rebrand or recolour an app; the project has packages/theme (themes/*.json,
-  active.json); a screen needs a colour, font, radius or shadow; or the app still shows a template
-  name. DO NOT TRIGGER when: rendering data or RTL layout (use pikku-tailwind),
-  writing email templates (use pikku-emails), or accessibility beyond colour (use pikku-a11y).
+  Giving a Pikku Tailwind + shadcn/ui app its look: `pikku ui theme list|apply`, brand
+  colours/fonts/page/ink over a preset, matching an existing look, cva component variants, replacing
+  template names (`pikku validate` flags them), emails/theme.json, plus light/dark and WCAG contrast
+  rules. TRIGGER when: asked to theme, restyle, rebrand or recolour; the project has packages/theme
+  (themes/*.json, active.json); a screen needs a colour, font, radius or shadow; or template names
+  still show. DO NOT TRIGGER for data rendering or RTL layout (use pikku-tailwind), email templates
+  (use pikku-emails) or accessibility beyond colour (use pikku-a11y).
 installGroups: [client]
 ---
 
@@ -86,14 +84,14 @@ pikku ui theme apply --preset storybook \
 pikku ui theme apply --preset quorum --structure monopro
 ```
 
-| Flag | Sets |
-| --- | --- |
-| `--preset <id>` | starting brand + structure; the theme is written as `themes/<id>.json` (no preset → `custom`, based on the first preset) |
-| `--structure <id>` | swap in another preset's structure (depth) under this brand |
-| `--primary`, `--secondary`, `--accent` | brand colours, hex |
-| `--font-heading`, `--font-body` | Google Fonts families |
-| `--page` | light-mode page colour (`structure.page`) — paper, linen, bone instead of white |
-| `--ink` | light-mode text colour (`structure.ink`) |
+| Flag                                   | Sets                                                                                                                     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `--preset <id>`                        | starting brand + structure; the theme is written as `themes/<id>.json` (no preset → `custom`, based on the first preset) |
+| `--structure <id>`                     | swap in another preset's structure (depth) under this brand                                                              |
+| `--primary`, `--secondary`, `--accent` | brand colours, hex                                                                                                       |
+| `--font-heading`, `--font-body`        | Google Fonts families                                                                                                    |
+| `--page`                               | light-mode page colour (`structure.page`) — paper, linen, bone instead of white                                          |
+| `--ink`                                | light-mode text colour (`structure.ink`)                                                                                 |
 
 Flags are flat scalars, one value each; there is no nested `--colors` object. One call writes the
 theme, makes it active, regenerates `themes/index.ts` (so the running app reloads) and re-brands

package/skills/pikku-ui/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: pikku-ui
 description: >-
-  How a screen gets made: it is delegated to a subagent, which is handed the project's design rules and designs it with the impeccable skill.
-  TRIGGER when: the user asks for a screen, page, view, form, dashboard or empty/error state, or asks for an existing screen to be redone or restyled.
-  DO NOT TRIGGER when: the change is backend only, copy only (use pikku-i18n), or a one-line fix to a screen that already looks right.
+  How a screen gets made: delegated to a subagent handed the project's design rules, designing with
+  the impeccable skill. TRIGGER when: asked for a screen, page, view, form, dashboard or empty/error
+  state, or to redo/restyle an existing screen. DO NOT TRIGGER for backend-only changes, copy-only
+  changes (use pikku-i18n) or a one-line fix to a screen that already looks right.
 installGroups: [client]
 ---
 

package/skills/pikku-webhook/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: pikku-webhook
 description: >-
-  Use when an application needs to SEND outgoing webhooks — notifying a customer's endpoint that
-  something happened, with signing, retries and a delivery log. Covers WebhookService,
-  QueueWebhookService, the `pikku-outgoing-webhooks` queue worker, `scaffold.webhook`,
-  `config.webhook`, signature verification on the receiving side, and KyselyWebhookService's
-  delivery history. TRIGGER when: code uses webhookService, QueueWebhookService,
-  KyselyWebhookService, pikkuWebhookWorkerFunc, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
-  SendWebhookInput or X-Pikku-Signature. TRIGGER when: the user asks to emit events to a
-  customer URL, build a webhook endpoint settings screen, add a signing secret, or show
-  delivery attempts. DO NOT TRIGGER when: the user is RECEIVING webhooks from a third party
-  into a route — that is an ordinary wireHTTP function (use pikku-wiring).
+  Sending OUTGOING webhooks from a Pikku app (notify a customer's endpoint, with signing, retries
+  and a delivery log): WebhookService, QueueWebhookService, the `pikku-outgoing-webhooks` queue
+  worker, `scaffold.webhook`, `config.webhook`, receiver signature verification,
+  KyselyWebhookService delivery history. TRIGGER when: code uses webhookService,
+  QueueWebhookService, KyselyWebhookService, pikkuWebhookWorkerFunc,
+  PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, SendWebhookInput or X-Pikku-Signature; or asked to emit events
+  to a customer URL, build a webhook settings screen, add a signing secret or show delivery
+  attempts. DO NOT TRIGGER for RECEIVING third-party webhooks (an ordinary wireHTTP function; use
+  pikku-wiring).
 installGroups: [core]
 ---
 
@@ -201,7 +200,7 @@ const deliveries = await webhookService.listDeliveries({
 const detail = await webhookService.getDelivery(deliveryId) // { delivery, attempts }
 ```
 
-Building a console screen is `listDeliveries` for the list and `getDelivery` for
+Building a deliveries screen is `listDeliveries` for the list and `getDelivery` for
 the drill-in. A hand-written select over `webhookDelivery` is a sign the wrong
 service is registered.
 

package/skills/pikku-wiring/SKILL.md

@@ -1,17 +1,15 @@
 ---
 name: pikku-wiring
 description: >-
-  Use when exposing a Pikku function over a transport — HTTP routes and SSE, WebSocket channels,
-  typed realtime pub/sub, internal and exposed RPC, queue workers, cron schedules, event triggers,
-  MCP tools/resources/prompts, CLI commands, or a Slack gateway. Covers choosing the wiring, what
-  every wiring shares, and what differs: function type, session source, and which calls throw
-  instead of returning. TRIGGER when: code uses wireHTTP, defineHTTPRoutes, wireChannel,
-  wireQueueWorker, wireScheduler, wireTrigger, wireTriggerSource, wireCLI, wireMCPResource,
-  wireMCPPrompt, `mcp: true`, `sse: true`, `expose: true`, rpc.invoke, SlackGatewayAdapter, or the
-  user asks how to expose, route, schedule, queue, stream or publish a function. DO NOT TRIGGER
-  when: writing the function body (use pikku-concepts), authorization (use pikku-permissions), serving on
-  a runtime (use pikku-deploy), building a live-updating view (use pikku-realtime), or sending
-  outgoing webhooks (use pikku-webhook).
+  Exposing a Pikku function over a transport: HTTP and SSE, WebSocket channels, typed pub/sub, RPC,
+  queue workers, cron, event triggers, MCP tools/resources/prompts, CLI commands, Slack gateway;
+  choosing the wiring and what differs by function type, session source and throw-vs-return. TRIGGER
+  when: code uses wireHTTP, defineHTTPRoutes, wireChannel, wireQueueWorker, wireScheduler,
+  wireTrigger, wireTriggerSource, wireCLI, wireMCPResource, wireMCPPrompt, `mcp: true`, `sse: true`,
+  `expose: true`, rpc.invoke or SlackGatewayAdapter, or asked how to expose, route, schedule, queue,
+  stream or publish a function. DO NOT TRIGGER for function bodies (use pikku-concepts),
+  authorization (use pikku-permissions), runtimes (use pikku-deploy), live views (use
+  pikku-realtime) or outgoing webhooks (use pikku-webhook).
 installGroups: [core]
 ---
 
@@ -55,7 +53,7 @@ Three consequences that hold for every wiring below:
 - **Permissions are never declared on the wiring.** Wire-level permissions were
   removed in #972 — declare them on the function (`pikkuFunc({ permissions })`,
   see `pikku-permissions`) or app-wide via `addGlobalPermission`. Tags and
-  patterns now target *middleware* only.
+  patterns now target _middleware_ only.
 - **The wire is the third argument**, not a service. `channel`, `rpc`, `session`,
   `setSession`, `mcp`, `queue`, `scheduledTask` and `cli` all live there.
 
@@ -70,30 +68,30 @@ exactly the typing that makes the wiring worth having, silently.
 naming the `#pikku` leaf to use instead. `@pikku/core/services` is the one
 subpath it exempts — the service implementations bootstrap picks.
 
-| Wiring | Import from |
-| --- | --- |
-| `wireHTTP`, `defineHTTPRoutes`, `wireHTTPRoutes` | `#pikku/http` |
-| `wireChannel`, `defineChannelRoutes` | `#pikku/channel` |
-| `wireQueueWorker` | `#pikku/queue` |
-| `wireScheduler` | `#pikku/scheduler` |
-| `wireTrigger`, `wireTriggerSource`, `pikkuTriggerFunc` | `#pikku/trigger` |
-| `wireCLI`, `pikkuCLICommand`, `pikkuCLIRender` | `#pikku/cli` |
-| `pikkuMCPToolFunc`, `pikkuMCPResourceFunc`, `pikkuMCPPromptFunc`, `wireMCPResource`, `wireMCPPrompt` | `#pikku/mcp` |
+| Wiring                                                                                               | Import from        |
+| ---------------------------------------------------------------------------------------------------- | ------------------ |
+| `wireHTTP`, `defineHTTPRoutes`, `wireHTTPRoutes`                                                     | `#pikku/http`      |
+| `wireChannel`, `defineChannelRoutes`                                                                 | `#pikku/channel`   |
+| `wireQueueWorker`                                                                                    | `#pikku/queue`     |
+| `wireScheduler`                                                                                      | `#pikku/scheduler` |
+| `wireTrigger`, `wireTriggerSource`, `pikkuTriggerFunc`                                               | `#pikku/trigger`   |
+| `wireCLI`, `pikkuCLICommand`, `pikkuCLIRender`                                                       | `#pikku/cli`       |
+| `pikkuMCPToolFunc`, `pikkuMCPResourceFunc`, `pikkuMCPPromptFunc`, `wireMCPResource`, `wireMCPPrompt` | `#pikku/mcp`       |
 
 ## Pick a wiring
 
-| Reach for | When | Reference |
-| --- | --- | --- |
-| **HTTP** | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only) | `references/http.md`; every field in `references/http-options.md` |
-| **Channel** | A hand-designed WebSocket protocol with your own action routing | `references/channel.md` |
-| **Realtime** | Typed pub/sub push — the scaffolded `/events` channel and SSE topics, plus subscribing to any other `sse: true` route or channel from the client | `references/realtime.md` |
-| **RPC** | One function calling another, or dispatching a name from outside | `references/rpc.md` |
-| **Queue** | Reliable background work that must survive a crash and retry | `references/queue.md` |
-| **Scheduler** | Recurring work on a cron expression | `references/scheduler.md` |
-| **Trigger** | Reacting in-process to an external event source (Redis pub/sub, PG LISTEN) | `references/trigger.md` |
-| **MCP** | Exposing functions to an AI assistant as tools, resources or prompts | `references/mcp.md` |
-| **CLI** | A terminal program with commands, subcommands and options | `references/cli.md`; end-to-end walkthrough in `references/cli-complete-example.md` |
-| **Gateway** | An inbound integration from a third-party product — Slack is the shipped adapter | `references/gateway-slack.md` |
+| Reach for     | When                                                                                                                                             | Reference                                                                           |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| **HTTP**      | REST endpoints, web APIs, and SSE streams (`sse: true`, `get` only)                                                                              | `references/http.md`; every field in `references/http-options.md`                   |
+| **Channel**   | A hand-designed WebSocket protocol with your own action routing                                                                                  | `references/channel.md`                                                             |
+| **Realtime**  | Typed pub/sub push — the scaffolded `/events` channel and SSE topics, plus subscribing to any other `sse: true` route or channel from the client | `references/realtime.md`                                                            |
+| **RPC**       | One function calling another, or dispatching a name from outside                                                                                 | `references/rpc.md`                                                                 |
+| **Queue**     | Reliable background work that must survive a crash and retry                                                                                     | `references/queue.md`                                                               |
+| **Scheduler** | Recurring work on a cron expression                                                                                                              | `references/scheduler.md`                                                           |
+| **Trigger**   | Reacting in-process to an external event source (Redis pub/sub, PG LISTEN)                                                                       | `references/trigger.md`                                                             |
+| **MCP**       | Exposing functions to an AI assistant as tools, resources or prompts                                                                             | `references/mcp.md`                                                                 |
+| **CLI**       | A terminal program with commands, subcommands and options                                                                                        | `references/cli.md`; end-to-end walkthrough in `references/cli-complete-example.md` |
+| **Gateway**   | An inbound integration from a third-party product — Slack is the shipped adapter                                                                 | `references/gateway-slack.md`                                                       |
 
 Realtime and Channel are the pair most often confused. If the shape is "server
 pushes typed events to subscribers", use Realtime — `pikku enable events`
@@ -104,11 +102,11 @@ only when the client also sends structured messages you need to route on.
 
 ### Each wiring demands a particular function type
 
-| Wiring | Function type | Why |
-| --- | --- | --- |
-| HTTP, Channel, Queue, CLI, MCP | `pikkuFunc` / `pikkuSessionlessFunc` | Ordinary request/response |
-| Scheduler | **`pikkuVoidFunc`** | A cron has no input and no caller to return to |
-| Trigger *source* | **`pikkuTriggerFunc`** | Runs **once at startup**, not once per event |
+| Wiring                         | Function type                        | Why                                            |
+| ------------------------------ | ------------------------------------ | ---------------------------------------------- |
+| HTTP, Channel, Queue, CLI, MCP | `pikkuFunc` / `pikkuSessionlessFunc` | Ordinary request/response                      |
+| Scheduler                      | **`pikkuVoidFunc`**                  | A cron has no input and no caller to return to |
+| Trigger _source_               | **`pikkuTriggerFunc`**               | Runs **once at startup**, not once per event   |
 
 A trigger source is the one that surprises people: it sets up a listener, calls
 `trigger.invoke(...)` per event, and returns a teardown function. It receives
@@ -145,11 +143,11 @@ logging them as errors.
 
 ### Delivery semantics differ, and that is usually the real choice
 
-| Wiring | Delivery | Runs where |
-| --- | --- | --- |
-| Trigger | **At-most-once**, synchronous | In-process, alongside the listener |
-| Queue | **At-least-once** with retries and a dead-letter queue | Distributed workers |
-| Scheduler | Depends on the runtime — see below | Wherever the scheduler service runs |
+| Wiring    | Delivery                                               | Runs where                          |
+| --------- | ------------------------------------------------------ | ----------------------------------- |
+| Trigger   | **At-most-once**, synchronous                          | In-process, alongside the listener  |
+| Queue     | **At-least-once** with retries and a dead-letter queue | Distributed workers                 |
+| Scheduler | Depends on the runtime — see below                     | Wherever the scheduler service runs |
 
 Reach for a trigger to react immediately, and a queue when the work must not be
 lost. A trigger that must not drop events is a queue with extra steps.
@@ -160,11 +158,11 @@ cron expression can decide which tasks fire. `pikku-deploy` has the comparison.
 
 ### Codegen owns several wirings — do not hand-write them
 
-| Turn it on | Codegen writes | Never hand-write |
-| --- | --- | --- |
-| `pikku enable rpc` | `rpc-public.gen.ts` — the `POST /rpc/:rpcName` route | A second route on the same path collides |
+| Turn it on            | Codegen writes                                                   | Never hand-write                                  |
+| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------- |
+| `pikku enable rpc`    | `rpc-public.gen.ts` — the `POST /rpc/:rpcName` route             | A second route on the same path collides          |
 | `pikku enable events` | `events.gen.ts` — the `/events` channel and `GET /events/:topic` | A hand-rolled `/events` misses disconnect cleanup |
-| `wireCLI` | `<program>-channel.gen.ts` — the same commands over a channel | It is regenerated on every build |
+| `wireCLI`             | `<program>-channel.gen.ts` — the same commands over a channel    | It is regenerated on every build                  |
 
 Enabling the RPC endpoint says the endpoint exists, not who may call it — each
 `expose: true` function is still gated by its own `auth`, permissions and scopes.

package/skills/pikku-wiring/references/channel.md

@@ -44,7 +44,7 @@ permissions were removed in #972. Authorization lives on the function's own
 ### `pikkuChannelMiddleware(fn)`
 
 ```typescript
-import { pikkuChannelMiddleware } from '@pikku/core'
+import { pikkuChannelMiddleware } from '@pikku/core/middleware'
 
 const middleware = pikkuChannelMiddleware(async (services, event, next) => {
   // Transform or filter events before/after

package/skills/pikku-wiring/references/scheduler.md

@@ -38,7 +38,7 @@ wireScheduler({
 })
 ```
 
-`runScheduledTask` builds its wire with a `sessionService`, so a `setSession`
+`runScheduledTask` builds its wire with a `sessionService`, so a `setInitialSession`
 here is the session the function is frozen with. See the machine-auth section of
 `pikku-middleware` for the factory and for why a cron is not a user row.
 

package/skills/pikku-wiring/references/trigger.md

@@ -77,6 +77,29 @@ The config-object form (`pikkuTriggerFunc({ func, title, description, tags,
 input, output })`) is also accepted when you want schemas or metadata on the
 source.
 
+### Events that belong to a user
+
+A source that watches something on a user's behalf — polling each connected
+user's mailbox, say — names that user as the second argument to `invoke`:
+
+```typescript
+for (const userId of await credentialService.getUsersWithCredential('gmail')) {
+  for (const message of await fetchNewMessages(userId)) {
+    trigger.invoke(message, { pikkuUserId: userId })
+  }
+}
+```
+
+The target then runs as that user, exactly like a queue job or workflow run
+carrying a `pikkuUserId`: its `type: 'wire'` credentials and its stored session
+resolve for them, and a workflow target records them on the run. Without the
+option the target runs as nobody.
+
+The user is the source's assertion, not the event's — it is a separate argument
+so nothing in the event data can set it. Pass only a user the source has
+established itself, such as the one whose credential it just polled with, and
+never an id read out of the event.
+
 ## Starting triggers
 
 Nothing fires until a `TriggerService` is started. For a single process,
@@ -84,7 +107,7 @@ Nothing fires until a `TriggerService` is started. For a single process,
 target and sets it up:
 
 ```typescript
-import { InMemoryTriggerService } from '@pikku/core/services'
+import { InMemoryTriggerService } from '@pikku/core/services/in-memory-trigger'
 
 const triggerService = new InMemoryTriggerService()
 await triggerService.start()

package/skills/pikku-workflow/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: pikku-workflow
 description: >-
-  Use when building multi-step, durable workflows with Pikku — pikkuWorkflowFunc,
-  pikkuWorkflowGraph, workflow.do / sleep / suspend / approval, retries, compensate, sub-workflows,
-  and starting or resuming runs. Includes deciding whether something should be a workflow at all.
-  TRIGGER when: code uses pikkuWorkflowFunc or pikkuWorkflowGraph, or the user asks about
-  workflows, multi-step processes, durable execution, suspend/resume, approval gates, sagas or DAG
-  orchestration. DO NOT TRIGGER when: the user wants a single background job (use the queue
-  reference in pikku-wiring) or a cron task (use the scheduler reference in pikku-wiring), or is
-  converting an n8n export (use pikku-n8n-import).
+  Multi-step durable workflows with Pikku: pikkuWorkflowFunc, pikkuWorkflowGraph,
+  workflow.do/sleep/suspend/approval, retries, compensate, sub-workflows, starting/resuming runs,
+  and deciding whether something should be a workflow at all. TRIGGER when: code uses
+  pikkuWorkflowFunc or pikkuWorkflowGraph, or asked about workflows, multi-step processes, durable
+  execution, suspend/resume, approval gates, sagas or DAG orchestration. DO NOT TRIGGER for a single
+  background job or cron task (use pikku-wiring's queue/scheduler references) or n8n exports (use
+  pikku-n8n-import).
 installGroups: [core]
 ---