@pikku/skills 0.12.10 → 0.12.12

package/skills/pikku-services/SKILL.md

@@ -38,7 +38,7 @@ pikku info tags --verbose        # Understand project organization
 ### `pikkuServices(factory)` — singleton services (created once at startup)
 
 ```typescript
-import { pikkuServices } from '#pikku'
+import { pikkuServices } from '#pikku/function'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 
@@ -61,7 +61,7 @@ export const createSingletonServices = pikkuServices(
 ### `pikkuWireServices(factory)` — per-request services (fresh per HTTP request, queue job, CLI command, etc.)
 
 ```typescript
-import { pikkuWireServices } from '#pikku'
+import { pikkuWireServices } from '#pikku/function'
 
 export const createWireServices = pikkuWireServices(
   async (singletonServices, wire) => {
@@ -157,13 +157,16 @@ const getUser = pikkuFunc({
 
 **Never write a `if (!service) throw ...` existence guard in a function body.** It is dead code, and it defeats the platform.
 
-Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means *"this may not be created"*, not *"this may be missing at call time"*. A service is optional precisely because **nothing destructures it**, and the generated `requiredSingletonServices` manifest therefore never marks it for creation. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
+Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means _"this may not be created"_, not _"this may be missing at call time"_. A service is optional precisely because **nothing destructures it**, and the generated `requiredSingletonServices` manifest therefore never marks it for creation. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
 
 The types enforce this rather than merely documenting it. The inspector records the services destructured by every wired `func`, `permissions` **and** `middleware`, and emits them as `RequiredSingletonServices`. The generated function types then default their service parameter to:
 
 ```typescript
-export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
-export type WiredServices = SecretlessServices<RequiredSingletonServices & Services>
+export type WiredSingletonServices = RequiredSingletonServices &
+  SingletonServices
+export type WiredServices = SecretlessServices<
+  RequiredSingletonServices & Services
+>
 ```
 
 The `SecretlessServices<...>` wrapper is why `secrets` never appears in a
@@ -223,21 +226,21 @@ const createSingletonServices = pikkuServices(async (config) => {
 
 ### Built-in Services
 
-| Service                    | Package                | Purpose                          |
-| -------------------------- | ---------------------- | -------------------------------- |
-| `ConsoleLogger`            | `@pikku/core/services` | Console-based logging            |
-| `JoseJWTService`           | `@pikku/jose`          | JWT sign/verify via jose         |
-| `LocalSecretService`       | `@pikku/core/services` | Local development secrets        |
-| `LocalVariablesService`    | `@pikku/core/services` | Local environment variables      |
-| `PinoLogger`               | `@pikku/pino`          | Structured logging via Pino      |
-| `createInvocationAudit`    | `@pikku/core/services` | Per-request audit buffer         |
-| `createAuditedKysely`      | `@pikku/kysely`        | Auto-capture DB queries as audit events |
+| Service                 | Package                | Purpose                                 |
+| ----------------------- | ---------------------- | --------------------------------------- |
+| `ConsoleLogger`         | `@pikku/core/services` | Console-based logging                   |
+| `JoseJWTService`        | `@pikku/jose`          | JWT sign/verify via jose                |
+| `LocalSecretService`    | `@pikku/core/services` | Local development secrets               |
+| `LocalVariablesService` | `@pikku/core/services` | Local environment variables             |
+| `PinoLogger`            | `@pikku/pino`          | Structured logging via Pino             |
+| `createInvocationAudit` | `@pikku/core/services` | Per-request audit buffer                |
+| `createAuditedKysely`   | `@pikku/kysely`        | Auto-capture DB queries as audit events |
 
 ## Complete Example
 
 ```typescript
 // services.ts
-import { pikkuServices, pikkuWireServices } from '#pikku'
+import { pikkuServices, pikkuWireServices } from '#pikku/function'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 
@@ -249,9 +252,15 @@ class TodoStore {
     this.todos.set(todo.id, todo)
     return todo
   }
-  async get(id: string) { return this.todos.get(id) }
-  async list() { return [...this.todos.values()] }
-  async delete(id: string) { this.todos.delete(id) }
+  async get(id: string) {
+    return this.todos.get(id)
+  }
+  async list() {
+    return [...this.todos.values()]
+  }
+  async delete(id: string) {
+    this.todos.delete(id)
+  }
 }
 
 export const createSingletonServices = pikkuServices(async (config) => {

package/skills/pikku-services/references/audit-wire-service.md

@@ -9,13 +9,15 @@ Pair with `createAuditedKysely` to auto-capture every Kysely query as an audit e
 import { createInvocationAudit } from '@pikku/core/services'
 import { createAuditedKysely } from '@pikku/kysely'
 
-export const createWireServices = pikkuWireServices(async (singletonServices, wire) => {
-  const audit = createInvocationAudit(singletonServices.audit, wire)
-  const kysely = singletonServices.kysely
-    ? createAuditedKysely(singletonServices.kysely, { audit })
-    : undefined
-  return { audit, ...(kysely ? { kysely } : {}) }
-})
+export const createWireServices = pikkuWireServices(
+  async (singletonServices, wire) => {
+    const audit = createInvocationAudit(singletonServices.audit, wire)
+    const kysely = singletonServices.kysely
+      ? createAuditedKysely(singletonServices.kysely, { audit })
+      : undefined
+    return { audit, ...(kysely ? { kysely } : {}) }
+  }
+)
 ```
 
 The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions that emit custom events use it directly:
@@ -24,7 +26,11 @@ The `audit` wire service is typed as `AuditLog` (from `@pikku/core`). Functions
 const deleteUser = pikkuFunc({
   func: async ({ audit }, { userId }) => {
     // The user identity comes from the wire session — the payload is metadata.
-    await audit.write({ type: 'user.deleted', source: 'explicit', metadata: { userId } })
+    await audit.write({
+      type: 'user.deleted',
+      source: 'explicit',
+      metadata: { userId },
+    })
     // ...
   },
 })

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

@@ -5,118 +5,182 @@
 //
 // 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';
+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 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 dir = process.argv[2]
+if (!dir) {
+  console.error('usage: node validate.mjs <.knowledge dir>')
+  process.exit(2)
+}
 
-const errors = [];
-const warnings = [];
+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]];
+  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.$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;
+    errors.push(
+      `${path}: expected one of [${schema.enum.join(', ')}], got ${JSON.stringify(value)}`
+    )
+    return
   }
-  const t = schema.type;
+  const t = schema.type
   if (t === 'object') {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-      errors.push(`${path}: expected object`); return;
+      errors.push(`${path}: expected object`)
+      return
     }
     for (const req of schema.required || []) {
-      if (!(req in value)) errors.push(`${path}: missing required field "${req}"`);
+      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}`);
+      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 (!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}`);
+      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}]`));
+    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 (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}`);
+      errors.push(`${path}: "${value}" does not match ${schema.pattern}`)
     }
   } else if (t === 'boolean' && typeof value !== 'boolean') {
-    errors.push(`${path}: expected boolean`);
+    errors.push(`${path}: expected boolean`)
   } else if (t === 'number' && typeof value !== 'number') {
-    errors.push(`${path}: expected 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 = {};
+const docs = {}
 for (const [filename, fileSchema] of Object.entries(schemaDoc.files)) {
-  const p = join(dir, filename);
+  const p = join(dir, filename)
   if (!existsSync(p)) {
-    if (!fileSchema['x-optional']) errors.push(`${filename}: missing`);
-    continue;
+    if (!fileSchema['x-optional']) errors.push(`${filename}: missing`)
+    continue
   }
   try {
-    docs[filename] = JSON.parse(readFileSync(p, 'utf8'));
+    docs[filename] = JSON.parse(readFileSync(p, 'utf8'))
   } catch (e) {
-    errors.push(`${filename}: invalid JSON (${e.message})`); continue;
+    errors.push(`${filename}: invalid JSON (${e.message})`)
+    continue
   }
-  check(docs[filename], fileSchema, filename);
+  check(docs[filename], fileSchema, filename)
 }
-if (!existsSync(join(dir, 'blueprint.md'))) errors.push('blueprint.md: missing');
+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 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`);
-  };
+    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);
+    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`);
+      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 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)`);
+    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`);
+    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?`);
+      warnings.push(
+        `commands.json:${c.name}: no policies or preconditions — really unguarded, or missed extraction?`
+      )
     }
   }
 }
