@pikku/skills 0.12.34 → 0.12.37

package/skills/pikku-n8n-import/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: pikku-n8n-import
 description: 'Use to import an n8n workflow JSON export into a runnable Pikku workflow. Triggers when the user says "import this n8n workflow", "convert this n8n export to pikku", points at an n8n `.json` export or a directory of them, or picks up after `pikku import n8n` left throwing stub functions (`STUB — generated from n8n …`, `— implement me`) or a `<workflow>.integrations.json` manifest. Owns the whole flow: run the importer, triage what it could not map, fill each stub, report any missing `@pikku/addon-*` integrations, and verify the result compiles and runs with no surviving stubs. DO NOT TRIGGER for hand-written addon wiring unrelated to an n8n import (use pikku-addon), or for authoring workflows from scratch (use pikku-workflow).'
+installGroups: [core]
 metadata:
   version: 1.0.0
 ---
@@ -19,14 +20,14 @@ missing dependency).
 
 ## Agent Operating Procedure
 
-1. Discover before editing. Prefer `pikku-meta`/`pikku meta ... --json` when
+1. Discover before editing. Prefer `pikku meta ... --json` when
    available; inspect only the focused output you need.
 2. Identify the source file that owns the behavior. Do not start from generated
    output, `.pikku`, `node_modules`, or vendored packages.
 3. Make the smallest source change that satisfies the task. Keep generated files
    generated.
-4. Validate with the narrowest relevant command first, then `pikku all` /
-   `pikku-verify` when functions, wirings, or schemas changed.
+4. Validate with the narrowest relevant command first, then `pikku all` when
+   functions, wirings, or schemas changed.
 5. If validation fails, fix the source cause and rerun. Never edit generated
    files to hide an error.
 

package/skills/pikku-react/references/client.md

@@ -1,6 +1,18 @@
 # Pikku React
 
 
