@pikku/skills 0.12.13 → 0.12.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.13",
+  "version": "0.12.14",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-ai-vercel/SKILL.md

@@ -6,7 +6,6 @@ description: >-
   VercelAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
   @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-agent) or
   voice I/O (use pikku-ai-voice).
-installGroups: [core]
 ---
 
 # Pikku AI Vercel (Agent Runner)

package/skills/pikku-ai-voice/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   agents, speech-to-text, text-to-speech, transcription, or @pikku/ai-voice. DO NOT TRIGGER when:
   user asks about AI agent wiring generally (use pikku-agent) or the runner itself (use
   pikku-ai-vercel).
+installGroups: [fabric]
 ---
 
 # Pikku AI Voice (Speech I/O)

package/skills/pikku-audit/SKILL.md

@@ -10,7 +10,6 @@ description: >-
   uses auditLog, createInvocationAudit, createAuditedKysely, or AuditService. DO NOT TRIGGER when:
   user wants app logging/telemetry (use the logger) or DB migrations in general (use
   pikku-kysely).
-installGroups: [core]
 ---
 
 # Pikku Audit

package/skills/pikku-better-auth/SKILL.md

@@ -10,7 +10,6 @@ description: >-
   user asks about ANY form of authentication, login, logout, sessions, or user identity — always
   answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security)
   or custom session services (use pikku-services).
-installGroups: [core]
 ---
 
 # Pikku Better Auth Integration

package/skills/pikku-build-app/SKILL.md

@@ -10,7 +10,6 @@ description: >-
   something quick or throwaway (use pikku-build-quick), wants every platform surface demonstrated
   (use pikku-build-platform), or is adding one feature to an app that already has its knowledge
   base and milestones (use pikku-feature).
-installGroups: [core]
 ---
 
 # Build a product on open-source Pikku

package/skills/pikku-build-platform/SKILL.md

@@ -8,8 +8,7 @@ description: >-
   app, or asked to demonstrate what Pikku can do. DO NOT TRIGGER when: the user wants a product
   built (use pikku-build-app), something quick (use pikku-build-quick), or one specific surface
   wired into an existing app — a single workflow, cron job or agent (use that surface's own skill,
-  e.g. pikku-workflow, pikku-cron, pikku-agent).
-installGroups: [core]
+  e.g. pikku-workflow, pikku-schedule, pikku-agent).
 ---
 
 # Build a platform showcase on Pikku
@@ -90,7 +89,7 @@ on a human or a timer and must survive a restart.
   from the UI.
 - Three workflows ship with the template. Read them before writing yours.
 
-### Schedules — `pikku-schedule` / `pikku-cron`
+### Schedules — `pikku-schedule`
 
 Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
 
@@ -231,7 +230,7 @@ built.
 ## Reference
 
 - Base workflow: `pikku-build-app` — read it first, follow it in full
-- Per-surface skills: `pikku-workflow`, `pikku-schedule`, `pikku-cron`,
+- Per-surface skills: `pikku-workflow`, `pikku-schedule`,
   `pikku-queue`, `pikku-agent`, `pikku-ai-vercel`, `pikku-realtime`,
   `pikku-websocket`, `pikku-mcp`, `pikku-trigger`, `pikku-i18n`, `pikku-rtl`,
   `pikku-emails`, `pikku-versioning`, `pikku-addon`, `pikku-security`,

package/skills/pikku-build-quick/SKILL.md

@@ -12,7 +12,6 @@ description: >-
   workflows, queues, realtime or i18n (use pikku-build-platform); or the user is adding a feature
   to an app that already exists rather than building one from a fresh scaffold (use
   pikku-feature).
-installGroups: [core]
 ---
 
 # Build an app on Pikku, fast

package/skills/pikku-concepts/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pikku-concepts
 description: >-
-  Foundational guide to Pikku framework concepts. Use this skill when working with any Pikku
-  codebase, starting a new Pikku project, or migrating a backend to Pikku. Covers the core mental
-  model, function types, project structure, code generation, testing, and how Pikku maps to
-  traditional backend patterns. TRIGGER when: user asks "what is Pikku?", starts a new Pikku
-  project, migrates from Express/NestJS/Hono, or needs to understand how Pikku works. DO NOT
-  TRIGGER when: user is doing a specific wiring task (use the specific skill instead, e.g.
-  pikku-http, pikku-websocket).
+  Use FIRST in any Pikku codebase, before writing an import or reaching for another pikku skill.
+  Covers the core mental model, function types, project structure, code generation and testing,
+  and how to read `pikku doc` — the API surface of the pikku actually installed here, which also
+  indexes which skill teaches each door. TRIGGER when: starting any Pikku task, about to import
+  from `#pikku/*`, unsure whether an export exists or what its options are called, choosing which
+  pikku skill to load, a build failed on an unknown import or option, or migrating an existing
+  backend to Pikku. DO NOT TRIGGER when: the task is not a Pikku project.
 installGroups: [core]
 ---
 
