@pikku/skills 0.12.22 → 0.12.26

package/skills/{pikku-deploy-fastify/SKILL.md → pikku-deploy/references/fastify.md}

@@ -1,31 +1,11 @@
----
-name: pikku-deploy-fastify
-description: >-
-  Use when deploying a Pikku app with Fastify. Covers PikkuFastifyServer standalone and
-  pikkuFastifyPlugin for existing Fastify apps. TRIGGER when: code imports @pikku/fastify or
-  @pikku/fastify-plugin, user mentions Fastify deployment, or start.ts creates a
-  PikkuFastifyServer. DO NOT TRIGGER when: just defining functions/wirings without
-  Fastify-specific code.
----
-
-# Pikku Fastify Deployment
-
-## Agent Operating Procedure
-
-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.
-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.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
-
-## Standalone Server
+# Fastify
 
 ```bash
 yarn add @pikku/fastify
 ```
 
+## Standalone server
+
 ```typescript
 import { PikkuFastifyServer } from '@pikku/fastify'
 import './.pikku/pikku-bootstrap.gen.js'
@@ -43,16 +23,12 @@ await appServer.init()
 await appServer.start()
 ```
 
-**Constructor:** `new PikkuFastifyServer(config, logger)`
-
-**Config extends CoreConfig with:** `port`, `hostname`, `healthCheckPath?`
-
-**Methods:** `init(httpOptions?: RunHTTPWiringOptions)`, `start()`, `stop()`, `enableExitOnSigInt()`
-
-**Property:** `app: FastifyInstance` — Direct access to Fastify instance.
+The config extends `CoreConfig` with `port`, `hostname` and an optional
+`healthCheckPath`. `app: FastifyInstance` is exposed for direct access.
 
-`enableCors` exists on the class but **throws `Method not implemented.`** — unlike
-the Express server. Register `@fastify/cors` on `app` yourself before `init()`.
+`enableCors` exists on the class but **throws `Method not implemented.`** —
+unlike the Express server. Register `@fastify/cors` on `app` yourself before
+`init()`.
 
 Unlike the Express server, the health check is registered by `init()`, not the
 constructor, so nothing answers before `init` runs. `init` also passes

package/skills/{pikku-deploy-lambda/SKILL.md → pikku-deploy/references/lambda.md}

@@ -1,30 +1,10 @@
----
-name: pikku-deploy-lambda
-description: >-
-  Use when deploying a Pikku app to AWS Lambda. Covers HTTP handlers, scheduled tasks, SQS queue
-  workers, WebSocket via API Gateway, and cold start caching. TRIGGER when: code imports
-  @pikku/lambda, user mentions Lambda/serverless/AWS deployment, or handler files export
-  Lambda-typed functions. DO NOT TRIGGER when: just defining functions/wirings without
-  Lambda-specific code.
----
-
-# Pikku AWS Lambda Deployment
-
-## Agent Operating Procedure
-
-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.
-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.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+# AWS Lambda
 
 ```bash
 yarn add @pikku/lambda
 ```
 
-## Cold Start Pattern
+## Cold start pattern
 
 Cache singleton services across Lambda invocations:
 
@@ -53,7 +33,7 @@ named exports (`handler`, `queue`, `scheduled`, or `connect`/`disconnect`/
 `default`) that `serverless.yml` references. Hand-written handlers are for cases
 the codegen does not cover.
 
-## HTTP Handler
+## HTTP handler
 
 Pick the entry point that matches the API Gateway payload version — they take
 different event types and are not interchangeable:
@@ -91,7 +71,7 @@ carried.
 Neither takes `RunHTTPWiringOptions` — there is no `maxBodySize` or
 `respondWith404` knob here; API Gateway's own payload limit is the bound.
 
-## Scheduled Tasks
+## Scheduled tasks
 
 ```typescript
 import type { ScheduledHandler } from 'aws-lambda'
@@ -113,7 +93,7 @@ Reach for `runScheduledTask({ name })` from `@pikku/core/scheduler` directly
 only when one Lambda genuinely bundles several tasks that must fire on separate
 schedules.
 
-## SQS Queue Worker
+## SQS queue worker
 
 ```typescript
 import type { SQSHandler } from 'aws-lambda'
