@pikku/skills 0.12.52 → 0.12.55

package/skills/pikku-fabric/references/debugging.md

@@ -1,110 +0,0 @@
-# Debugging a deployed Fabric stage
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Reproduce locally first. If it fails locally too, debug it there — the
-   deployed stage adds cost and latency to every iteration.
-2. Start from `errors`, not `logs`. Errors are already filtered and carry the
-   traceId that unlocks the rest.
-3. Follow one trace end-to-end before forming a theory. A single failing request
-   tells you more than a hundred unrelated log lines.
-4. Fix the source cause and redeploy. Never leave the diagnosis at "it is flaky".
-5. Confirm the fix against the same stage — recheck `errors` for the function.
-
-Every command below requires a logged-in CLI and a linked project. Both fail
-with the exact remediation if not:
-
-```
-Not logged in. Run `pikku fabric login` first.
-No fabric project linked. Run `pikku fabric link` first.
-```
-
-## The loop
-
-**1 — What is broken?**
-
-```bash
-pikku fabric errors -b main                 # branch defaults to main
-pikku fabric errors -b main --function createOrder
-```
-
-Prints a `WHEN | FUNCTION | TRACE | MESSAGE` table. The message is **truncated
-to 100 characters** — treat it as a label, not the full error. The TRACE column
-is the input to the next step.
-
-**2 — What happened in that one request?**
-
-```bash
-pikku fabric trace <traceId> -b main
-pikku fabric trace <traceId> -b main --json
-```
-
-`--branch` is **required** here (no default). Each event prints as:
-
-```
-<timestamp> <scriptName> <wireType>:<wireId> <duration>ms — <error|message|outcome>
-```
-
-This is the whole request across the stage — every unit it touched, in order,
-with per-event durations. The last event before the failure is where to look.
-
-**3 — Is it one request or the whole stage?**
-
-```bash
-pikku fabric metrics -b main                       # last 24h
-pikku fabric metrics -b main --hours 2 --function createOrder
-```
-
-`--branch` is **required** here too; `--hours` defaults to 24.
-
-Rows are `reqs= err= (rate%) avg= min= max=` per bucket. A single bad request
-with a healthy error rate is a data problem; a climbing error rate is a
-deployment or dependency problem. `--json` additionally returns a `wireTypes`
-breakdown (requests per http/queue/scheduler/…) that the table output omits.
-
-**4 — Wider context around the failure**
-
-```bash
-pikku fabric logs -b main
-pikku fabric logs -b main --level warn
-pikku fabric logs -b main -f              # follow
-```
-
-`--branch` is **required** — `logs` throws `Specify --branch <branch-name>.`
-without it, even though the flag reads as optional.
-
-**5 — Is the running code the code you think it is?**
-
-```bash
-pikku fabric status     # active + in-flight deployment, per stage, with gitSha
-```
-
-Check this _before_ deep-diving. A stage still serving an older `gitSha`, or a
-deploy stuck in flight, explains a whole class of "my fix did nothing".
-
-## Known gaps — do not misread these as bugs in your app
-
-- **`pikku fabric logs --since` and `--deployment` are accepted and ignored.**
-  They are declared as options but the command never reads them, so
-  `--since 15m` silently returns the same default window as no flag at all. Do
-  not conclude "nothing happened in the last 15 minutes" from it. Narrow by
-  `--level`, or by `--function` via `errors`, instead.
-- **`--follow` is a 2-second client-side poll, not a server stream** — despite
-  its own help text reading "Stream new logs (SSE)". Server-side SSE is planned;
-  the backend doesn't push natively today. It
-  dedups against what it already printed, so it behaves like `tail -f`, but new
-  entries can appear up to ~2s late and it holds the process open until killed.
-
-## What NOT to do
-
-- **Do not SSH anywhere or query the telemetry backend directly.** These
-  commands are the supported surface; anything lower-level is Fabric-internal
-  and will not exist for your project.
-- **Do not debug by redeploying with added `console.log`s.** Get the traceId,
-  read the trace. A deploy cycle per hypothesis is the slow path.
-- **Do not read the truncated `errors` message as the full error.** Always
-  confirm against `trace` before changing code.
-- **Do not treat an empty `errors` table as "the app is fine"** — a request that
-  returns a wrong 200 logs nothing. Check `metrics` for the outcome mix.

package/skills/pikku-mantine/SKILL.md