@@ -17,7 +17,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run `pikku doc --ai` for the installed API surface, and the relevant `pikku meta ... --json` for what this project has wired.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
@@ -25,12 +25,54 @@ Use this skill as an execution checklist, not reference material.
 
 Pikku is a TypeScript framework that separates business logic from transport mechanisms. You define a function once, then wire it to HTTP, WebSocket, queues, schedulers, MCP, CLI, or RPC — without the function knowing how it's being called.
 
-For deep-dive on each topic, see the dedicated skills:
+## Ask The Installed Pikku, Don't Guess
 
-- **Wiring**: `pikku-http`, `pikku-websocket`, `pikku-rpc`, `pikku-mcp`, `pikku-queue`, `pikku-cron`, `pikku-trigger`, `pikku-cli`, `pikku-agent`, `pikku-workflow`
-- **Authorization**: `pikku-security` (authentication/sessions), `pikku-permissions` (permission checks, scopes), `pikku-middleware` (global/tag/route middleware)
-- **Infrastructure**: `pikku-services`, `pikku-config`
-- **Project introspection**: `pikku-info`
+Pikku generates `#pikku/*` imports per project and changes between versions. Anything you
+remember about its API may be from a different version than the one in this directory.
+Everything below is the mental model; `pikku doc` is the API surface, computed when the
+installed CLI was built. It needs no config and works outside a project.
+
+**Do not write an import, an export name, or an option key you have not seen in `pikku doc`.**
+A name that looks right and is not costs a full build cycle to discover. If the doc does not
+list it, it does not exist here — do not reach into `node_modules` or `.pikku` for something
+that will work anyway.
+
+### Start here, every time
+
+```
+pikku doc --ai
+```
+
+≈480 tokens, giving the 20 `#pikku/*` doors grouped by the job they do, and beside each the
+skill that teaches it. Read that routing table as the index to every other pikku skill — it is
+generated from the installed version, so it never names a skill for a door that no longer exists.
+
+Then go one of two ways. For **what exists** — the exact export name, its options, its
+signature — stay in the doc:
+
+```
+pikku doc http                 one door: its exports, each with a signature or a key count
+pikku doc wireHTTP             one export: signature, every key with what it is for
+pikku doc wireHTTP pikkuFunc   several topics in one call, rather than one call each
+```
+
+For **how it fits together** — composition, lifecycle, the generated client — load the skill
+the routing table named. The doc lists keys; it does not teach patterns.
+
+On a door screen, `N keys — pikku doc X` means a second call buys you something; an inlined
+signature means it does not. Error classes carry the HTTP status they are registered with,
+which is what decides whether a thrown error becomes a 409 or a 500.
+
+### Two things the doc will not give you
+
+- **Worked examples are sparse.** Most exports show a signature and keys, not usage.
+- **`pikkuFunc` lists keys that belong elsewhere.** `before`, `after`, `skip`, `surfaces` and
+  `requiresActor` apply only to scenarios; `workflowQueued`, `workflowRetries` and
+  `workflowTimeout` only to a workflow step. One shared config type offers all of them to
+  every function — each key says which it belongs to.
+
+`pikku doc` needs `@pikku/cli` 0.12.115 or newer. On an older pin, fall back to the door's
+skill and `pikku meta --json`, and do not guess at names the doc would have given you.
 
 ## Core Mental Model
 
@@ -59,7 +101,7 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 ## Concept Mapping: Generic Backend → Pikku
 
-Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
+Controllers/routes → `pikkuFunc`; auth/sessions → `pikku-security`, a separate install; authorization checks → `pikku-permissions`; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
 ## Functions
 
@@ -270,8 +312,8 @@ src/
 ├── schemas.ts           # Zod/Valibot schemas
 ├── services.ts          # Service factories (see pikku-services)
 ├── lifecycle.ts         # Server lifecycle hooks (pikku dev/serve only)
