@pikku/skills 0.12.58 → 0.12.60

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.

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.