@pikku/skills 0.12.14 → 0.12.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.14",
+  "version": "0.12.15",
   "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,6 +6,7 @@ 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: [fabric]
 ---
 
 # Pikku AI Vercel (Agent Runner)

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

@@ -10,6 +10,7 @@ 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: [fabric]
 ---
 
 # Pikku Better Auth Integration

package/skills/pikku-cli/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   options, parameters, custom renderers, and nested command groups. TRIGGER when: code uses
   wireCLI/pikkuCLICommand, user asks about CLI commands, terminal tools, command-line interface,
   or adding subcommands. DO NOT TRIGGER when: user asks about the pikku CLI tool itself (use
-  pikku-info) or HTTP endpoints (use pikku-http).
+  pikku-meta) or HTTP endpoints (use pikku-http).
 installGroups: [core]
 ---
 

package/skills/pikku-emails/SKILL.md

@@ -10,6 +10,7 @@ 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: [fabric]
 ---
 
 # Pikku Emails

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: [client]
+installGroups: [client, fabric]
 ---
 
 # Pikku i18n (Paraglide JS)

package/skills/pikku-jose/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   code uses JoseJWTService, user asks about JWT setup, token signing, token verification, or
   @pikku/jose. DO NOT TRIGGER when: user asks about session middleware (use pikku-security) or
   general service setup (use pikku-services).
+installGroups: [fabric]
 ---
 
 # Pikku Jose (JWT Service)

package/skills/pikku-kysely/SKILL.md

@@ -11,6 +11,7 @@ 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: [fabric]
 ---
 
 # Pikku Kysely (SQL Database Services)

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

@@ -9,6 +9,7 @@ description: >-
   credentials, sandbox/worker tokens, or resolving a better-auth session in a Pikku function. DO
   NOT TRIGGER when: user asks about end-user HTTP session/cookie auth only (use pikku-http + the
   app betterAuth config) or about WebSocket channel mechanics (use pikku-websocket).
+installGroups: [fabric]
 ---
 
 # Pikku Machine Auth