-├── middleware.ts         # Middleware definitions (see pikku-security)
-├── permissions.ts       # Permission definitions (see pikku-security)
+├── middleware.ts         # Middleware definitions (see pikku-middleware)
+├── permissions.ts       # Permission definitions (see pikku-permissions)
 └── .pikku/              # Generated (gitignored)
     ├── function/        # #pikku/function
     ├── http/            # #pikku/http

package/skills/pikku-concepts/references/concept-mapping.md

@@ -15,7 +15,7 @@ Authoritative mapping table plus side-by-side code examples showing how common b
 | **Dependency Injection**                | `pikkuServices` (singleton) + `pikkuWireServices` (per-request) | `pikku-services`  |
 | **WebSocket handlers**                  | `wireChannel`                                                   | `pikku-websocket` |
 | **Job Queue workers**                   | `wireQueueWorker`                                               | `pikku-queue`     |
-| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
+| **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-schedule`      |
 | **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
 | **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
 | **Type-safe API client**                | `npx pikku all` generates clients                               | `pikku-concepts`  |

package/skills/pikku-deploy-cloudflare/SKILL.md

@@ -5,7 +5,6 @@ description: >-
   tasks, and WebSocket via Durable Objects. TRIGGER when: code imports @pikku/cloudflare, user
   mentions Cloudflare Workers deployment, or worker entry uses ExportedHandler/wrangler.toml. DO
   NOT TRIGGER when: just defining functions/wirings without Cloudflare-specific code.
-installGroups: [fabric]
 ---
 
 # Pikku Cloudflare Workers Deployment

package/skills/pikku-deps/SKILL.md

@@ -12,7 +12,6 @@ description: >-
   reading/rendering audit.json. DO NOT TRIGGER when: user asks about authentication/sessions/JWT
   (use pikku-security), permissions (use pikku-permissions), or secrets/env vars (use
   pikku-config).
-installGroups: [core]
 ---
 
 # Pikku Dependency Audit

package/skills/pikku-emails/SKILL.md

@@ -10,7 +10,6 @@ description: >-
   email (verification, password reset, invitation, receipt), wire email sending, or translate an
   email. DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows
   in general (use pikku-better-auth).
-installGroups: [core]
 ---
 
 # Pikku Emails

package/skills/pikku-fabric/SKILL.md

@@ -273,13 +273,64 @@ reload).
 pikku fabric login              # opens a browser; needs a human, wait for it
 pikku fabric init https://github.com/<owner>/<repo>
 pikku fabric validate           # must pass clean
-pikku fabric deploy plan --production
-pikku fabric deploy apply --production --auto-apply
+pikku fabric deploy apply --production --sync --auto-approve
 ```
 
+There is no `deploy plan` subcommand — `apply` runs the same auth, git-safety
+and ref resolution itself, and fabric produces the real plan server-side.
+
 `apply` confirms before deploying, and with no TTY to ask — CI, an agent shell —
-it refuses rather than hangs. `--auto-apply` supplies that confirmation; drop it
-only when a human is at a real terminal.
+it refuses rather than hangs. `--auto-approve` supplies that confirmation; drop
+it only when a human is at a real terminal.
+
+By default `apply` queues the deploy, prints the deployment id and returns. That
+tells you nothing about whether it worked. `--sync` waits for a terminal state
+and exits non-zero unless the deployment went live, which is the only form worth
+running in CI:
+
+| exit | meaning |
+| ---- | ------- |
+| 0 | live (or queued, without `--sync`) |
+| 1 | the command could not run — not logged in, unsafe git state, bad flags |
+| 2 | the deployment failed, errored, timed out server-side, or was cancelled |
+| 3 | the deployment is blocked and nothing the CLI can do will unblock it |
+| 4 | the wait hit `--timeout` with the deployment still in flight |
+
+Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
+Why it parked is the whole story, and it is `statusReason`, not `status`:
+
+- `awaiting_approval` — the plan is fine, a human has to publish it.
+  `--auto-approve` does that; without it you get exit 3 and the command to run.
+  One exception: if fabric marked any pending migration **destructive** — a
+  drop, a truncate, a rewrite — `--auto-approve` alone declines and exits 3,
+  because a standing yes was given before anyone knew the plan dropped a table.
+  The CLI lists the migrations and fabric's reasons; `--allow-destructive`
+  accepts them for that deploy.
+- `needs_config` — a declared secret or variable has no value covering the
+  stage. The CLI names them. `--auto-approve` will **not** force this through;
+  set the values (`pikku fabric secrets set <name>`) and re-attach.
+- `needs_attention` — the plan is red. Nothing to approve.
+
+`--sync` defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
+it prints the deployment id and the re-attach command rather than lying about
+the outcome.
+
+Splitting kick-off from waiting across two CI jobs is the reason
+`--deployment-id` exists:
+
+```bash
+id=$(pikku fabric deploy apply --production --auto-approve --json | jq -r 'select(.event=="result").deploymentId')
+# …later, in another job…
+pikku fabric deploy apply --deployment-id "$id" --sync --auto-approve
+```
+
+`--deployment-id` skips the git safety check entirely (the deployment already
+pins a sha, and the checkout is allowed to have moved on) and refuses to be
+combined with `--branch`/`--production`, which would let the two disagree.
+
+Under `--json`, `--sync` emits one NDJSON event per line — `created`/`attached`,
+`status` on each transition, `blocked`, `approved` — and the last line is the
+terminal result object, tagged `"event": "result"`.
 
 `init` adopts a **GitHub** repo, and adoption goes through the Pikku Fabric
 GitHub App — the app has to be installed on the account or org that owns the