@@ -124,13 +188,15 @@ if (docs['domains.json'] && docs['commands.json']) {
 // --- 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),
-  );
+    (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`);
+        warnings.push(
+          `frontend-routes.json:${r.path}: uses component "${c}" not in frontend-components.json`
+        )
       }
     }
   }
@@ -138,7 +204,9 @@ if (docs['frontend-components.json']) {
   // 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`);
+      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
@@ -146,11 +214,13 @@ if (docs['frontend-components.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`);
+          warnings.push(
+            `frontend-routes.json:${r.path}: reads "${d}" which is not a known query/command`
+          )
         }
       }
     }
@@ -160,14 +230,21 @@ if (docs['frontend-components.json']) {
 // 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/…)`);
+  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);
+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-tag-middleware/SKILL.md

@@ -6,6 +6,7 @@ description: 'Deprecated — use pikku-middleware instead. Tag middleware (addTa
 # Deprecated: use `pikku-middleware`
 
 Tag middleware is covered in the **`pikku-middleware`** skill, which also covers:
+
 - `addHTTPMiddleware` (global / prefix-based)
 - `addTagMiddleware` (tag-scoped)
 - Middleware execution order and priority

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

@@ -26,8 +26,9 @@ commit, separate from any feature work.
 
    `create-pikku` keeps only the chosen package manager's lockfile and deletes
    the other, and for yarn it may have written an **empty** `yarn.lock` as a