@@ -181,8 +161,7 @@ is a separate invocation, so nothing survives in memory between `$connect` and
 `LambdaEventHubService` handles cross-connection messaging and takes
 `(logger, event, channelStore, eventHubStore)` — the `event` is needed to derive
 the API Gateway Management endpoint, so it is constructed per invocation, not
-once at cold start. It also needs an `EventHubStore` alongside the channel
-store.
+once at cold start. It also needs an `EventHubStore` alongside the channel store.
 
 Two behaviours to design around: **binary payloads throw** (`Binary data is not
 supported on serverless lambdas`), and any `PostToConnection` failure removes

package/skills/{pikku-deploy-nextjs/SKILL.md → pikku-deploy/references/nextjs.md}

@@ -1,29 +1,10 @@
----
-name: pikku-deploy-nextjs
-description: >-
-  Use when deploying a Pikku app with Next.js. Covers API route handlers, server-side data
-  fetching, and RPC calls from Server Components. TRIGGER when: code imports @pikku/next, user
-  mentions Next.js integration, or app/api route files use pikkuAPIRequest. DO NOT TRIGGER when:
-  just defining functions/wirings without Next.js-specific code.
----
-
-# Pikku Next.js Deployment
-
-## Agent Operating Procedure
-
-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.
-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.
-5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+# Next.js
 
 ```bash
 yarn add @pikku/next
 ```
 
-## API Route Handler
+## API route handler
 
 The CLI generates a typed wrapper. Use it in a catch-all route:
 
@@ -49,7 +30,7 @@ choose. It also passes no `RunHTTPWiringOptions`: to set `maxBodySize` or
 `respondWith404` you need your own handler over `new PikkuNextJS(...)` calling
 `apiRequest(req, options)`.
 
-## Server-Side Data Fetching
+## Server-side data fetching
 
 Use the generated `pikku()` helper in Server Components or Server Actions:
 
@@ -69,12 +50,9 @@ const config = await staticGet('/config')
 const result = await rpc('calculateTax', { amount: 100, region: 'US' })
 ```
 
-**Dynamic vs Static:**
-
-- `get`, `post`, `patch`, `del`, `rpc` — read `next/headers` cookies and headers,
-  so they force the component dynamic
-- `staticGet`, `staticPost`, `staticRPC` — no request context, safe for
-  precompile/ISR
+`get`, `post`, `patch`, `del` and `rpc` read `next/headers` cookies and headers,
+so they force the component dynamic. `staticGet`, `staticPost` and `staticRPC`
+have no request context and are safe for precompile/ISR.
 
 The static variants pass `skipUserSession: true`, so a wiring that expects a
 session sees none. That is the real difference — not just where they can run.
@@ -85,7 +63,7 @@ Both paths run with `bubbleErrors: true`, so a failing wiring **throws** in your
 Server Component rather than resolving to an error status. Wrap the call, or let
 the Next.js error boundary take it.
 
-## How It Works
+## How it works
 
 `PikkuNextJS` lazy-initializes on first request:
 
@@ -95,8 +73,6 @@ import { PikkuNextJS } from '@pikku/next'
 const pikku = new PikkuNextJS(createConfig, createSingletonServices)
 ```
 
-**Constructor:** `new PikkuNextJS(createConfig | undefined, createSingletonServices)`
-
 Both arguments are positional and `createConfig` is only optional in the sense
 that passing `undefined` substitutes an empty config —
 `createSingletonServices` is required.
@@ -113,8 +89,8 @@ route definitions.
 - **`PikkuNextJSWorkerRPC({ fetcher })`** — same surface as `PikkuNextJS`, but
   every call is dispatched through a `Fetcher` (a Cloudflare service binding, a
   local HTTP client, a fabric dispatcher) instead of loading function code
-  in-process. Use it to keep functions out of the SSR bundle. A non-2xx
-  response throws with the status and body text.
+  in-process. Use it to keep functions out of the SSR bundle. A non-2xx response
+  throws with the status and body text.
 - **`toNextJsAuthHandler(auth)`** — wraps a better-auth instance or handler
   function for an auth route. The three-argument form
   `(pikkuAuthFactory, createConfig, createSingletonServices)` resolves a Pikku