package/skills/pikku-feature/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-feature
 description: 'Drive create-a-feature work inside a Pikku project that already exists: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
-installGroups: [core]
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *)
 argument-hint: '<feature description>'
 ---

package/skills/pikku-gateway-slack/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   parseSlashCommand, buildSlackInstallUrl, or user asks about Slack integration, Slack bots, or
   @pikku/gateway-slack. DO NOT TRIGGER when: user asks about general gateway/webhook patterns (use
   pikku-trigger).
+installGroups: [core]
 ---
 
 # Pikku Gateway Slack

package/skills/pikku-i18n/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-i18n
 description: 'Wire i18n into a Pikku frontend with Paraglide JS (inlang). English by default, every user-facing string is a typed message function (`m.some__key()`) compiled from `messages/<locale>.json`, and additional languages are served under `/fr` `/de` URL prefixes. TRIGGER when: scaffolding or editing a frontend and writing user-facing text, adding a second language, or asked to "make this translatable / use tokens / add i18n". DO NOT TRIGGER for backend functions, error messages thrown from functions, or log output.'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku i18n (Paraglide JS)

package/skills/pikku-info/SKILL.md

@@ -8,7 +8,6 @@ description: >-
   routes/middleware/permissions", or needs to understand an existing Pikku codebase. DO NOT
   TRIGGER when: user is writing new code (use the specific wiring skill) or asking about Pikku
   concepts (use pikku-concepts).
-installGroups: [core]
 allowed-tools: Bash(yarn pikku info *)
 argument-hint: '[functions|tags|middleware|permissions] [--verbose] [--limit N]'
 ---

package/skills/pikku-knowledge/SKILL.md

@@ -13,7 +13,6 @@ description: >-
   brief to record. DO NOT TRIGGER when: user asks what
   functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
   note), or to write a scenario test (use pikku-scenario).
-installGroups: [core]
 ---
 
 # Pikku Knowledge

package/skills/pikku-kysely/SKILL.md

@@ -11,7 +11,6 @@ description: >-
   PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
   about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB (use pikku-mongodb) or
   Redis (use pikku-redis).
-installGroups: [core]
 ---
 
 # Pikku Kysely (SQL Database Services)

package/skills/pikku-paraglide/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-paraglide
 description: 'Generate typed, static enum-label maps for a Paraglide i18n frontend with `@pikku/paraglide`, and reconcile them against the database enum columns so a label can never silently drift from a DB value. Enum-valued labels live under a reserved `enum__<group>__<member>` message namespace; the generator emits `i18n-enum.gen.ts` typed `satisfies EnumLabel<DbEnum>`. TRIGGER when: labelling an enum/status/kind/role value in a Paraglide app, replacing a dynamic `mKey(...)`/`m[...]` lookup with a static map, wiring `@pikku/paraglide` into Vite, or reconciling i18n against `CHECK (col IN (...))` / Postgres enum columns. DO NOT TRIGGER for plain free-text UI copy (that is a normal `m.some_key()` message), backend errors, or logs.'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku Paraglide enum labels

