@pikku/cli 0.12.82 → 0.12.83

package/skills/pikku-software-archaeology/references/pikku-mapping.md

@@ -0,0 +1,49 @@
+# How Pikku Consumes a Product Blueprint
+
+The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pikku primitive. A generator (or an agent following `pikku-feature`) walks the JSON files in this order:
+
+| Blueprint source | Pikku target |
+|---|---|
+| `entities.json` attributes + relationships + constraints | Kysely migrations + generated `DB` types; Zod schemas per entity |
+| `entities.json` states/transitions | a `status` column + transition guards inside the owning commands (or a state-machine helper) |
+| `commands.json` | `pikkuFunc` / `pikkuSessionlessFunc` with `input:` Zod schema built from `input[]`; `preconditions` become guard clauses; name is the camelCased command name (`SendInvoice` → `sendInvoice`) |
+| `queries.json` | `pikkuFunc` reads; `scoping` becomes the mandatory `WHERE` / session filter |
+| `events.json` | EventHub topics (realtime) or queue messages; `consumedBy` become `wireQueueWorker` handlers — implicit events (`explicit: false`) get promoted to real emissions |
+| `policies.json` (authorization) | Pikku `permissions` / middleware; one policy = one named permission function, wired everywhere `enforcedAt` listed — this collapses duplicated legacy checks into a single definition |
+| `policies.json` (validation) | Zod schema refinements on the command's `input` |
+| `workflows.json` kind=user | frontend flows + the commands they chain |
+| `workflows.json` kind=system, with `schedule` | `wireScheduler` entries |
+| `workflows.json` multi-step / checkpointing | `pikkuWorkflowFunc` with one `workflow.do(...)` step per blueprint step |
+| `workflows.json` `scenarios[]` | **`pikkuUserFlow` stories — this is the canonical target.** Each scenario's given/when/outcome maps 1:1 onto a user-flow step sequence; group scenarios by their workflow into one flow per journey. Only scenarios with no user-facing surface (pure system workflows: cron sweeps, webhook ingest) fall back to API/e2e tests |
+| `api.json` | `wireHTTP` routes: keep `path`+`method` for compatibility, point at the mapped command/query func; `auth: none`/capability-URL surfaces get `auth: false` |
+| `api.json` kind=webhook-in | `wireHTTP` with `auth: false` + signature-verification middleware from the integration |
+| `integrations.json` | services in `services.ts` (constructor-injected classes); `configVia` env vars become `wireSecret` / config; per-user credentials become `wireCredential` |
+| `architecture.json` notes | deployment config (ports, raw-body routes, proxy expectations) |
+| `invariants.json` enforcedBy=db-constraint | migration constraints (UNIQUE, CHECK, FK) |
+| `invariants.json` enforcedBy=code-guard/nothing | guard clauses + a test each; `atRiskBecause` entries get a hardening task |
+| `gaps.json` | excluded from generation; `open-product-decision` + `migration.json.decisionsNeeded` go to a human BEFORE generation starts |
+| `migration.json.mappings` | the work plan: one mapping = one migration slice |
+| `interfaces.json` kind=cli | `wireCLI` entrypoints — the CLI commands are the same funcs the routes expose |
+| `interfaces.json` kind=mcp | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates) |
+| `interfaces.json` kind=openapi-rest / sdk | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen |
+| `interfaces.json` kind=websocket-realtime | `pikku-realtime` EventHub topics / channels |
+| `frontend.json` | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react-query` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto |
+| `frontend-routes.json` | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views |
+| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk |
+| `frontend-components.json` rebuild=`custom-logic` | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items |
+| `frontend-components.json` rebuild=`custom-style` | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported |
+
+## Order of generation
+
+1. Human resolves `decisionsNeeded`.
+2. Entities → migrations + types.
+3. Policies → permission functions (before commands, so commands can reference them).
+4. Commands + queries → funcs; api.json → wirings.
+5. Events → topics/queues; system workflows → schedulers/workers/workflows.
+6. Scenarios → tests. Run them against the new implementation; they encode the legacy behavior worth preserving.
+
+## Uncertainty handling
+
+- `confidence: high` concepts generate directly.
+- `confidence: medium` concepts generate, but are listed for review in the pre-generation report — id, evidence summary, and what is uncertain — rather than carrying a marker comment in the generated code. The report is the review surface; the generated code stays clean.
+- `confidence: low` concepts are NOT generated automatically — they surface in the pre-generation review along with `decisionsNeeded`.

package/skills/pikku-software-archaeology/scripts/validate.mjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Validates a .knowledge/ blueprint directory against references/blueprint.schema.json,
+// then runs cross-file referential checks (does every command's domain exist, does every
+// api surface map to a real command/query, ...). Exit 0 = valid, 1 = errors.
+//
+// Usage: node validate.mjs <path-to-.knowledge-dir>
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const schemaDoc = JSON.parse(readFileSync(join(here, '..', 'references', 'blueprint.schema.json'), 'utf8'));
+
+const dir = process.argv[2];
+if (!dir) { console.error('usage: node validate.mjs <.knowledge dir>'); process.exit(2); }
+
+const errors = [];
+const warnings = [];
+
+// --- minimal JSON-Schema-subset validator (type, required, properties, items, enum, minItems, pattern, $ref -> $defs) ---
+function resolveRef(ref) {
+  const m = /^#\/\$defs\/(\w+)$/.exec(ref);
+  if (!m || !schemaDoc.$defs[m[1]]) throw new Error(`unresolvable $ref ${ref}`);
+  return schemaDoc.$defs[m[1]];
+}
+
+function check(value, schema, path) {
+  if (schema.$ref) schema = { ...resolveRef(schema.$ref), ...schema, $ref: undefined };
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${path}: expected one of [${schema.enum.join(', ')}], got ${JSON.stringify(value)}`);
+    return;
+  }
+  const t = schema.type;
+  if (t === 'object') {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      errors.push(`${path}: expected object`); return;
+    }
+    for (const req of schema.required || []) {
+      if (!(req in value)) errors.push(`${path}: missing required field "${req}"`);
+    }
+    for (const [k, v] of Object.entries(value)) {
+      if (schema.properties?.[k]) check(v, schema.properties[k], `${path}.${k}`);
+    }
+  } else if (t === 'array') {
+    if (!Array.isArray(value)) { errors.push(`${path}: expected array`); return; }
+    if (schema.minItems && value.length < schema.minItems) {
+      errors.push(`${path}: needs at least ${schema.minItems} item(s), has ${value.length}`);
+    }
+    if (schema.items) value.forEach((v, i) => check(v, schema.items, `${path}[${i}]`));
+  } else if (t === 'string') {
+    if (typeof value !== 'string') { errors.push(`${path}: expected string`); return; }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${path}: "${value}" does not match ${schema.pattern}`);
+    }
+  } else if (t === 'boolean' && typeof value !== 'boolean') {
+    errors.push(`${path}: expected boolean`);
+  } else if (t === 'number' && typeof value !== 'number') {
+    errors.push(`${path}: expected number`);
+  }
+}
+
+// --- load + per-file validation ---
+// Files marked `x-optional` (the frontend layer) only validate when present, so a
+// backend-only repo does not fail for lacking them.
+const docs = {};
+for (const [filename, fileSchema] of Object.entries(schemaDoc.files)) {
+  const p = join(dir, filename);
+  if (!existsSync(p)) {
+    if (!fileSchema['x-optional']) errors.push(`${filename}: missing`);
+    continue;
+  }
+  try {
+    docs[filename] = JSON.parse(readFileSync(p, 'utf8'));
+  } catch (e) {
+    errors.push(`${filename}: invalid JSON (${e.message})`); continue;
+  }
+  check(docs[filename], fileSchema, filename);
+}
+if (!existsSync(join(dir, 'blueprint.md'))) errors.push('blueprint.md: missing');
+
+// --- cross-file referential checks ---
+if (docs['domains.json'] && docs['commands.json']) {
+  const domains = new Set((docs['domains.json'].domains || []).map((d) => d.name));
+  const commandNames = new Set((docs['commands.json'].commands || []).map((c) => c.name));
+  const queryNames = new Set((docs['queries.json']?.queries || []).map((q) => q.name));
+  const eventNames = new Set((docs['events.json']?.events || []).map((e) => e.name));
+
+  const wantDomain = (owner, d) => {
+    if (d && !domains.has(d)) errors.push(`${owner}: domain "${d}" not defined in domains.json`);
+  };
+  for (const c of docs['commands.json'].commands || []) {
+    wantDomain(`commands.json:${c.name}`, c.domain);
+    for (const ev of c.eventsProduced || []) {
+      if (!eventNames.has(ev)) warnings.push(`commands.json:${c.name} produces "${ev}" which is not in events.json`);
+    }
+  }
+  for (const q of docs['queries.json']?.queries || []) wantDomain(`queries.json:${q.name}`, q.domain);
+  for (const e of docs['entities.json']?.entities || []) wantDomain(`entities.json:${e.name}`, e.domain);
+  for (const ev of docs['events.json']?.events || []) wantDomain(`events.json:${ev.name}`, ev.domain);
+
+  for (const s of docs['api.json']?.surfaces || []) {
+    const { type, name } = s.mapsTo || {};
+    if (type === 'command' && !commandNames.has(name)) errors.push(`api.json:${s.method || ''} ${s.path}: maps to unknown command "${name}"`);
+    if (type === 'query' && !queryNames.has(name)) errors.push(`api.json:${s.method || ''} ${s.path}: maps to unknown query "${name}"`);
+    if (type === 'event-ingress' && !eventNames.has(name)) errors.push(`api.json:${s.method || ''} ${s.path}: event-ingress maps to unknown event "${name}" (state-changing webhooks should map to a command instead)`);
+  }
+  // every domain's listed concepts should exist
+  for (const d of docs['domains.json'].domains || []) {
+    for (const c of d.commands || []) if (!commandNames.has(c)) warnings.push(`domains.json:${d.name}: lists command "${c}" not in commands.json`);
+    for (const q of d.queries || []) if (!queryNames.has(q)) warnings.push(`domains.json:${d.name}: lists query "${q}" not in queries.json`);
+    for (const e of d.events || []) if (!eventNames.has(e)) warnings.push(`domains.json:${d.name}: lists event "${e}" not in events.json`);
+    const policyNames = new Set((docs['policies.json']?.policies || []).map((p) => p.name));
+    for (const p of d.policies || []) if (!policyNames.has(p)) warnings.push(`domains.json:${d.name}: lists policy "${p}" not in policies.json`);
+  }
+  // commands with no policies and no preconditions are suspicious for mutating ops
+  for (const c of docs['commands.json'].commands || []) {
+    if (!(c.policies || []).length && !(c.preconditions || []).length) {
+      warnings.push(`commands.json:${c.name}: no policies or preconditions — really unguarded, or missed extraction?`);
+    }
+  }
+}
+
+// --- frontend layer cross-checks (only when the optional frontend files exist) ---
+if (docs['frontend-components.json']) {
+  const componentNames = new Set(
+    (docs['frontend-components.json'].components || []).map((c) => c.name),
+  );
+  // routes should reference components that were actually inventoried
+  for (const r of docs['frontend-routes.json']?.routes || []) {
+    for (const c of r.usesComponents || []) {
+      if (!componentNames.has(c)) {
+        warnings.push(`frontend-routes.json:${r.path}: uses component "${c}" not in frontend-components.json`);
+      }
+    }
+  }
+  // a component flagged as needing a port must say WHY (the custom logic), or the
+  // port-risk is unactionable
+  for (const c of docs['frontend-components.json'].components || []) {
+    if (c.rebuild === 'custom-logic' && !c.customLogic) {
+      warnings.push(`frontend-components.json:${c.name}: rebuild=custom-logic but no customLogic description — port risk is unactionable`);
+    }
+  }
+  // data-fetching queries named on routes should resolve to a real query/command
+  if (docs['queries.json'] || docs['commands.json']) {
+    const known = new Set([
+      ...(docs['queries.json']?.queries || []).map((q) => q.name),
+      ...(docs['commands.json']?.commands || []).map((c) => c.name),
+    ]);
+    for (const r of docs['frontend-routes.json']?.routes || []) {
+      for (const d of r.dataFrom || []) {
+        if (!known.has(d)) {
+          warnings.push(`frontend-routes.json:${r.path}: reads "${d}" which is not a known query/command`);
+        }
+      }
+    }
+  }
+}
+
+// an inconsistent UI with no specific design findings = under-extraction
+// (guarded on frontend.json alone — independent of the component inventory)
+if (docs['frontend.json']) {
+  const consistency = docs['frontend.json'].designSystemConsistency;
+  const findingCount = (docs['frontend.json'].designFindings || []).length;
+  if ((consistency === 'mixed' || consistency === 'ad-hoc') && findingCount === 0) {
+    warnings.push(`frontend.json: designSystemConsistency="${consistency}" but designFindings is empty — name the specific broken patterns (interaction/theming/cross-page/…)`);
+  }
+}
+
+for (const w of warnings) console.log(`WARN  ${w}`);
+for (const e of errors) console.log(`ERROR ${e}`);
+console.log(`\n${errors.length} error(s), ${warnings.length} warning(s) across ${Object.keys(docs).length} files`);
+process.exit(errors.length ? 1 : 0);

package/skills/pikku-template-clone/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-template-clone
-description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `pikku create`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
+description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `npm create pikku`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
 allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
 ---
 

package/skills/pikku-trigger/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-trigger
-description: 'Use when adding event-driven functions that respond to system events like Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or custom event sources. Covers wireTrigger, wireTriggerSource, and pikkuTriggerFunc.
-TRIGGER when: code uses wireTrigger/wireTriggerSource/pikkuTriggerFunc, user asks about event-driven functions, Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or reacting to external events.
-DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-cron) or background job queues (use pikku-queue).'
+description: >-
+  Use when adding event-driven functions that respond to system events like Redis pub/sub,
+  PostgreSQL LISTEN/NOTIFY, or custom event sources. Covers wireTrigger, wireTriggerSource, and
+  pikkuTriggerFunc. TRIGGER when: code uses wireTrigger/wireTriggerSource/pikkuTriggerFunc, user
+  asks about event-driven functions, Redis pub/sub, PostgreSQL LISTEN/NOTIFY, or reacting to
+  external events. DO NOT TRIGGER when: user asks about scheduled tasks (use pikku-cron) or
+  background job queues (use pikku-queue).
 installGroups: [core]
 ---
 

package/skills/pikku-versioning/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-versioning
-description: 'Use when versioning Pikku function contracts, detecting breaking changes, or managing API backward compatibility. Covers the version property, versions.pikku.json manifest, contract hashing, and CI integration.
-TRIGGER when: code uses version: on a pikkuFunc, user asks about API versioning, breaking changes, contract hashes, backward compatibility, or "pikku versions" CLI commands.
-DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config) or general function definitions (use pikku-concepts).'
+description: >-
+  Use when versioning Pikku function contracts, detecting breaking changes, or managing API
+  backward compatibility. Covers the version property, versions.pikku.json manifest, contract
+  hashing, and CI integration. TRIGGER when: code uses version: on a pikkuFunc, user asks about
+  API versioning, breaking changes, contract hashes, backward compatibility, or "pikku versions"
+  CLI commands. DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config)
+  or general function definitions (use pikku-concepts).
 installGroups: [core]
 ---
 

package/skills/pikku-websocket/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-websocket
-description: 'Use when adding real-time features, WebSocket channels, live updates, chat, or pub/sub to a Pikku app. Covers wireChannel, action routing, auth, EventHub pub/sub, channel middleware, and generated WebSocket client.
-TRIGGER when: code uses wireChannel, user asks about WebSocket, real-time, live updates, chat, pub/sub, or the generated WebSocket client.
-DO NOT TRIGGER when: user asks about HTTP/REST (use pikku-http), SSE (use pikku-http with sse: true), or WebSocket deployment specifics (use pikku-deploy-uws).'
+description: >-
+  Use when adding real-time features, WebSocket channels, live updates, chat, or pub/sub to a
+  Pikku app. Covers wireChannel, action routing, auth, EventHub pub/sub, channel middleware, and
+  generated WebSocket client. TRIGGER when: code uses wireChannel, user asks about WebSocket,
+  real-time, live updates, chat, pub/sub, or the generated WebSocket client. DO NOT TRIGGER when:
+  user asks about HTTP/REST (use pikku-http), SSE (use pikku-http with sse: true), or WebSocket
+  deployment specifics (use pikku-deploy-uws).
 ---
 
 # Pikku WebSocket Wiring
@@ -172,7 +176,7 @@ wireChannel({
 
 ### Generated WebSocket Client
 
-After `npx pikku prebuild`:
+After `npx pikku all`:
 
 ```typescript
 import { PikkuWebSocket } from '.pikku/pikku-websocket.gen.js'

package/skills/pikku-workflow/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: pikku-workflow
-description: 'Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku. Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
-TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows, multi-step processes, durable execution, suspend/resume, or DAG orchestration.
-DO NOT TRIGGER when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use pikku-cron).'
+description: >-
+  Use when building multi-step workflows, state machines, or orchestration pipelines with Pikku.
+  Covers pikkuWorkflowFunc, workflow steps (do, sleep, suspend), graph workflows, and HTTP wiring.
+  TRIGGER when: code uses pikkuWorkflowFunc/pikkuWorkflowGraph, user asks about workflows,
+  multi-step processes, durable execution, suspend/resume, or DAG orchestration. DO NOT TRIGGER
+  when: user asks about simple background jobs (use pikku-queue) or scheduled tasks (use
+  pikku-cron).
 installGroups: [core]
 ---
 

