@pikku/skills 0.12.9 → 0.12.11

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-versioning/SKILL.md

@@ -3,10 +3,14 @@ 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"
+  hashing, and CI integration. Also covers `pikku semver`, which derives a release's semver by
+  diffing this build's surface against a deployed one and writes .pikku/changes.gen.json.
+  TRIGGER when: code uses version: on a pikkuFunc, user asks about
+  API versioning, breaking changes, contract hashes, backward compatibility, what semver a
+  release should get, comparing against production/staging, or "pikku versions" / "pikku semver"
   CLI commands. DO NOT TRIGGER when: user asks about secrets/variables/OAuth2 (use pikku-config)
-  or general function definitions (use pikku-concepts).
+  or general function definitions (use pikku-concepts), or about updating dependency versions
+  (use pikku-deps).
 installGroups: [core]
 ---
 
@@ -145,6 +149,84 @@ the manifest alone. Fix the contract or bump the version, then run it again.
 4. If intentional: pin the old contract as `…V1` with `version: 1`, bump the
    live function to `version: 2`, then `pikku versions update`
 
+## The `pikku semver` command
+
+`versions check` and `semver` answer different questions and share no state.
+`check` is a within-repo gate — "you changed a contract without bumping
+`version:`". `semver` is a release question — "what does this build owe the
+clients of the one already deployed?" — and needs an **external baseline**,
+which is why the answer is always relative to an environment rather than to
+the previous commit.
+
+```bash
+npx pikku semver --against https://api.acme.com/surface.json  # vs production
+npx pikku semver --against ../other-app/.pikku                # vs a checkout
+npx pikku semver --emit --out surface.json                    # publish a baseline
+npx pikku semver --against ... --fail-on major                # CI gate
+```
+
+`--against` takes three things and tells them apart itself: a directory is read
+as a `.pikku` tree, an `http(s)` URL is fetched as a published snapshot, and any
+other file is read as a snapshot. `--emit` produces the snapshot; **use `--out`**
+— plain `--emit` writes to stdout _after_ the CLI banner, so a bare `> file.json`
+captures the banner too. Publish the snapshot from CI on deploy and it becomes
+the baseline everyone else compares against.
+
+The verdict, in order:
+
+- **major** — a function or client-facing wiring was removed, or a surviving
+  one tightened its contract.
+- **minor** — anything was added, or a contract loosened compatibly.
+- **patch** — the surface did not move; the release is internal work.
+
+Below the id level it reads the generated JSON Schemas, and **direction
+decides**. An input is contravariant (the caller writes it) and an output is
+covariant (the caller reads it), so the same edit is not the same event on both:
+
+| Change                         | On an input                          | On an output |
+| ------------------------------ | ------------------------------------ | ------------ |
+| field removed                  | breaking (when the schema is closed) | breaking     |
+| required field added           | breaking                             | compatible   |
+| field became optional          | compatible                           | breaking     |
+| optional field became required | breaking                             | compatible   |
+| enum value removed             | breaking                             | compatible   |
+| enum value added               | compatible                           | breaking     |
+| type changed                   | breaking                             | breaking     |
+
+It consumes `versions.pikku.json`: published versions are immutable, so a
+function id that left the source while the manifest still records it is a `@vN`
+bump, not a removal — that is what keeps a deliberate version bump at `minor`.
+Without the manifest the same disappearance reads as `major`, which is the safe
+reading rather than a wrong one.
+
+Two things it deliberately will not guess. A named schema whose body did not
+travel with the baseline falls back to `contractHash` and, if that moved, is
+reported **breaking with the reason stated** — never quietly "unchanged". And at
+the wiring level only `auth` going from absent/false to true is classified as
+breaking; every other metadata change is reported as compatible, because there
+is no general way to tell a cosmetic wiring edit from a restricting one.
+
+Output is `.pikku/changes.gen.json` (override with `--out`), so it rides the
+same meta pipeline as `audit.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "baseline": "https://api.acme.com/surface.json",
+  "verdict": "major",
+  "summary": { "breaking": 1, "added": 1, "removed": 0, "modified": 1 },
+  "changes": [
+    {
+      "kind": "function",
+      "id": "getUser",
+      "status": "modified",
+      "breaking": true,
+      "reasons": ["input.tenant: required field added"]
+    }
+  ]
+}
+```
+
 ## CI Integration
 
 ```yaml
@@ -159,6 +241,8 @@ jobs:
       - uses: actions/checkout@v4
       - run: npm ci
       - run: npx pikku versions check
+      # Refuse to ship a breaking change to production unintentionally.
+      - run: npx pikku semver --against https://api.acme.com/surface.json --fail-on major
 ```
 
 ## Complete Example

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

package/skills/pikku-ws/SKILL.md

@@ -36,7 +36,7 @@ class. You own the `http.Server` and the `WebSocketServer`; the handler attaches
 the upgrade and message plumbing to them.
 
 ```typescript
-import { pikkuWebsocketHandler } from '@pikku/ws'
+import { DEFAULT_WS_MAX_PAYLOAD, pikkuWebsocketHandler } from '@pikku/ws'
 import { stopSingletonServices } from '@pikku/core'
 import { Server } from 'http'
 import { WebSocketServer } from 'ws'
@@ -48,7 +48,10 @@ const config = await createConfig()
 const singletonServices = await createSingletonServices(config)
 
 const server = new Server()
-const wss = new WebSocketServer({ noServer: true })
+const wss = new WebSocketServer({
+  noServer: true,
+  maxPayload: DEFAULT_WS_MAX_PAYLOAD,
+})
 
 pikkuWebsocketHandler({
   server,