@@ -1,80 +0,0 @@
----
-name: pikku-mantine
-description: >-
-  Use when building a Mantine UI 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, and branching on
-  colour scheme without hardcoding a shade. TRIGGER when: putting a value from usePikkuQuery or an
-  RPC response on screen, writing margins/padding/alignment in Mantine props or CSS, choosing a date
-  input, or handling light/dark. 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).
-installGroups: [client]
----
-
-# Mantine on a Pikku client
-
-## Dates — always format before rendering
-
-The generated clients run `transformDates`, which revives **fully-zoned ISO-8601 instants** —
-`2026-03-14T08:12:00Z`, `2026-03-14T08:12:00.000+01:00` — into `Date` objects and touches nothing
-else. A bare `2026-03-14`, a zoneless `2026-03-14T08:12:00` and an impossible `2026-02-31T00:00:00Z`
-all stay the strings the server sent. So a field's runtime type follows the VALUE, not the schema:
-one column can arrive as a `Date` from one row and a string from the next.
-
-Two consequences, and both compile:
-
-- **A string method on one white-screens the page.** `row.createdAt.split('T')[0]` type-checks
-  against nothing useful and blows up at runtime. There is no string to slice.
-- **A raw `Date` dropped into JSX crashes the route.** `<Text>{row.createdAt}</Text>`, a table cell,
-  a `<Badge>` — React throws `Objects are not valid as a React child (found: [object Date])` and the
-  page falls into its error boundary. Nothing catches it before the screen is white, which makes it
-  the most common broken page in a build.
-
-**Format with dayjs.** It is Mantine's own date library, already shipped alongside `@mantine/dates`,
-and it takes either a `Date` or a string. Never `toLocaleDateString`, `date-fns` or `luxon`.
-
-```tsx
-import dayjs from 'dayjs'
-
-<Text>{dayjs(row.dueOn).format('D MMM YYYY')}</Text>        // 15 Jun 2026
-<Text>{dayjs(row.createdAt).format('D MMM YYYY, HH:mm')}</Text>
-```
-
-A relative "2 days ago" via dayjs `relativeTime` is fine. Coercing instead of formatting
-(`` `${d}` ``, `String(d)`, `d + ''`) does not crash but prints
-`Mon Jun 15 2026 02:00:00 GMT+0200` — a different bug, equally wrong.
-
-Date **inputs** are `@mantine/dates` — `DatePickerInput`, `DatePicker`, `Calendar` — never a raw
-`<TextInput type="date">`. Those are pickers and they are not a schedule: Mantine ships no
-week/time-grid component, so a diary, rota, timetable or booking week is a grid you build, not a
-`Calendar` with the time-of-day left out. `Calendar` with `renderDay` IS right for "a few things on
-each day of a month", like a content calendar or a holiday planner.
-
-All of this applies to stub and fixture dates exactly as it does to real data.
-
-## RTL-safe styles
-
-Write layout styles 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`, `pl`, `pr`        | `ms`, `me`, `ps`, `pe`                     |
-| `text-align: left/right`      | `text-align: start/end`                    |
-| `margin-left`, `margin-right` | `margin-inline-start`, `margin-inline-end` |
-| `flex-direction: row-reverse` | `dir` attribute or logical properties      |
-
-Mantine shorthand: `ms` = margin-inline-start, `me` = margin-inline-end, `ps` = padding-inline-start,
-`pe` = padding-inline-end.
-
-## Dark mode
-
-Use Mantine's `light-dark()` utility or `useMantineColorScheme`, and only with colours that already
-come from the theme — never introduce a literal colour or a shade string for one scheme.
-
-```tsx
-// Correct
-<Box bg="var(--mantine-color-body)">
-
-// Wrong — scheme branch with hardcoded Mantine shades
-<Box bg={theme.colorScheme === 'dark' ? 'dark.6' : 'gray.0'}>
-```

package/skills/pikku-scenario/references/personas.md

@@ -1,117 +0,0 @@
-# Personas and actors
-
-A **persona** is a person your product is for; an **actor** is one body that signs in as them. Every entry materialises exactly one actor, so `actors.<id>` exists for each declared persona and there is no second way to declare a login.
-
-- Two people of the same kind are two entries, not one persona with two logins — "you see yours, not theirs" is only testable with two customers.
-- Never write an email address: each is derived from the persona id and `scenarios.emailDomain`, and a hand-written one signs in as somebody who was never created.
-- `roles` is typechecked against `defineSystemRole`; an undeclared role is a build error.
-- A person who is only ever acted _upon_ — the account an admin bans — sets `runnable: false`: declared and seeded, never signed in, because a run as them would race the scenario that acts on them.
-- A persona holds only what is true of that kind of person for the app's whole lifetime (`name`, `jobTitle`, `description`, `personality`, `roles`, `goals`, `disposition`). What someone is trying to get done, and the circumstances they are doing it in, belong to the **scenario**, not to them.
-
-## Declaring personas in TypeScript
-
-There may be **one `definePersonas` call in the whole codebase** — one place to
-read the set from, one place to add to it. A second anywhere, including in the
-same file, is a critical. Generated files are exempt and never claim the slot.
-
-> [!WARNING]
-> The declaration is **read from source, never evaluated** — the CLI writes it
-> to JSON that a deployed stage carries without the app. So every value has to
-> be statically knowable, and a value that is not comes out as `undefined`
-> rather than as an error. Only `name` is checked, so a computed `personality`,
-> `jobTitle` or `description` is dropped in silence and the persona runs with a
-> blank temperament.
-
-What that admits and what it does not:
-
-```typescript
-personality: 'Wound up and short with it.' // read
-personality: `Wound up and short with it.
-  Says what she wants in a few blunt words.` // read — no ${} in it
-personality: 'Wound up. ' + 'Short with it.' // dropped, silently
-personality: TEMPERAMENTS.impatient // dropped, silently
-```
-
-A no-substitution template literal is a string literal as far as the reader is
-concerned, so it is the way to write a long personality across several lines —
-not a concatenation, and not a `prettier-ignore`d single line. Its newlines and
-leading indentation are kept verbatim and reach the model that way, which is
-harmless but worth knowing before you align it to the surrounding code.
-
-One more thing worth knowing before writing a rich persona: **`actor.converse`
-builds its prompt from `name`, `jobTitle`, `personality` and the scenario's
-`task` only.** Fields like `disposition`, `goals` and `roles` are read and
-stored, and the console shows them, but they do not reach the conversing
-persona's instructions. Anything that must shape how someone talks belongs in
-`personality` or in the task.
-
-A project that never declares a persona keeps working: a scenario that names no actor needs none.
-
-- `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
-- **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
-
-## Actors that call a third-party API
-
-An addon generated from an upstream API (Dolibarr, a CRM, a calendar) calls it
-with the signed-in user's own credential. An actor has none until one is stored
-for it, so every step that reaches the addon fails with `No <X> session`. Give
-the `actor` plugin a `credentials` option, and each actor carries its upstream
-credential into every session:
-
-- `names: ['dolibarr']` — the credentials to carry
-- `store: (name, value, userId) => credentialService.set(name, value, userId)`
-- `remove: (name, userId) => credentialService.delete(name, userId)`
-
-At each actor sign-in the plugin reads `ACTOR_CREDENTIAL_<PERSONA>_<NAME>` —
-`dan` + `dolibarr` is `ACTOR_CREDENTIAL_DAN_DOLIBARR` — and stores it with
-`credentialService.set` for that actor. A bare value is stored as `{ token }`
-(what a delegated or bearer credential holds); a JSON object is stored as-is,
-e.g. `{"apiKey":"…"}` for an API-key credential. Unset means the actor has no
-upstream credential: `remove` drops one stored at an earlier sign-in.
-
-- **Values live in `.env` (or CI secrets), never in `personas.ts` or code.**
-  Use a dedicated upstream test account per persona, not a real person's.
-- `read` defaults to `process.env`; a Worker passes `(key) => variables.get(key)`.
-- A malformed JSON value refuses the sign-in with a 500 that names the variable.
-- A delegated token expires upstream like any other; re-signing the actor
-  in re-stores whatever the variable holds now.
-
-## The same actors sign a human in
-
-Declared actors are not only for automated runs. `signInPath` is Better Auth's
-`actor` plugin (see `pikku-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.
-
-The switcher holds no credential. It lists personas from
-`/auth/sign-in/personas` and signs in by posting only a persona id to
-`/auth/sign-in/persona`; the server resolves the address. One server piece
-serves both, in the auth config:
-
-```ts snippet:personaSignIn
-```
-
-It is always open under `pikku dev`. A deployed stage needs actor
-sign-in opted in **and** its `devSwitcher` feature flag on; production never
-has the opt-in, so it lists nobody and refuses every persona sign-in.
-
-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.
-When the switcher is missing, it is one of three things, and none of them
-errors:
-
-- **The list is empty.** On a deployed stage that is the gate
-  doing its job — check the opt-in and the `devSwitcher` flag. Locally, check
-  the personas declare an `email` (via `scenarios.emailDomain`) and are not
-  `runnable: false`.
-- **`personaSignIn` is missing, or the frontend calls another API.** A dev
-  proxy (`VITE_API_PROXY`, default `http://localhost:3000`) that points at
-  another project's API lists that project's personas, or none.
-- **It is not mounted on the page you are looking at.** The template mounts it
-  on the login screen. A public homepage that replaces the `/` → `/app`
-  redirect needs its own `<DevActorSwitcher />` in the public layout.
-
-When the switcher lists personas but a click 404s, that persona has no `email`
-or is `runnable: false`.

package/skills/pikku-wiring/references/realtime-other-routes.md

@@ -1,23 +0,0 @@
-# Subscribing to other SSE / WebSocket routes
-
-The same `PikkuRealtime` client also handles generic SSE + channel routes (not just
-`/events` topics). Use the path; the base URL is inherited from `PikkuFetch`.
-
-```ts
-// Any `sse: true` HTTP route
-const sub = realtime.subscribeToSSE<{ progress: number }>(
-  `/workflow-run/${runId}/stream`,
-  (event) => setProgress(event.progress)
-)
-// later: sub.close()
-
-// Any wireChannel — open a raw socket, wrap in PikkuWebSocket for typed I/O
-const ws = realtime.connectToChannel('/ws/kanban')
-const typed = new PikkuWebSocket<'kanban-live'>(ws)
-typed.getRoute('command').subscribe('message', (data) => {
-  /* ... */
-})
-```
-
-Discover what's available with `pikku meta clients --json` — `channels` and any HTTP
-`sse: true` routes are listed there.