package/skills/pikku-deploy/references/uws.md

@@ -0,0 +1,72 @@
+# uWebSockets.js
+
+Highest-throughput option among Pikku's runtimes. Handles both HTTP and
+WebSocket automatically.
+
+```bash
+yarn add @pikku/uws
+```
+
+```typescript
+import { PikkuUWSServer } from '@pikku/uws'
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const appServer = new PikkuUWSServer(
+  { ...config, hostname: 'localhost', port: 4002 },
+  singletonServices.logger
+)
+appServer.enableExitOnSigInt()
+await appServer.init()
+await appServer.start()
+```
+
+The config extends `CoreConfig` with `port`, `hostname` and an optional
+`healthCheckPath`. `app: uWS.App` is exposed for direct access.
+
+## What the server does and does not give you
+
+`init()` registers three things in order: the health check (`healthCheckPath`,
+default `/health-check`), a catch-all `app.any('/*')` HTTP handler, and a
+catch-all `app.ws('/*')` websocket handler. Nothing is registered by the
+constructor, so nothing answers before `init` runs.
+
+**There is no `enableCors`, no static assets and no `content` support** — unlike
+the Express server. The class is explicitly a prototyping convenience; for
+anything that needs extra handlers, use `@pikku/uws-handler` directly and treat
+`pikku-uws-server.ts` as the template (that is what its own JSDoc says).
+
+`httpOptions` reaches the HTTP handler only. The websocket handler is
+constructed with a fixed `{ logger, logRoutes: true }`, so per-request options
+do not apply to the upgrade path. `loadSchemas` is also never passed by the
+server, so schemas compile lazily on first use rather than at startup — pass
+`loadSchemas: true` in `httpOptions` if you want the startup cost paid up front.
+
+`stop()` closes the listen socket and then waits a fixed 2 seconds for
+connections to drain. Called before `start()`, it throws a bare **string**, not
+an `Error`, so `catch (e) { e.message }` reads `undefined`.
+
+## Body limits
+
+uWS hands over raw chunks with no limit of its own, so the handler counts the
+bytes itself. A request over `maxBodySize` (default `DEFAULT_MAX_BODY_SIZE`) is
+answered `413` with a `PayloadTooLargeError` body, and the chunks are dropped
+rather than concatenated — an oversized request never accumulates in memory. A
+`content-length` header that already exceeds the limit short-circuits before any
+data arrives.
+
+## Handlers directly (own uWS app)
+
+```typescript
+import { pikkuHTTPHandler, pikkuWebsocketHandler } from '@pikku/uws-handler'
+
+app.any('/*', pikkuHTTPHandler({ logger, logRoutes: true, loadSchemas: true }))
+app.ws('/*', pikkuWebsocketHandler({ logger, logRoutes: true }))
+```
+
+Both take `{ logger, logRoutes?, loadSchemas? } & RunHTTPWiringOptions`.
+
+For a WebSocket-only server on the `ws` library instead, see `ws.md`.

package/skills/pikku-deploy/references/ws.md