-   marker. Commit the lockfile *after* the first install has filled it in —
+   marker. Commit the lockfile _after_ the first install has filled it in —
    committing the empty placeholder pins nothing.
+
 3. **Rename template identifiers.** Update `name` in the root `package.json`
    (and any `@project/*` or other placeholder names) to the real project.
 4. **Drop template-only artifacts.** Remove any `TEMPLATE.md`, demo docs, or

package/skills/pikku-trigger/SKILL.md

@@ -45,7 +45,7 @@ handler, and a handler can exist before any source is wired.
 Define the target function that handles trigger events:
 
 ```typescript
-import { wireTrigger } from '#pikku'
+import { wireTrigger } from '#pikku/trigger'
 
 wireTrigger({
   name: string, // Trigger name (matches source)
@@ -60,7 +60,7 @@ wireTrigger({
 Define the event source that fires triggers:
 
 ```typescript
-import { wireTriggerSource } from '#pikku'
+import { wireTriggerSource } from '#pikku/trigger'
 
 wireTriggerSource({
   name: string, // Must match a wireTrigger name
@@ -80,7 +80,7 @@ up a listener, calls `trigger.invoke(...)` for each event it sees, and returns a
 teardown function:
 
 ```typescript
-import { pikkuTriggerFunc } from '#pikku'
+import { pikkuTriggerFunc } from '#pikku/trigger'
 
 const source = pikkuTriggerFunc<
   InputType, // Configuration input

package/skills/pikku-websocket/SKILL.md

@@ -94,8 +94,9 @@ wireChannel({
   name: 'todos',
   route: '/todos',
   onMessageWiring: {
-    action: {                                  // ← the field to route on
-      create: { func: createTodo },            // ← its possible values
+    action: {
+      // ← the field to route on
+      create: { func: createTodo }, // ← its possible values
       list: { func: listTodos, auth: false },
     },
   },
@@ -129,7 +130,7 @@ wireChannel({
   onMessageWiring: {
     action: {
       authenticate: { func: authenticate, auth: false }, // No session required
-      subscribe: { func: subscribeTodos },               // Session required
+      subscribe: { func: subscribeTodos }, // Session required
       create: { func: createTodo },
     },
   },

package/skills/pikku-workflow/SKILL.md

@@ -64,8 +64,8 @@ import {
   pikkuWorkflowComplexFunc,
 } from '#pikku/workflow/pikku-workflow-types.gen.js'
 
-// WRONG — '#pikku' does not re-export them (TS2305)
-import { pikkuWorkflowFunc } from '#pikku'
+// WRONG — the function leaf does not re-export them (TS2305)
+import { pikkuWorkflowFunc } from '#pikku/function'
 ```
 
 ## Defining a workflow

package/skills/pikku-workflow/references/workflow-reference.md

@@ -6,15 +6,15 @@ Whether a step runs **inline** (same process/session, no queue round-trip) or is
 
 - **Steps default to inline.** Most steps don't need their own worker; running them inline avoids a queue round-trip per step, so a normally-started workflow executes its whole chain in one orchestrator pass.
 - **`workflowQueued: true` opts a function out.** Set it on the **function config** (`pikkuFunc` / `pikkuSessionlessFunc`, same level as `auth`/`expose`) to dispatch that step via the queue — for expensive/long-running steps that deserve their own worker, retry isolation, and concurrency limits. `workflowRetries` and `workflowTimeout` sit alongside it.
-- **Run-level `inline` is separate** and only controls whether the *whole run* executes in-process without queue infrastructure (set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, not per-step dispatch.
+- **Run-level `inline` is separate** and only controls whether the _whole run_ executes in-process without queue infrastructure (set automatically when there is no `queueService`, or via `startWorkflow(..., { inline: true })`). It governs sleep handling, not per-step dispatch.
 
 The rule (`dispatchStep`):
 
-| Function `workflowQueued` | `queueService` present? | Result |
-|---|---|---|
-| default / `false` | any | **inline** |
-| `true` | yes | **queued** (own worker) |
-| `true` | no | **throws** |
+| Function `workflowQueued` | `queueService` present? | Result                  |
+| ------------------------- | ----------------------- | ----------------------- |
+| default / `false`         | any                     | **inline**              |
+| `true`                    | yes                     | **queued** (own worker) |
+| `true`                    | no                      | **throws**              |
 
 ```typescript
 // Push this one expensive step onto the queue; every other step stays inline:
@@ -24,7 +24,9 @@ export const renderLargeReport = pikkuSessionlessFunc({
   workflowTimeout: '5m',
   input: ReportInput,
   output: ReportOutput,
-  func: async (services, data) => { /* ... */ },
+  func: async (services, data) => {
+    /* ... */
+  },
 })
 ```
 
@@ -39,13 +41,25 @@ Usually auto-scaffolded via `scaffold.workflow`. To wire by hand:
 
 ```typescript
 // Start a workflow
-wireHTTP({ method: 'post', route: '/onboard', func: workflowStart('onboardUser') })
+wireHTTP({
+  method: 'post',
+  route: '/onboard',
+  func: workflowStart('onboardUser'),
+})
 
 // Execute workflow steps (called by the orchestrator)
-wireHTTP({ method: 'post', route: '/onboard/run', func: workflow('onboardUser') })
+wireHTTP({
+  method: 'post',
+  route: '/onboard/run',
+  func: workflow('onboardUser'),
+})
 
 // Check workflow status
-wireHTTP({ method: 'get', route: '/onboard/status/:runId', func: workflowStatus('onboardUser') })
+wireHTTP({
+  method: 'get',
+  route: '/onboard/status/:runId',
+  func: workflowStatus('onboardUser'),
+})
 ```
 
 ## Suspend / resume example