+What is here:
+
+- [What ships](#what-ships)
+- [Resolving the server URL](#resolving-the-server-url)
+- [Setup at the app root](#setup-at-the-app-root)
+- [Calling an RPC directly (no React Query)](#calling-an-rpc-directly-no-react-query)
+- [Calling fetch directly](#calling-fetch-directly)
+- [Realtime subscriptions](#realtime-subscriptions)
+- [When to reach for what](#when-to-reach-for-what)
+- [Authentication](#authentication)
+- [What NOT to do](#what-not-to-do)
+
 ## What ships
 
 ```tsx

package/skills/pikku-realtime/SKILL.md

@@ -3,17 +3,17 @@ name: pikku-realtime
 description: >-
   Use when making ANY view live/realtime in a Pikku app — a board, shared list, dashboard, ticker, bidding room, live count — or when adding two-way chat/presence. Covers the DEFAULT event-hub SSE path and the two-way WebSocket channel.
   TRIGGER when: the user wants live updates, realtime, "update without refresh", a live board/feed/ticker/room, presence, or chat; or when data that MORE THAN ONE signed-in user can change should reflect others
-  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (that is pikku-schedule/pikku-workflow).
+  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (see `pikku-wiring`'s scheduler and queue references, or `pikku-workflow`).
 installGroups: [core, client]
 ---
 
 # Pikku Realtime (SSE + WebSocket channels)
 
-There is NOTHING to hand-roll and NOTHING to "find". The event-hub SSE transport
-is already wired into every app, and the two patterns below ARE the realtime
-templates. Start from them and rename — never grep the project for existing
-`sse`/`eventHub` code to copy, never write a custom `EventSource`, and never
-write a bespoke `sse: true` route for a plain live feed.
+There is NOTHING to hand-roll and NOTHING to "find". `pikku enable events` wires
+the event-hub SSE transport and generates the typed client, and the two patterns
+below ARE the realtime templates. Start from them and rename — never grep the
+project for existing `sse`/`eventHub` code to copy, never write a custom
+`EventSource`, and never write a bespoke `sse: true` route for a plain live feed.
 
 ## Pick the transport (almost always SSE)
 

package/skills/pikku-report/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: pikku-report
+description: >-
+  Use when pikku itself cost you time — wrong generated types, a check that passes when it
+  should not, output that is quietly wrong, a skill that misled you — or when the user asks you
+  to report a framework bug, file a finding, or look at what is queued. Owns `pikku fabric
+  report` (a finding is about pikku, not the app), the product-vs-harness kinds, the
+  workaround-first ladder, and the local findings spool. TRIGGER when: the framework fought you,
+  codegen produced something broken, a skill told you to run something that does not exist, the
+  user says "report this to pikku" / "file a finding" / "check the findings queue", or a finding
+  was queued and never sent. DO NOT TRIGGER when: the bug is in the app you are building (fix it
+  there), or you are tempted to patch pikku's source (never do that from an app).
+installGroups: [core]
+---
+
+# Report a finding to Fabric
+
+A finding is about **pikku**, not about the app you are building. It is how the
+framework learns what cost its users time — the bug, the misleading skill, the
+silence where a check should have complained.
+
+Nothing is written to the repository. The terminal receipt shows exactly what
+left your machine, and the command is spelled `pikku fabric report` — there is
+no top-level report command.
+
+## Report at the moment it happens
+
+Not at the end from memory: a run that falls over never reaches its end, and the
+mechanism is already loaded while you are in it. One finding per thing that
+fought you.
+
+The ladder decides how much to spend:
+
+1. **Find the quicker workaround.** The user is paying for their feature, not
+   for pikku's health.
+2. **Investigate** only when there is no workaround, or when the user asks why
+   something is slow or wrong.
+3. **Report at the depth you already reached.** Never spend extra effort to
+   file; never throw away effort you already spent. If the investigation took
+   you to the mechanism, the finding says so — named file, named function, what
+   is actually happening, and what pikku should do instead.
+
+## What counts
+
+Anything that cost you time and would cost the next person the same. Most of
+these never produce an error: output that is quietly wrong, a generated type
+that disagrees with the runtime, a check that passes when it should not, a
+narrowing you had to write by hand because the framework should have written
+it. **Having to write code the framework should have written for you is a
+finding.**
+
+Also anything that only shows up in one place — invisible locally, fatal
+deployed, or the reverse. Say which with `--surface local|deployed|both`.
+
+Not a finding: a preference, a thing you would have designed differently, or
+baseline noise that was already failing before you started.
+
+## Two kinds
+
+- `--kind product` — pikku behaved wrongly. Fixing it is a change to the
+  framework.
+- `--kind harness` — a skill misled you: it told you to run something that does
+  not exist, described a flag that is spelled differently, or contradicted what
+  the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
+  section>"`. This is the most useful kind to file, because it is fixable
+  immediately — so file it even when the cost was small.
+
+## The command
+
+Send it as JSON on stdin. Most of a finding is prose, and prose carries
+apostrophes, quotes, backticks and newlines — each one a shell metacharacter
+before it is a character in your sentence. A stack trace passed to `--error`
+breaks the command at its first newline; a backtick in `--actual` runs whatever
+follows it. Quote the heredoc delimiter (`<<'EOF'`, never `<<EOF`) so the shell
+leaves the body alone.
+
+```bash
+pikku fabric report --stdin <<'EOF'
+{
+  "title": "<one-line title>",
+  "kind": "product",
+  "model": "<the model you are>",
+  "expected": "<what you expected pikku to do>",
+  "actual": "<what it did instead>",
+  "command": "<the command you ran>",
+  "workaround": "<what you did instead, inside the app>"
+}
+EOF
+```
+
+The same fields exist as flags for a finding short enough to type; `pikku fabric
+report --help` lists them. Whichever path you use, the rules below are checked
+before anything is sent:
+
+- `kind` is `product` or `harness`, and a `harness` finding names the skill that
+  misled you.
+- A resolved finding carries the `workaround` you used (or a `proposal`).
+- `--unresolved` means **no workaround was found** — it requires `--tried` with
+  what you attempted and how each attempt failed, and it forbids `--workaround`.
+  It does not mean the workaround was unpleasant.
+
+Add whichever of these you actually have: `error` (the error's message line,
+verbatim), `repro` (the shortest way to reach it again), `proposal`, `area`,
+`surface`, `cost` (measured if you measured it — "98s vs 20s steady" ranks;
+"slow" does not), `run` (an id shared by every finding from this build),
+`deployTarget`.
+
+Versions, platform and package manager are read off the installed tree for you.
+Do not pass them and do not ask the user for them.
+
+## When it cannot send
+
+Reporting never fails a build. A finding that cannot be sent — logged out, or
+fabric unreachable — is held on the machine and goes out with the next report
+that succeeds, so nothing you file is lost:
+
+- `pikku fabric findings list` shows what is queued.
+- `pikku fabric findings flush` sends everything queued.
+- `pikku fabric findings clear` discards it.
+
+If the terminal says the finding was queued, carry on with what you were doing.
+Do not try to fix the send, and do not file the same thing again.
+
+## Never fix pikku itself
+
+Not a patch in `node_modules`, not a linked checkout, not a branch in the
+framework repo. Many agents each patching pikku to unblock themselves is many
+divergent copies and a merge problem nobody signed up for. Work around it in the
+app, report it, and let the fix happen once.
+
+## What NOT to do
+
+- **Do not report a bug in the app as a pikku finding.** If the app's own code
+  is wrong, fix it; a finding that turns out to be the caller's mistake costs
+  the maintainers more than it cost you.
+- **Do not batch findings at the end of a build.** You will have lost the
+  mechanism and the command, and the report wins nothing.
+- **Do not file without a workaround or an `--unresolved --tried`.** A finding
+  that cannot be acted on is noise.
+- **Do not paste a secret, token or customer data into a finding.** The payload
+  leaves your machine; keep it to the mechanism.
+- **Do not ask the user for versions or platform.** They are collected
+  automatically.