package/skills/pikku-meta/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: pikku-meta
+description: >-
+  Read and change a Pikku project's declarations without grepping or hand-editing — functions
+  (with their transport, middleware and permissions), schemas, workflows, wires, tags, middleware
+  and permission definitions, plus `pikku meta apply` to set config on them. TRIGGER when: user
+  asks "what functions exist?", "show me the project structure", "list routes/middleware/
+  permissions", needs a function's input/output shape, or wants to add a permission, retag a
+  function, or change a declaration's config. DO NOT TRIGGER when: user is writing a NEW function
+  or wiring (use the specific wiring skill) or asking about Pikku concepts (use pikku-concepts).
+installGroups: [core]
+allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku info *)
+argument-hint: '[context|functions|schemas|workflows|middleware|permissions|wires|apply]'
+---
+
+# Pikku Project Metadata
+
+`pikku meta` is the machine-readable view of the project and the write path to it.
+`pikku info` is the same ground as human-readable tables. Prefer `meta` when you are
+going to act on the output; prefer `info` when a person is going to read it.
+
+## 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. Change a declaration's config with `pikku meta apply`, not by hand-editing the file.
+4. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
+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.
+
+## Reading
+
+| Command                         | What it answers                                                                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `pikku meta context`            | Everything a planner needs in one call — functions, wires, middleware, permissions, workflows, capabilities, layout. Start here. |
+| `pikku meta functions get <id>` | One function's input/output schema names, source file, tags, expose/readonly                                                     |
+| `pikku meta schemas get <name>` | One generated JSON schema                                                                                                        |
+| `pikku meta workflows get <id>` | One workflow's steps                                                                                                             |
+| `pikku meta permissions list`   | What permissions exist and where they are defined                                                                                |
+| `pikku meta middleware list`    | What middleware exists                                                                                                           |
+| `pikku meta wires list`         | Wires by transport (http, channel, scheduler, queue, trigger)                                                                    |
+| `pikku meta clients`            | Exposed RPCs/workflows/channels with their type names — what a frontend can call                                                 |
+
+`list` is the default for each group, so `pikku meta functions` and `pikku meta functions list`
+are the same call.
+
+A function's input/output shape comes from here. Do not infer it by reading the
+function body, and do not cast a call site to make it compile — the schema is the type.
+
+## Changing
+
+`pikku meta apply` applies a batch of edits to your own source. Pass JSON as a file
+or on stdin:
+
+```bash
+pikku meta apply ops.json
+```
+
+```json
+{
+  "operations": [
+    {
+      "kind": "functionConfig",
+      "sourceFile": "src/functions/todos.functions.ts",
+      "exportedName": "listTodos",
+      "changes": { "title": "List Todos", "tags": ["todos", "read"] }
+    },
+
+    {
+      "kind": "functionConfig",
+      "sourceFile": "src/functions/todos.functions.ts",
+      "exportedName": "listTodos",
+      "changes": {
+        "permissions": {
+          "functionLevel": {
+            "name": "isTodoOwner",
+            "from": "../permissions.js"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+Three kinds: `functionConfig`, `agentConfig`, `functionBody`. Every operation names
+a `sourceFile` and the `exportedName` declared in it.
+
+`functionConfig` changes: `title`, `description`, `summary`, `tags`, `errors`,
+`expose`, `remote`, `mcp`, `readonly`, `approvalRequired`, `permissions`.
+`agentConfig` changes: `name`, `description`, `instructions`, `role`, `personality`,
+`goal`, `model`, `maxSteps`, `temperature`, `toolChoice`, `tools`, `tags`.
+
+`null` removes a property. Edits are spliced into the original text, so formatting,
+comments and JSDoc survive.
+
+`permissions` and `tools` are written as identifiers rather than literals, so each
+one carries the module it comes from (`{"name": "isTodoOwner", "from": "../permissions.js"}`)
+and the missing import is added for you — widening an existing import from that
+module rather than adding a second one.
+
+### Why batch
+
+The whole batch either lands or it does not: every operation is resolved before
+anything is written, so a failure leaves every file untouched and names the
+operation that caused it. Batching is also what makes one codegen pass correct —
+**run `pikku all` once after the batch**, not once per property. The response tells
+you whether it is needed:
+
+```json
+{
+  "schemaVersion": "meta-apply.v1",
+  "applied": 2,
+  "files": ["src/functions/todos.functions.ts"],
+  "generatedMetaIsStale": true
+}
+```
+
+## Human-readable tables (`pikku info`)
+
+Four subcommands only — `functions`, `tags`, `middleware`, `permissions`. Routes,
+channels, schedulers and queues are not subcommands; they are the _transport_ column
+of `info functions --verbose`.
+
+```bash
+yarn pikku info functions --verbose --silent
+yarn pikku info tags --silent
+yarn pikku info middleware --verbose --silent
+yarn pikku info permissions --verbose --silent
+```
+
+`--silent` suppresses the banner and inspector diagnostics. It works, but it is not
+declared as an option, so every run also prints `Warning: Unknown option: --silent
+(ignored)` — the warning is wrong. Ignore that one line.
+
+`--limit N` caps rows (default 50); the footer says how many were withheld.
+On `tags`, `--verbose` swaps counts for names; elsewhere it adds columns.

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

@@ -3,6 +3,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).'
 metadata:
   version: 1.0.0
+installGroups: [fabric]
 ---
 
 # n8n → Pikku Import

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: [client]
+installGroups: [client, fabric]
 ---
 
 # Pikku React Query Hooks

package/skills/pikku-rpc/SKILL.md

@@ -6,6 +6,7 @@ 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: [fabric]
 ---
 
 # Pikku RPC Wiring

package/skills/pikku-ws/SKILL.md

@@ -5,6 +5,7 @@ description: >-
   adapter for Pikku channels. TRIGGER when: code uses @pikku/ws, user asks about ws library
   WebSocket server, or Node.js WebSocket runtime. DO NOT TRIGGER when: user asks about WebSocket
   wiring/channels (use pikku-websocket) or uWebSockets (use pikku-deploy-uws).
+installGroups: [fabric]
 ---
 
 # Pikku WS (WebSocket Server Runtime)

package/skills/pikku-info/SKILL.md

@@ -1,109 +0,0 @@
----
-name: pikku-info
-description: >-
-  Discover what exists in a Pikku project — functions (with their transport, middleware and
-  permissions), tags, middleware and permission definitions. Use when you need to understand the
-  project structure, find existing functions, or check what middleware and permissions are
-  defined. TRIGGER when: user asks "what functions exist?", "show me the project structure", "list
-  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).
-allowed-tools: Bash(yarn pikku info *)
-argument-hint: '[functions|tags|middleware|permissions] [--verbose] [--limit N]'
----
-
-# Pikku Project Discovery
-
-## 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.
-
-Use the `pikku info` CLI commands to inspect this Pikku project. Run the commands below and present the results to the user in a clear summary.
-
-There are exactly four subcommands — `functions`, `tags`, `middleware`,
-`permissions`. Routes, channels, schedulers and queues are not separate
-subcommands; they show up as the _transport_ column of `info functions --verbose`.
-
-## Available Commands
-
-`--silent` suppresses the banner and the inspector's diagnostics, which is what
-you want when parsing the table. It is read by the CLI but not declared as an
-option, so every run also prints `Warning: Unknown option: --silent (ignored)` —
-the warning is wrong, the flag works. Ignore that one line.
-
-For anything you intend to parse rather than read, prefer `--json` (alias
-`-j`, or `--output json`), which emits NDJSON instead of a formatted table.
-
-### Functions
-
-List all registered pikku functions:
-
-```bash
-yarn pikku info functions --silent
-```
-
-For full details including transport type (http/channel/scheduler/queue/workflow/mcp/cli/trigger), middleware, permissions, and source file:
-
-```bash
-yarn pikku info functions --verbose --silent
-```
-
-### Tags
-
-List all tags with counts of associated functions and middleware:
-
-```bash
-yarn pikku info tags --silent
-```
-
-For full names instead of counts:
-
-```bash
-yarn pikku info tags --verbose --silent
-```
-
-### Middleware
-
-List all middleware definitions:
-
-```bash
-yarn pikku info middleware --silent
-```
-
-For full details including source file, required services, and description:
-
-```bash
-yarn pikku info middleware --verbose --silent
-```
-
-### Permissions
-
-List all permission definitions:
-
-```bash
-yarn pikku info permissions --silent
-```
-
-For full details including source file, required services, and description:
-
-```bash
-yarn pikku info permissions --verbose --silent
-```
-
-## Instructions
-
-1. If the user specifies a subcommand (e.g., `/pikku-info functions`), run only that command.
-2. If no subcommand is specified, run all four commands to give a complete project overview.
-3. Always use `--silent` to suppress the Pikku banner and inspector logs, and disregard the spurious "Unknown option" warning it prints.
-4. Use `--verbose` when the user asks for details, file paths, or "more info". On `tags` it swaps counts for names; elsewhere it adds columns.
-5. Use `--limit N` to control output size (default is 50 rows) — the footer tells you how many were withheld.
-6. After running the commands, summarize the findings concisely:
-   - Total count of functions, tags, middleware, and permissions
-   - Notable patterns (e.g., which transport types are in use, which tags group the most functions)
-   - Any functions without tags or transport types (potential issues)