@@ -0,0 +1,75 @@
+# ws (WebSocket only)
+
+`@pikku/ws` connects Pikku's channel system to a Node.js WebSocket server built
+on the [ws](https://github.com/websockets/ws) library. Use it for a
+WebSocket-only server; for HTTP and WebSocket on one port see `uws.md`, and when
+the WebSocket server shares a port with an existing HTTP app see `express.md` or
+`fastify.md`.
+
+```bash
+yarn add @pikku/ws ws
+```
+
+The package exports one function, `pikkuWebsocketHandler` — there is no server
+class. You own the `http.Server` and the `WebSocketServer`; the handler attaches
+the upgrade and message plumbing to them.
+
+```typescript
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
+import { stopSingletonServices } from '@pikku/core'
+import { Server } from 'http'
+import { WebSocketServer } from 'ws'
+
+import './.pikku/pikku-bootstrap.gen.js'
+import { createConfig, createSingletonServices } from './services.js'
+
+const config = await createConfig()
+const singletonServices = await createSingletonServices(config)
+
+const server = new Server()
+const wss = new WebSocketServer({
+  noServer: true,
+  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+})
+
+pikkuWebsocketHandler({
+  server,
+  wss,
+  logger: singletonServices.logger,
+  logRoutes: true, // print the wired channels at startup
+  loadSchemas: true, // compile input schemas up front
+})
+
+server.listen(4002, 'localhost')
+
+process.on('SIGINT', async () => {
+  await stopSingletonServices()
+  wss.close()
+  server.close()
+  process.exit(0)
+})
+```
+
+## `noServer: true` is required, not stylistic
+
+The handler listens for the HTTP server's own `upgrade` event, opens the channel
+— running Pikku's middleware chain, auth and CORS against the upgrade request
+first — and only then calls `wss.handleUpgrade`. A `WebSocketServer` bound to the
+server directly would take the socket before any of that ran.
+
+An upgrade the channel rejects gets the socket destroyed, and an auth failure is
+written as a real HTTP response on the raw socket rather than a silent drop.
+
+## Services and the event hub
+
+Services come from the bootstrap import and the global singleton registry, which
+is why nothing is passed in. The event hub is taken from
+`singletonServices.eventHub` when it is a `LocalEventHubService`, and a local one
+is created otherwise — so a single-process app gets pub/sub for free, while a
+multi-instance deployment must register a distributed hub.
+
+The options type also extends `RunHTTPWiringOptions`, so per-request settings
+such as `respondWith404`, `coerceDataFromSchema` and `bubbleErrors` are accepted
+here too.
+
+On shutdown, call `stopSingletonServices()` then close `wss` and `server`.

package/skills/pikku-emails/SKILL.md

@@ -9,8 +9,8 @@ description: >-
   or emailTemplatesDir in pikku.config.json. TRIGGER when: user asks to add/edit a transactional
   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: [fabric]
+  in general (use pikku-auth).
+installGroups: [core]
 ---
 
 # Pikku Emails
@@ -187,6 +187,7 @@ async send(input: SendEmailInput) {
   const r = renderEmailTemplate(input.template as RenderEmailInput<EmailTemplateName>)
   return this.delegate.send({
     to: input.to, from: input.from, subject: r.subject, html: r.html,
+    attachments: input.attachments,
     ...(r.text ? { text: r.text } : {}),
   })
 }

package/skills/pikku-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-fabric
-description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. TRIGGER when: user asks about a `pikku fabric validate` finding, including app-missing-actor-quick-login. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
+description: 'Build, convert and debug apps on the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, the pikku-verify workflow, and reading logs, traces and metrics from a deployed stage. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, asking about Fabric deployment, database or project conventions, asking about a `pikku fabric validate` finding including app-missing-actor-quick-login, or a deployed stage is erroring, timing out or behaving differently than local ("why is prod failing", "check the logs"). DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy instead — or the failure reproduces locally, which is where to debug it.'
 installGroups: [fabric]
 ---
 
@@ -21,7 +21,7 @@ Use this skill as an execution checklist, not reference material.
 5. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 6. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
 
-Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-http`, `pikku-services`, etc.
+Fabric is a serverless deployment platform for Pikku apps. Every Fabric app runs on Cloudflare Workers with a SQLite database (via libSQL/Turso). This skill covers what's unique to Fabric. For general Pikku concepts, function authoring, HTTP wiring, and more, see `pikku-concepts`, `pikku-wiring`, `pikku-services`, etc.
 
 ## Before you start
 
@@ -291,24 +291,40 @@ 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 apply --production --sync --auto-approve
+pikku fabric deploy apply --production -y
 ```
 
+The branch is positional and defaults to the checked-out one, and `-y` is the
+short form of `--auto-approve`, so a one-shot deploy is:
+
+```bash
+pikku fabric deploy apply -y            # the branch you are standing on
+pikku fabric deploy apply my-branch -y  # a named one
+```
+
+`-y` answers the prompts and nothing more. It does **not** approve migrations
+that drop or rewrite data — that stays `--allow-destructive`, typed out on
+purpose.
+
+Inferring the branch is safe because the git safety check refuses any branch
+without an upstream or out of sync with it, so it cannot ship an unpushed
+commit; the branch it picked is printed before the build starts. A detached
+HEAD is refused by name rather than travelling on as a branch called `HEAD`.
+
 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-approve` supplies that confirmation; drop
-it only when a human is at a real terminal.
+it refuses rather than hangs. `--auto-approve` (`-y`) 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:
+`apply` waits for a terminal state and exits non-zero unless the deployment went
+live. `--detach` opts out — it queues the deploy, prints the deployment id and
+returns 0, which tells you nothing about whether it worked:
 
 | exit | meaning                                                                 |
 | ---- | ----------------------------------------------------------------------- |
-| 0    | live (or queued, without `--sync`)                                      |
+| 0    | live (or queued, under `--detach`)                                      |
 | 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    |
@@ -318,14 +334,14 @@ 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.
+  `-y` 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,
+  drop, a truncate, a rewrite — `-y` 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.
+  accepts them for that deploy, and `-y` implies it.
 - `needs_config` — a declared secret or variable has no value covering the
-  stage. The CLI names them. `--auto-approve` will **not** force this through;
+  stage. The CLI names them. `-y` will **not** force this through;
   set the values and re-attach — `pikku fabric secrets set <name>` for a
   declared secret, `pikku fabric variables set <name> --value <v>` for a declared
   variable. They are separate stores: a secret is sealed to the stage and cannot
@@ -334,24 +350,25 @@ Why it parked is the whole story, and it is `statusReason`, not `status`:
   stage exactly as it is from `.env`, and `--value '"true"'` is the string.
 - `needs_attention` — the plan is red. Nothing to approve.
 
-`--sync` defaults to a 900s ceiling; `--timeout <seconds>` moves it. On timeout
+The wait 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:
+`--deployment-id` exists, and what `--detach` is for — the first job here has to
+return the id and exit rather than wait:
 
 ```bash
-id=$(pikku fabric deploy apply --production --auto-approve --json | jq -r 'select(.event=="result").deploymentId')
+id=$(pikku fabric deploy apply --production -y --detach --json | jq -r 'select(.event=="result").deploymentId')
 # …later, in another job…
-pikku fabric deploy apply --deployment-id "$id" --sync --auto-approve
+pikku fabric deploy apply --deployment-id "$id" -y
 ```
 
 `--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.
+combined with a branch or `--production`, which would let the two disagree.
 
-Under `--json`, `--sync` emits one NDJSON event per line — `created`/`attached`,
+Under `--json`, the wait 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"`.
 
@@ -440,3 +457,13 @@ Fix every `error` and `warn` in the output before continuing. Then:
 6. **Add `pikkufabric.config.json`** at project root with `projectId`, `production.domain`, and `frontends` (production is always `main`, so there is no `production.branch`).
 7. **Run `pikku all`** — verify codegen succeeds and there are no type errors.
 8. **Run `pikku fabric validate`** once more to confirm no structural issues remain.
+
+## A deployed stage misbehaving
+
+Reproduce locally first — a deployed stage adds cost and latency to every
+iteration, and a failure that reproduces locally is a local debugging problem.
+When it only happens deployed, read `references/debugging.md`: start from
+`errors` rather than `logs` (they are already filtered and carry the traceId),
+follow one trace end to end before forming a theory, and confirm the fix against
+the same stage. A deploy that *failed* is a build or config problem and belongs
+above, not there.

package/skills/{pikku-fabric-debug/SKILL.md → pikku-fabric/references/debugging.md}

@@ -1,9 +1,3 @@
----
-name: pikku-fabric-debug
-description: 'Debug a deployed Fabric stage from the CLI — read logs, find recent errors, follow a single request end-to-end by traceId, and check request/error/latency metrics. TRIGGER when: a deployed Fabric app is erroring, timing out, or behaving differently than local; the user asks "why is prod failing", "check the logs", "what happened to this request"; or a deploy succeeded but the app misbehaves. DO NOT TRIGGER when: the failure reproduces locally (debug it locally), the deploy itself failed (use pikku-fabric — that is a build/config problem, not a runtime one), or the project is not deployed to Fabric.'
-installGroups: [fabric]
----
-
 # Debugging a deployed Fabric stage
 
 ## Agent Operating Procedure