package/skills/pikku-product-second-opinion/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-product-second-opinion
 description: 'Use when a non-technical owner (founder, PM, operator) wants a plain-language report on an app they hold but did not build — explaining how it works and how it could be better. Reads the .knowledge/ blueprint from pikku-software-archaeology and produces a layered, jargon-free report that credits what works, names what does not (with business impact + effort), and argues an opinionated better design. TRIGGER: "explain how my app works", "what would you do differently", "review my app for a non-technical audience", "I inherited/am stuck with an agency-built app", "is this built well?". DO NOT TRIGGER for: extracting the machine-readable blueprint itself (use pikku-software-archaeology), or an engineer-facing technical code review.'
-installGroups: [fabric]
 ---
 
 # Product Second Opinion

package/skills/pikku-queue/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   app. Covers wireQueueWorker, job enqueuing, progress tracking, retries, BullMQ and PgBoss
   adapters. TRIGGER when: code uses wireQueueWorker, user asks about background jobs, task queues,
   async processing, BullMQ, PgBoss, or job retries. DO NOT TRIGGER when: user asks about scheduled
-  cron tasks (use pikku-cron) or event-driven triggers (use pikku-trigger).
+  cron tasks (use pikku-schedule) or event-driven triggers (use pikku-trigger).
 installGroups: [core]
 ---
 

package/skills/pikku-react/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-react
 description: 'Set up @pikku/react in a React app: PikkuProvider context, createPikku factory, and the usePikkuRPC / usePikkuFetch hooks for direct (non-React-Query) calls. TRIGGER when: the user is bootstrapping a React frontend that talks to a Pikku backend, asks how to wire `PikkuProvider`, or needs to make one-off RPC calls outside of useQuery/useMutation. TRIGGER when: user asks about the dev actor switcher, "sign in as" / quick-login UI, useDevActors, VITE_DEV_ACTORS, or the app-missing-actor-quick-login validate finding. DO NOT TRIGGER when: the user is asking about useQuery/useMutation hooks (use pikku-react-query) or about workflows (use pikku-workflows-client).'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku React

package/skills/pikku-react-query/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-react-query
 description: 'Use the Pikku auto-generated React Query hooks (`usePikkuQuery`, `usePikkuMutation`, `usePikkuInfiniteQuery`) to call backend RPC functions from a React frontend with full type safety. TRIGGER when: writing React components that need to call a Pikku function, fetch data, mutate data, or paginate; user mentions React Query, useQuery, useMutation, or building a frontend that talks to a Pikku backend. DO NOT TRIGGER when: working on the backend (use pikku-rpc / pikku-feature) or wiring a non-React frontend.'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku React Query Hooks

package/skills/pikku-realtime/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: pikku-realtime
 description: 'Use Pikku''s realtime feature — typed pub/sub events over WebSocket (multi-topic) or SSE (single-topic, auto-cleanup). Covers declaring EventHubTopics, scaffolding the /events channel, the auto-generated `PikkuRealtime` client, and publishing events from a function. TRIGGER when: the user asks for realtime updates, pub/sub, push notifications, server-sent events, websocket events, eventhub, or "live" data on the frontend. DO NOT TRIGGER when: the user wants RPC-style request/response (use pikku-rpc / pikku-react-query) or a custom one-off WebSocket channel (use pikku-websocket).'
-installGroups: [core]
 ---
 
 # Pikku Realtime

package/skills/pikku-rpc/SKILL.md

@@ -6,7 +6,6 @@ description: >-
   TRIGGER when: code uses wire.rpc or expose: true, user asks about calling one Pikku function
   from another, function composition, or RPC endpoints. DO NOT TRIGGER when: user asks about HTTP
   routes (use pikku-http) or addon cross-package calls (use pikku-addon).
-installGroups: [core]
 ---
 
 # Pikku RPC Wiring

package/skills/pikku-rtl/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-rtl
 description: 'Make a Pikku frontend work in both English (LTR) and Arabic / right-to-left languages. Direction is derived from the active locale, applied once at the document root, and the layout mirrors itself — but only if styling is written flow-relative (margin-inline-start, text-align: start, Mantine ms/me) instead of left/right. TRIGGER when: adding Arabic (or Hebrew/Farsi/Urdu), asked to "support RTL / right-to-left / bidi / mirror the layout", or writing layout styles in an app that may run RTL. Builds on pikku-i18n (an RTL language is just another locale file). DO NOT TRIGGER for backend functions or for LTR-only copy changes.'
-installGroups: [core]
+installGroups: [client]
 ---
 
 # Pikku RTL (Arabic + English)

package/skills/pikku-scenario/SKILL.md