package/skills/pikku-ws/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: pikku-ws
-description: 'Use when setting up a WebSocket server with the ws library in a Pikku app. Covers the ws runtime 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).'
+description: >-
+  Use when setting up a WebSocket server with the ws library in a Pikku app. Covers the ws runtime
+  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).
 ---
 
 # Pikku WS (WebSocket Server Runtime)

package/skills/pikku-n8n-addon-map/SKILL.md

@@ -1,178 +0,0 @@
----
-name: pikku-n8n-addon-map
-description: 'Use when mapping n8n integration stubs (gmailTool, slackTool, googleSheetsTool, plain gmail/slack action nodes, etc.) emitted by @pikku/n8n-import to real `@pikku/addon-*` functions. Triggered when the user points at a `<workflow>.integrations.json` manifest produced by `pikku-n8n-import`, says ''map the n8n integrations'', ''wire up the gmail/slack stubs'', ''replace these stubs with addon refs'', or opens a stub file generated from an n8n integration node (the stub''s JSDoc says `STUB — generated from n8n node "..." (type "n8n-nodes-base.<service>...")`). For n8n **Code** node stubs use `pikku-n8n-code-translate` instead. DO NOT TRIGGER when: the stub is an n8n Code node (use pikku-n8n-code-translate), or no n8n-generated stub/manifest is involved (use pikku-addon for hand-written addon wiring).'
-metadata:
-  version: 1.0.0
----
-
-# n8n Integration Stub → Pikku Addon Mapper
-
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise 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.
-
-You are translating n8n integration nodes (`gmailTool`, `slackTool`, `googleSheetsTool`, plain `gmail` / `slack` action nodes, etc.) that `@pikku/n8n-import` left as throwing stubs into real `ref('<addonRpc>')` references that point at functions in installed `@pikku/addon-*` packages.
-
-This skill is **per-stub mechanical**. You do not invent business logic, you do not chain calls, you do not "improve" the workflow. You read one entry from a manifest, find the matching addon function, and rewrite the stub.
-
-## Inputs
-
-1. **Manifest file** — `<workflow>.integrations.json` next to the workflow `.graph.ts`. Each entry:
-   ```jsonc
-   {
-     "rpcName": "agentGmailtool__sendAMessageInGmail",
-     "n8nType": "n8n-nodes-base.gmailTool",
-     "n8nName": "Send a message in Gmail",
-     "parameters": { "sendTo": "...", "message": "...", "subject": "..." },
-     "credentials": {
-       "gmailOAuth2": { "id": "...", "name": "Personal Gmail" },
-     },
-     "isAgentTool": true,
-     "agentName": "Inbox Assistant",
-   }
-   ```
-2. **Installed addons** — anything matching `@pikku/addon-*` in the project's `package.json` `dependencies`. The mapping is _only_ allowed against installed packages. If the addon for a given n8n type is not installed, surface that — do not silently skip and do not pick a vaguely-named function from another addon.
-
-## What you actually do, in order
-
-For **each** entry in the manifest:
-
-### Step 1 — identify the target addon
-
-Map `n8nType` to a `@pikku/addon-*` package by reading its source. Common shapes:
-
-| n8n type prefix                            | typical addon package candidate(s) |
-| ------------------------------------------ | ---------------------------------- |
-| `n8n-nodes-base.gmail` / `gmailTool`       | `@pikku/addon-email-gmail`         |
-| `n8n-nodes-base.slack` / `slackTool`       | `@pikku/addon-chat-slack`          |
-| `n8n-nodes-base.googleSheets` / `…Tool`    | `@pikku/addon-sheets-google`       |
-| `n8n-nodes-base.notion` / `notionTool`     | `@pikku/addon-docs-notion`         |
-| `n8n-nodes-base.telegram` / `telegramTool` | `@pikku/addon-chat-telegram`       |
-
-**These are guesses, not authoritative.** Always verify by reading the installed addon's `src/functions/**` to confirm the exported function names exist. If you cannot find an installed addon that plausibly covers this n8n type, stop and tell the user — do not pick a wrong addon.
-
-### Step 2 — pick the function (resource + operation → fn name)
-
-n8n integration nodes use a `(resource, operation)` pair to disambiguate. The mapping rubric:
-
-- `resource` defaults to the integration's primary noun if absent (gmail → `message`, slack → `message`, sheets → `spreadsheet`, etc.). Look at the addon's folder structure (`messages/`, `drafts/`, `channels/`) to see what nouns exist.
-- `operation` is usually a verb (`get`, `getAll`, `send`, `delete`, `addLabels`, `markAsRead`, `create`).
-- The pikku addon function name is almost always `<resource><Verb>` in camelCase, matching the file's `export const` (e.g. `messageList` for `messages/list.function.ts`, `draftCreate` for `drafts/create.function.ts`).
-
-Verify by `grep -h "^export const" <addonPkg>/src/functions/**/*.ts` and matching by name.
-
-Conventions seen in `@pikku/addon-email-gmail` (use as a sanity reference, **not** as a fallback if the addon is something else):
-
-- `getAll` → `<resource>List`
-- `get` → `<resource>Get`
-- `send` → `<resource>Send`
-- `delete` → `<resource>Delete`
-- `reply` → `<resource>Reply`
-- `addLabels` → `<resource>AddLabel` (singular!)
-- `removeLabels` → `<resource>RemoveLabel`
-- `markAsRead` / `markAsUnread` → `<resource>MarkRead` / `<resource>MarkUnread`
-- `create` (drafts/labels) → `<resource>Create`
-
-If the addon has a `node:` block on the function, prefer matching on that block's `category`/`displayName` over guessing — read the source.
-
-### Step 3 — rewrite the stub
-
-The stub file currently looks like:
-
-```ts
-import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku'
-
-export const AgentGmailtoolSendAMessageInGmailInput = z.object({
-  items: z.array(z.unknown()).optional(),
-})
-export const AgentGmailtoolSendAMessageInGmailOutput = z.object({
-  items: z.array(z.unknown()),
-})
-
-/** STUB — generated from n8n node "Send a message in Gmail" (type "n8n-nodes-base.gmailTool"). … */
-export const agentGmailtool__sendAMessageInGmail = pikkuSessionlessFunc({
-  func: async () => {
-    throw new Error('agentGmailtool__sendAMessageInGmail — implement me')
-  },
-})
-```
-
-**There are two outcomes**, depending on `isAgentTool`:
-
-#### A) `isAgentTool: true` — the stub is consumed by an agent via `ref()`
-
-The agent file references the stub by its export name. The cleanest path is:
-
-1. **Delete the stub file entirely.**
-2. In the agent file (look in the same emitted directory or `src/functions`), update the agent's `tools: [...]` array — replace `ref('agentGmailtool__sendAMessageInGmail')` with `ref('messageSend')` (or whichever addon function name you resolved).
-3. Make sure the addon package is imported wherever pikku scans functions (typically already handled by pikku CLI scanning `node_modules/@pikku/addon-*`).
-
-If you cannot delete the stub safely (e.g. it has multiple consumers, or the user wants to keep a thin wrapper for renaming), leave a _one-line_ re-export wrapper instead:
-
-```ts
-import { messageSend } from '@pikku/addon-email-gmail'
-export const agentGmailtool__sendAMessageInGmail = messageSend
-```
-
-But the default is delete + retarget. Wrappers add maintenance burden.
-
-#### B) `isAgentTool: false` — the stub is part of the workflow graph proper
-
-1. Open the workflow `.graph.ts` file.
-2. Find the entry in `nodes: { … }` whose value is the stub's rpc name (e.g. `'agentGmailtool__sendAMessageInGmail'`).
-3. Replace the value with the addon function name (e.g. `'messageSend'`).
-4. If the workflow's `config: { <id>: { input: … } }` block has an `input` expression that produces an `{ items }` envelope, rewrite it to produce the addon's actual input schema (read the addon function's `input: z.object({...})` to know the shape).
-5. Delete the stub file.
-
-### Step 4 — port hard-coded parameters
-
-n8n parameters fall into two camps:
-
-- **Hardcoded values** (e.g. `"limit": 20`, `"labelIds": ["INBOX"]`, `"sendTo": "alice@example.com"`) — these were user choices in the n8n UI. Preserve them in the workflow's `input` expression (case B), or, for agent tools (case A), document them in the agent's tool list comment so the user knows what was lost. **Agent tools cannot carry hardcoded params** — the LLM fills the args at call time. If the user _needs_ a hardcoded value baked in, they must keep a wrapper function. Surface this trade-off explicitly.
-- **`$fromAI('Name', '', 'string')` placeholders** — these are LLM-filled. They map naturally to addon function input fields the LLM will populate via the `pikkuAIAgent`'s tool-calling. No action needed beyond deleting the placeholder string; the addon's Zod schema becomes the tool schema.
-
-### Step 5 — credentials
-
-Each entry's `credentials: { gmailOAuth2: { id, name } }` is the n8n credential reference. Pikku addons typically expect a service (e.g. `services.gmail`) wired in `services.ts`. Do **not** attempt to auto-wire — append a one-line note for the user:
-
-> `// TODO: wire services.gmail using credential "Personal Gmail" (n8n id: gmail_cred_1) — see @pikku/addon-email-gmail/README.md`
-
-…either at the top of the workflow file or printed in your final summary.
-
-## What you must NOT do
-
-- **Do not invent functions** in addon packages that don't exist. Grep first.
-- **Do not pick the wrong addon** because the right one isn't installed. Stop and tell the user `npm i @pikku/addon-<x>` is required.
-- **Do not bake per-mapping tables into `@pikku/n8n-import`.** That package is intentionally addon-agnostic. All mapping logic lives here in this skill.
-- **Do not modify the manifest file.** It's an audit artifact. Leave it alone.
-- **Do not chain calls** ("send and then mark as read"). Each manifest entry maps to _one_ addon function. If the n8n graph composed multiple steps, the n8n-import already represented that as multiple stubs / multiple workflow nodes.
-- **Do not silently drop hardcoded params.** If the addon function has no place to put a value, surface it in the summary.
-
-## After you finish
-
-Print a short summary to the user:
-
-```
-Mapped 3 of 5 stubs:
-  ✓ agentGmailtool__sendAMessageInGmail → ref('messageSend')      [agent tool: Inbox Assistant]
-  ✓ agentGmailtool__getManyMessagesInGmail → ref('messageList')   [agent tool: Inbox Assistant]
-  ✓ workflow node 'updateRow' → 'sheetRowAppend'                  [graph node]
-
-Unmapped:
-  ✗ slackTool 'Post to channel'  — @pikku/addon-chat-slack not installed (npm i @pikku/addon-chat-slack)
-  ✗ notionTool 'Create page'     — no `pageCreate` in @pikku/addon-docs-notion (only `pageGet`, `pageUpdate`)
-
-Hardcoded params worth knowing:
-  • Get many messages in Gmail had limit=20, labelIds=["INBOX"] — agent tools cannot pin these; if you need them fixed, add a thin wrapper function.
-
-Credential wiring TODOs added to the top of agentGmailtool.graph.ts.
-```
-
-Be terse. The user already knows the workflow context — they pointed you at the manifest.