@@ -534,6 +534,32 @@ export const opensTheCart = pikkuScenarioStep<
 - `pikku scenario run <env> --no-browser` **skips** scenarios containing browser steps and reports them as skipped — it does not fail them. That is how a machine with no browser stays green.
 - Playwright auto-waits; do not wrap `page.click` in `expectEventually`.
 
+#### Locate by message key, never by rendered copy
+
+If the app is translated, **no step may contain a user-visible string.** `getByLabel('Full Name')` passes only while the browser happens to render the base locale, and any copy edit turns it into a selector timeout that points at the wizard rather than at the rename that caused it — the test looks broken where it is merely stale.
+
+The message catalogue already holds the string under a key. Read it from there. Type the lookup off the catalogue JSON so a renamed or misspelled key is a **compile** error rather than a run-time timeout:
+
+```typescript
+// tests/scenarios/i18n.ts
+import type messages from '../../../../apps/web/messages/en.json'
+
+export type MessageKey = keyof typeof messages
+
+export const t = (key: MessageKey, locale = baseLocale): string => { /* … */ }
+```
+
+```typescript
+await page.getByLabel(t('jobs_apply_fullname')).fill(identity.name)
+await page.getByRole('button', { name: t('jobs_apply_submit'), exact: true }).click()
+```
+
+- Type off `messages/<baseLocale>.json`, **not** the generated Paraglide output — `i18n/paraglide/` is build output, so typing against it makes the tests unbuildable until the app has been built. The JSON is the tracked source.
+- Fall back to the base locale for a key a locale has not translated. That is what Paraglide does at run time, so a helper that throws instead would disagree with the screen the test is looking at.
+- This is not only about locators. A copy literal passed to a **project helper** (`pick('Where would you like to work?', …)`) reaches the DOM the same way, and so does a pane name quoted back in a failure message. `pikku fabric validate` scans every string in a `*.steps.ts` / `*.scenario.ts` against the base catalogue and errors on any verbatim match, wherever it sits.
+- A regex locator (`{ name: /^Next$/i }`) hides the literal but not the problem. `{ name: t('key'), exact: true }` is both stricter and locale-correct.
+- Strings the catalogue does not own — a test id, a fixture filename, a seeded value — stay literal. The catalogue is the test for whether something is copy.
+
 ## Configuration
 
 Personas, actors and environments live in `pikku.config.json`:
@@ -628,7 +654,7 @@ An actor with no `persona` is its own persona, so a project that never declares
 ### The same actors sign a human in
 
 Declared actors are not only for automated runs. `signInPath` is Better Auth's
-`actor` plugin (see `pikku-better-auth`), which any caller can post to — so the
+`actor` plugin (see `pikku-better-auth`, a separate install), which any caller can post to — so the
 frontend gets a one-click "Sign in as …" switcher over the **same** list, and an
 app can be reviewed as each kind of user without anyone knowing a seed password.
 
@@ -639,7 +665,7 @@ control renders nothing there — but gate the reads on your bundler's dev flag
 anyway (`import.meta.env.DEV ? … : undefined`) so the secret never reaches a
 production bundle in the first place.
 
-Do not hand-roll the switcher: `useDevActors()` (`pikku-react`) is the logic and
+Do not hand-roll the switcher: `useDevActors()` (`pikku-react`, a separate install) is the logic and
 `<DevActorSwitcher />` from `@pikku/mantine/dev` is a ready rendering of it.
 `pikku fabric validate` **requires** any frontend with a login screen to ship
 one — without it a reviewer is locked out of their own sandbox.
@@ -758,6 +784,7 @@ Services are plain objects — a Pikku function is pure business logic, so a moc
 | `sleep()` before asserting                          | Use `expectEventually`.                                                                                                     |
 | A step named `clicksAddToBasket` / `opensThePage`   | That is an action, not an intent. Name the step for what the actor wanted; put the clicking in a utility.                   |
 | A browser step that assumes it is already on a page | It can then only run mid-flow. Arrive first — check the URL, navigate if needed.                                            |
+| `getByLabel('Full Name')` in a translated app        | Passes only in the base locale, and a copy edit breaks it as an unexplained timeout. Locate by message key.                 |
 | A `browser` binding guarding `if (!browser)`        | The binding guarantees it. The guard hides the real error, which is a missing actor (`PKU677`).                             |
 | A step with a `func:` instead of a surface binding  | There is no `func` on a step. Bodies live under `default` / `browser` / `cli`; a step with none throws at load.             |
 | `expectEventually` in a `pikkuWorkflowFunc`         | `PKU675` — scenario-only.                                                                                                   |