@pikku/skills 0.12.10 → 0.12.11

package/skills/pikku-mcp/SKILL.md

@@ -74,7 +74,7 @@ returns MCP content blocks (`{ type: 'text', text }` or `{ type: 'image', data }
 with base64), so the assistant reads prose rather than raw JSON:
 
 ```typescript
-import { pikkuMCPToolFunc } from '#pikku'
+import { pikkuMCPToolFunc } from '#pikku/mcp'
 
 export const createTodoTool = pikkuMCPToolFunc({
   description: 'Create a todo item with title, priority, due date and tags',
@@ -96,7 +96,7 @@ presentation layer over logic that is already tested and reachable over HTTP.
 ### Resources
 
 ```typescript
-import { pikkuMCPResourceFunc } from '#pikku'
+import { pikkuMCPResourceFunc } from '#pikku/mcp'
 
 export const getTodoResource = pikkuMCPResourceFunc<{ id: string }>(
   async (_services, { id }, { rpc, mcp }) => {
@@ -117,7 +117,7 @@ it is text only, with no blob variant. `mcp.uri` is the concrete URI the client
 asked for, which is why each entry echoes it back.
 
 ```typescript
-import { wireMCPResource } from '#pikku'
+import { wireMCPResource } from '#pikku/mcp'
 
 wireMCPResource({
   uri: 'todos/{id}', // URI template
@@ -136,7 +136,7 @@ than handing the function an `undefined`.
 ### Prompts
 
 ```typescript
-import { pikkuMCPPromptFunc, wireMCPPrompt } from '#pikku'
+import { pikkuMCPPromptFunc, wireMCPPrompt } from '#pikku/mcp'
 
 export const planDayPrompt = pikkuMCPPromptFunc({
   input: UserIdInputSchema,

package/skills/pikku-middleware/SKILL.md

@@ -23,7 +23,7 @@ installGroups: [core]
 ## The `pikkuMiddleware` Factory
 
 ```typescript
-import { pikkuMiddleware } from '#pikku'
+import { pikkuMiddleware } from '#pikku/function'
 
 // Simple: just a function
 const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
@@ -54,7 +54,7 @@ The `wire` object gives you:
 - `wire.getSession()` — read the current session
 - `wire.session` — the session set so far (may be undefined)
 
-Throw a typed error to abort: `UnauthorizedError`, `ForbiddenError`, etc. from `@pikku/core/errors`.
+Throw a typed error to abort: `UnauthorizedError`, `ForbiddenError`, etc. from `#pikku/error`.
 
 ## Scoping: Five Levels
 
@@ -139,7 +139,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '#pikku'
+import { addTagMiddleware } from '#pikku/function'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -202,8 +202,8 @@ export const getToken = () => _token
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '#pikku'
-import { UnauthorizedError } from '@pikku/core/errors'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku/function'
+import { UnauthorizedError } from '#pikku/error'
 import { getToken } from '../lib/host-token.js'
 
 const bearerAuth = pikkuMiddleware(async (_services, { http }, next) => {

package/skills/pikku-middleware/references/middleware-patterns.md

@@ -31,17 +31,23 @@ export function getServiceRPC(baseUrl: string, token: string): RPCInvoke {
 ## Session-Setting Middleware
 
 ```typescript
-const apiKeyAuth = pikkuMiddleware(async ({ kysely }, { http, setSession, session }, next) => {
-  if (session) return next()  // already authenticated
+const apiKeyAuth = pikkuMiddleware(
+  async ({ kysely }, { http, setSession, session }, next) => {
+    if (session) return next() // already authenticated
 
-  const header = http?.request?.header?.('x-api-key')
-  if (!header) return next()
+    const header = http?.request?.header?.('x-api-key')
+    if (!header) return next()
 
-  const row = await kysely.selectFrom('apiKey').select('userId').where('key', '=', header).executeTakeFirst()
-  if (row) setSession?.({ userId: row.userId })
+    const row = await kysely
+      .selectFrom('apiKey')
+      .select('userId')
+      .where('key', '=', header)
+      .executeTakeFirst()
+    if (row) setSession?.({ userId: row.userId })
 
-  return next()
-})
+    return next()
+  }
+)
 
 addTagMiddleware('api-key-auth', [apiKeyAuth])
 ```

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

@@ -59,13 +59,13 @@ than the exit code to know what landed. Relay every skipped workflow to the user
 Every unmapped node is a stub that throws `… — implement me`. Classify each by its
 JSDoc marker and route to the matching reference:
 
-| Stub marker / signal | Handle via |
-|---|---|
-| `STUB — generated from n8n node "…" (type "n8n-nodes-base.<svc>…")` | `references/addon-mapping.md` |
-| `STUB — generated from n8n Code node "…"` | `references/code-translation.md` |
-| A `control` stub — Loop Over Items / **splitInBatches**, Switch expr-mode | `references/loops-and-control.md` |
-| `STUB — … vector-store … #902` | rare now (RAG ships as `<store>:query`/`:ingest`); a residual one = an unmapped store → report it, don't guess |
-| Importer `diagnostics` (already exited 1) | explain the reason; the workflow is un-importable as-is |
+| Stub marker / signal                                                      | Handle via                                                                                                     |
+| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `STUB — generated from n8n node "…" (type "n8n-nodes-base.<svc>…")`       | `references/addon-mapping.md`                                                                                  |
+| `STUB — generated from n8n Code node "…"`                                 | `references/code-translation.md`                                                                               |
+| A `control` stub — Loop Over Items / **splitInBatches**, Switch expr-mode | `references/loops-and-control.md`                                                                              |
+| `STUB — … vector-store … #902`                                            | rare now (RAG ships as `<store>:query`/`:ingest`); a residual one = an unmapped store → report it, don't guess |
+| Importer `diagnostics` (already exited 1)                                 | explain the reason; the workflow is un-importable as-is                                                        |
 
 Read a reference file only when you actually hit that stub class.
 
@@ -99,11 +99,11 @@ Missing integrations — install these or the nodes stay stubs:
 
 ## References
 
-| Open when you need to… | Read |
-|---|---|
-| map an integration stub (gmailTool, slackTool, googleSheets, plain action nodes) to an installed addon `ref(...)` | `references/addon-mapping.md` |
-| translate an n8n Code node body into a Pikku function body | `references/code-translation.md` |
-| lower a Loop Over Items / splitInBatches loop, or a Switch that stayed a stub | `references/loops-and-control.md` |
+| Open when you need to…                                                                                            | Read                              |
+| ----------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| map an integration stub (gmailTool, slackTool, googleSheets, plain action nodes) to an installed addon `ref(...)` | `references/addon-mapping.md`     |
+| translate an n8n Code node body into a Pikku function body                                                        | `references/code-translation.md`  |
+| lower a Loop Over Items / splitInBatches loop, or a Switch that stayed a stub                                     | `references/loops-and-control.md` |
 
 ## Final summary
 

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

@@ -11,6 +11,7 @@ remainder with judgment, report gaps that need a human decision, and verify.
 ## Scope
 
 In scope:
+
 - Running `pikku import n8n` and triaging its output.
 - Filling integration stubs (→ addon refs), Code stubs (→ function bodies), and
   loop/control stubs (→ `graph:map`/reduce/branch).
@@ -18,6 +19,7 @@ In scope:
 - Verifying via `pikku all` + `tsc` + a zero-surviving-stub check.
 
 Out of scope:
+
 - Extending `@pikku/n8n-import` itself (it is frozen; do not add per-service tables
   or new compiler rules to it).
 - Authoring workflows from scratch (`pikku-workflow`) or hand-written addon wiring
@@ -47,6 +49,7 @@ Out of scope:
 ## Source And Evidence Model
 
 Authoritative sources:
+
 - `@pikku/n8n-import` codegen (stub markers, manifest shape, `import-n8n` command).
 - `@pikku/addon-graph` function contracts (`graph:map`/`fanout`, `branch`).
 - Installed `@pikku/addon-*` source (function names verified by grep, never guessed).

package/skills/pikku-n8n-import/references/code-translation.md

@@ -20,39 +20,39 @@ refactor, add error handling, or invent fields.
 3. **Apply the rubric.**
 4. **Edit only the function body.** Leave imports, schemas, JSDoc, name, description, refs untouched unless step 5 forces it.
 5. **If the schemas are wrong** (code reads `$json.userId: string` but input is `items: z.array(z.unknown())`), tighten with the smallest change. Prefer `z.unknown()` over `z.any()`. Never widen output to `z.any()`.
-6. **Add one comment** at the top of the body noting the mode: `// translated from n8n Code node, mode: runOnceForAllItems`. This is the *only* comment you may add.
+6. **Add one comment** at the top of the body noting the mode: `// translated from n8n Code node, mode: runOnceForAllItems`. This is the _only_ comment you may add.
 7. **Typecheck** (`yarn tsc` from the package root); fix errors with the smallest change.
 
 ## Rubric
 
 ### Envelope unwrapping — all-items mode
 
-| n8n | Pikku |
-|---|---|
-| `items` | `(data.items ?? []) as any[]` (or typed if known) |
-| `items[i].json.X` | `items[i].X` |
-| `items[i].json` | `items[i]` |
-| `items[i].binary` | **NOT supported** — leave a TODO and explain |
-| `items.length` | `items.length` |
-| `items.map(i => i.json.X)` | `items.map((i: any) => i.X)` |
+| n8n                        | Pikku                                             |
+| -------------------------- | ------------------------------------------------- |
+| `items`                    | `(data.items ?? []) as any[]` (or typed if known) |
+| `items[i].json.X`          | `items[i].X`                                      |
+| `items[i].json`            | `items[i]`                                        |
+| `items[i].binary`          | **NOT supported** — leave a TODO and explain      |
+| `items.length`             | `items.length`                                    |
+| `items.map(i => i.json.X)` | `items.map((i: any) => i.X)`                      |
 
 ### Envelope unwrapping — each-item mode
 
-| n8n | Pikku |
-|---|---|
-| `$json.X` / `$input.item.json.X` | `data.X` (input is the item itself) |
-| `$input.item.json` | `data` |
-| `$input.all()` | not available per-item — change to all-items mode |
+| n8n                              | Pikku                                             |
+| -------------------------------- | ------------------------------------------------- |
+| `$json.X` / `$input.item.json.X` | `data.X` (input is the item itself)               |
+| `$input.item.json`               | `data`                                            |
+| `$input.all()`                   | not available per-item — change to all-items mode |
 
 ### Return statement
 
-| n8n | Pikku |
-|---|---|
-| `return [{ json: X }]` | `return { items: [X] }` |
-| `return items.map(i => ({ json: ... }))` | `return { items: items.map(...) }` |
-| `return [{ json: X }, { json: Y }]` | `return { items: [X, Y] }` |
-| `return { json: X }` (each-item) | `return X` |
-| `return [...]` (already plain) | wrap in `{ items: [...] }` only if the output schema expects it |
+| n8n                                      | Pikku                                                           |
+| ---------------------------------------- | --------------------------------------------------------------- |
+| `return [{ json: X }]`                   | `return { items: [X] }`                                         |
+| `return items.map(i => ({ json: ... }))` | `return { items: items.map(...) }`                              |
+| `return [{ json: X }, { json: Y }]`      | `return { items: [X, Y] }`                                      |
+| `return { json: X }` (each-item)         | `return X`                                                      |
+| `return [...]` (already plain)           | wrap in `{ items: [...] }` only if the output schema expects it |
 
 ### Built-ins — do NOT auto-translate
 
@@ -80,6 +80,7 @@ the first param).
 ## Example
 
 Before (stub):
+
 ```ts
 /**
  * STUB — generated from n8n Code node "Custom Code".
@@ -90,12 +91,15 @@ export const codeStubCustomCode = pikkuSessionlessFunc({
   input: CodeStubCustomCodeInput,
   output: CodeStubCustomCodeOutput,
   func: async (_services, _data) => {
-    throw new Error('Stub: ported from n8n Code node "Custom Code" — implement me')
+    throw new Error(
+      'Stub: ported from n8n Code node "Custom Code" — implement me'
+    )
   },
 })
 ```
 
 After:
+
 ```ts
 export const codeStubCustomCode = pikkuSessionlessFunc({
   description: 'Ported from n8n Code node "Custom Code"',

package/skills/pikku-n8n-import/references/loops-and-control.md

@@ -32,11 +32,11 @@ predecessor and any `$('<loop node>')` become `$item`.
 
 ### Decide the shape first
 
-| Loop body does… | Emit |
-|---|---|
-| transform each item independently (enrich, format, call one thing) | `graph:map` — child = the body |
-| accumulate across items (running total, build one object/array) | a **reduce**: a single generated function over the whole array, not a map — `graph:map` collects per-item results and *loses* the accumulator |
-| pure side-effect per item, nothing downstream consumes results | `graph:map` with **no `next`** (done branch empty) — the safest, unambiguous case |
+| Loop body does…                                                    | Emit                                                                                                                                          |
+| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| transform each item independently (enrich, format, call one thing) | `graph:map` — child = the body                                                                                                                |
+| accumulate across items (running total, build one object/array)    | a **reduce**: a single generated function over the whole array, not a map — `graph:map` collects per-item results and _loses_ the accumulator |
+| pure side-effect per item, nothing downstream consumes results     | `graph:map` with **no `next`** (done branch empty) — the safest, unambiguous case                                                             |
 
 ### Child arity
 
@@ -49,8 +49,8 @@ predecessor and any `$('<loop node>')` become `$item`.
 
 ### Done-branch semantics (ask if it matters)
 
-n8n's done output is version-dependent: it may carry the *original* items or the
-*accumulated* results. `graph:map`'s `next` receives the array of child results.
+n8n's done output is version-dependent: it may carry the _original_ items or the
+_accumulated_ results. `graph:map`'s `next` receives the array of child results.
 If a downstream node reads that array's shape and the distinction matters, add:
 
 ```ts

package/skills/pikku-paraglide/SKILL.md

@@ -18,7 +18,7 @@ Use this as an execution checklist, not reference material.
 ## The rules that don't change
 
 - **Never resolve an enum key dynamically.** No `mKey('status.' + value)`, no `m['enum__status__' + value]()`, no `mExists`/`mList` helpers. Dynamic keys can't be type-checked or tree-shaken. Everything is a static `m.<literal>()` reference, generated into the map.
-- **The `enum__<group>__<member>` namespace.** `__` separates the prefix / group / member segments; a single `_` joins words *within* a segment (`enum__booking_status__form_received`). The prefix (`enum`) and separator (`__`) are configurable but leave them at the defaults.
+- **The `enum__<group>__<member>` namespace.** `__` separates the prefix / group / member segments; a single `_` joins words _within_ a segment (`enum__booking_status__form_received`). The prefix (`enum`) and separator (`__`) are configurable but leave them at the defaults.
 - **Members must be valid JS identifiers.** Spell out leading digits — `two_guests`, not `2_guests`. The generator quotes an invalid member as a fallback but warns you to rename it.
 - **`asI18n(...)` is only for opaque server data** (names, slugs, ids returned from the API). Never `asI18n()` a hardcoded English string or an enum value — an enum value goes through its label map.
 
@@ -35,8 +35,8 @@ export type I18nMessage = () => I18nString
 export type EnumLabel<E extends string> = Record<E, I18nMessage>
 
 export const bookingStatus = {
-  enquiry:   m.enum__booking_status__enquiry,
-  reserved:  m.enum__booking_status__reserved,
+  enquiry: m.enum__booking_status__enquiry,
+  reserved: m.enum__booking_status__reserved,
   confirmed: m.enum__booking_status__confirmed,
 } satisfies EnumLabel<BookingStatus>
 export type BookingStatusKey = keyof typeof bookingStatus
@@ -61,18 +61,20 @@ const items = [{ label: m.common__nav__items__dashboard /* ← reference */ }]
 The DB column is the real source of truth for what an enum can be. The pikku CLI's db codegen emits a bare unions module — `.pikku/db/enums.gen.ts` — covering **both** Postgres native enums and SQLite `CHECK (col IN ('a','b',…))` constraints:
 
 ```ts
-export type BookingStatus = 'enquiry' | 'reserved' | 'confirmed' | 'ended' | 'cancelled'
+export type BookingStatus =
+  'enquiry' | 'reserved' | 'confirmed' | 'ended' | 'cancelled'
 ```
 
 Point `@pikku/paraglide` at that file (`enumsFile`) and each catalog group whose member set **exactly matches** a DB enum is typed `satisfies EnumLabel<DbEnum>`. The label map then **is** the reconciliation — no separate assertion:
 
 - catalog drops a DB member, or `en.json` is missing the key → `m.enum__…` doesn't exist / `Record<DbEnum,…>` isn't exhaustive → **`tsc` error naming the gap**.
 - a DB enum with **no** catalog group → `unmatchedDbEnums: 'emit'` (default) generates a label map referencing `enum__<table>_<column>__<member>` keys, so `tsc` tells you exactly which keys to add; `'warn'` only reports it.
-- a group with a member the DB lacks (a *derived* UI state, e.g. a `waitlisted` view of a `pending` row) → a drift warning. Make that a **standalone `m.<key>()` message**, not an enum member — the enum group must mirror the DB column exactly.
+- a group with a member the DB lacks (a _derived_ UI state, e.g. a `waitlisted` view of a `pending` row) → a drift warning. Make that a **standalone `m.<key>()` message**, not an enum member — the enum group must mirror the DB column exactly.
 
 Labelling an enum that's never rendered costs nothing: Paraglide compiles only the messages actually referenced, so unused labels are tree-shaken away. So label every DB enum; don't add an opt-out.
 
 **To make a column an enum**, give it a closed domain in the migration so codegen can see it:
+
 - SQLite: `status TEXT NOT NULL CHECK (status IN ('enquiry','reserved','confirmed'))`
 - Postgres: a native `CREATE TYPE … AS ENUM (…)` column.
 
@@ -88,7 +90,10 @@ import { paraglideEnums } from '@pikku/paraglide/vite'
 
 export default defineConfig({
   plugins: [
-    paraglideVitePlugin({ project: './project.inlang', outdir: './src/paraglide' }),
+    paraglideVitePlugin({
+      project: './project.inlang',
+      outdir: './src/paraglide',
+    }),
     paraglideEnums({
       catalog: './messages/en.json',
       outFile: './src/i18n/i18n-enum.gen.ts',

package/skills/pikku-permissions/SKILL.md

@@ -26,14 +26,14 @@ export const deleteBook = pikkuFunc({
     await db.deleteBook(bookId)
   },
   permissions: {
-    owner: isBookOwner,   // ← authorization here
+    owner: isBookOwner, // ← authorization here
   },
 })
 
 // WRONG — permission check inside func body
 export const deleteBook = pikkuFunc({
   func: async ({ db }, { bookId }, { session }) => {
-    if (!session) throw new UnauthorizedError()  // ← never do this
+    if (!session) throw new UnauthorizedError() // ← never do this
     await db.deleteBook(bookId)
   },
 })
@@ -54,7 +54,7 @@ Use for checks that read the session but need no request data — and that asser
 something **beyond** merely having a session (a flag, a tier, a claim).
 
 ```typescript
-import { pikkuAuth } from '#pikku'
+import { pikkuAuth } from '#pikku/function'
 
 // Good: a real gate on the session's contents, not just its existence.
 export const isVerified = pikkuAuth(
@@ -71,21 +71,21 @@ function already enforces. A function that needs a signed-in user sets
 ```typescript
 // WRONG — redundant with auth: true; adds a permission that gates nothing.
 export const isSignedIn = pikkuAuth(async (_s, session) => !!session)
-pikkuFunc({ auth: true, permissions: { signedIn: isSignedIn }, /* ... */ })
+pikkuFunc({ auth: true, permissions: { signedIn: isSignedIn } /* ... */ })
 
 // RIGHT — auth: true already requires the session; permissions are for capability.
-pikkuFunc({ auth: true, /* ... */ })
+pikkuFunc({ auth: true /* ... */ })
 ```
 
-A permission answers "*may this user do this?*" (role, ownership, tier) — never
-"*is there a session?*".
+A permission answers "_may this user do this?_" (role, ownership, tier) — never
+"_is there a session?_".
 
 ### `pikkuPermission(fn)` — Data-Aware Checks
 
 Use when authorization depends on the actual request data (e.g., resource ownership).
 
 ```typescript
-import { pikkuPermission } from '#pikku'
+import { pikkuPermission } from '#pikku/function'
 
 export const isBookOwner = pikkuPermission(
   async ({ db }, { bookId }, { session }) => {
@@ -132,24 +132,24 @@ export const deleteBook = pikkuFunc({
 
 ### Global (`addGlobalPermission`) — App-Wide AND Gate
 
-A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever *narrow* access — it never grants access a function's own `permissions` would deny.
+A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever _narrow_ access — it never grants access a function's own `permissions` would deny.
 
 ```typescript
-import { addGlobalPermission } from '#pikku'
+import { addGlobalPermission } from '#pikku/function'
 
 addGlobalPermission([isEmployee]) // every function now also requires an employee session
 ```
 
 Multiple `addGlobalPermission` calls accumulate and are AND'd together.
 
-> Wire-, tag-, and HTTP-route-level permissions (`addHTTPPermission`, `addTagPermission`, and a `permissions` field on HTTP/channel/MCP wirings) were **removed in #972**. Permissions now live only on the function definition, plus the optional global gate. Tags are organizational only — use tag/HTTP *middleware* (`addTagMiddleware`, `addHTTPMiddleware`) for cross-cutting request handling, not authorization.
+> Wire-, tag-, and HTTP-route-level permissions (`addHTTPPermission`, `addTagPermission`, and a `permissions` field on HTTP/channel/MCP wirings) were **removed in #972**. Permissions now live only on the function definition, plus the optional global gate. Tags are organizational only — use tag/HTTP _middleware_ (`addTagMiddleware`, `addHTTPMiddleware`) for cross-cutting request handling, not authorization.
 
 ## Scopes — the AND Gate Above Permissions
 
 Scopes answer "what was this session granted?" before permissions ask "may this
 user do this to this resource?". They are AND-ed: every scope listed must be
 held. Because they are checked first and fail closed, a scope can only ever
-*narrow* access — it never grants what `permissions` would deny.
+_narrow_ access — it never grants what `permissions` would deny.
 
 Declare the scope tree once with `defineScope`. The body is a no-op that
 tree-shakes away; the CLI reads the call by AST and generates a `ScopeId` union,
@@ -158,7 +158,7 @@ gating on nothing.
 
 ```typescript
 // src/scopes.ts
-import { defineScope } from '#pikku'
+import { defineScope } from '#pikku/scopes'
 
 defineScope({
   admin: {
@@ -222,7 +222,11 @@ export const handleStripeWebhook = pikkuSessionlessFunc({
   permissionsInBody: true,
   auth: false,
   func: async ({ stripe }, data, { http }) => {
-    stripe.webhooks.constructEvent(data.raw, http.request.header('stripe-signature'), secret)
+    stripe.webhooks.constructEvent(
+      data.raw,
+      http.request.header('stripe-signature'),
+      secret
+    )
     // ...
   },
 })
@@ -240,7 +244,7 @@ declared, inspectable, and reusable.
 
 ```typescript
 // src/permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku'
+import { pikkuAuth, pikkuPermission } from '#pikku/function'
 
 export const isVerified = pikkuAuth(
   async (_services, session) => !!session?.emailVerified

package/skills/pikku-product-second-opinion/README.md

@@ -11,8 +11,8 @@ Existing repo → pikku-software-archaeology → .knowledge/ blueprint → pikku
 
 ## The split from pikku-software-archaeology
 
-- **pikku-software-archaeology** extracts *facts* into `.knowledge/` for a machine (Pikku) to rebuild from. Engineer/generator audience.
-- **pikku-product-second-opinion** reads that blueprint and writes an *opinionated report* for a human to decide from. Non-technical audience.
+- **pikku-software-archaeology** extracts _facts_ into `.knowledge/` for a machine (Pikku) to rebuild from. Engineer/generator audience.
+- **pikku-product-second-opinion** reads that blueprint and writes an _opinionated report_ for a human to decide from. Non-technical audience.
 
 One extracts; one advises. This skill consumes the other's output — it doesn't re-read the code.
 
@@ -30,7 +30,7 @@ One extracts; one advises. This skill consumes the other's output — it doesn't
 4. **Argue improvements in business outcomes** (more reliable / faster / cheaper / safer / easier to hand off), and say whether each is a cheap **rewire** or an expensive **rebuild** — never recommend a rewrite just because the code is messy.
 5. **Mark confidence.** Certain and "I'd need to check" are different sentences.
 6. **Cover the frontend and the other ways the app is used** when the blueprint has them — walk the screens as a journey, call out consistency, and flag the custom-logic pieces (charts/tables/editors) as the real work vs the cheap standard pieces. Name the ways the product can be driven (people/web, developers/API+SDK, AI agents/MCP, power users/CLI) — often a genuine strength.
-7. **Give honest technology tradeoffs — both sides.** Every stack bet (framework, auth, hosting, key libraries) gets what-it-buys AND what-it-costs in business terms, tied to the founder's stage/goals. Don't cheerlead, don't trash, and **don't soften the disadvantages**. The app's own bets are derived from the blueprint (`architecture.json`/`integrations.json`/`frontend.json` + the repo's manifest) — never from a list in the skill, because a verdict you could write before reading the blueprint isn't a second opinion. Separately, and only when a rebuild is actually being recommended, the target stack (Pikku, Better Auth, TanStack Start) gets the *same* both-sides treatment with cons first-class — pinning someone's dependency for being pre-1.0 while staying quiet about the replacement being pre-1.0 too is a pitch, not an opinion.
+7. **Give honest technology tradeoffs — both sides.** Every stack bet (framework, auth, hosting, key libraries) gets what-it-buys AND what-it-costs in business terms, tied to the founder's stage/goals. Don't cheerlead, don't trash, and **don't soften the disadvantages**. The app's own bets are derived from the blueprint (`architecture.json`/`integrations.json`/`frontend.json` + the repo's manifest) — never from a list in the skill, because a verdict you could write before reading the blueprint isn't a second opinion. Separately, and only when a rebuild is actually being recommended, the target stack (Pikku, Better Auth, TanStack Start) gets the _same_ both-sides treatment with cons first-class — pinning someone's dependency for being pre-1.0 while staying quiet about the replacement being pre-1.0 too is a pitch, not an opinion.
 
 ## Files
 

package/skills/pikku-product-second-opinion/example/sample-report.md

@@ -1,5 +1,6 @@
 # Your app, in plain English — and where it could get better
-*A second opinion on the competitor-tracking system*
+
+_A second opinion on the competitor-tracking system_
 
 > Worked example for the pikku-product-second-opinion skill. Shows the voice and the
 > layered structure on one real area (competitor tracking), drawn from a
@@ -18,17 +19,18 @@ websites, spots meaningful changes (pricing, hiring, product updates), summarize
 them, and feeds your briefings and dashboards so your team knows first.
 
 **The headline.**
+
 - The hard part — reading messy websites and telling a real change from noise — is built well.
-- Until recently the app wasn't re-checking sites on its own at all *(now fixed)*.
+- Until recently the app wasn't re-checking sites on its own at all _(now fixed)_.
 - When it does spot a change, the follow-up work only happens if someone clicks a button — so your dashboards can quietly go stale while looking current.
 
 **If it were me, this is the order I'd tackle things:**
 
-| Fix | Why it matters to you | Effort | Payoff |
-|---|---|---|---|
-| Turn on automatic checking | Sites weren't refreshing themselves | *Done* | High |
-| Make the follow-up automatic | Stops your intelligence going stale unnoticed | Medium | High |
-| Make failures visible | Problems surface instead of hiding | Small | Medium |
+| Fix                          | Why it matters to you                         | Effort | Payoff |
+| ---------------------------- | --------------------------------------------- | ------ | ------ |
+| Turn on automatic checking   | Sites weren't refreshing themselves           | _Done_ | High   |
+| Make the follow-up automatic | Stops your intelligence going stale unnoticed | Medium | High   |
+| Make failures visible        | Problems surface instead of hiding            | Small  | Medium |
 
 ---
 
@@ -41,7 +43,7 @@ changes into summaries your team can act on.
 
 **How it works today.** Like a clipping service: on a timer, the app re-reads
 each competitor's site, compares it to last time, decides whether anything
-*meaningful* changed (it ignores trivial edits), and writes up a summary when
+_meaningful_ changed (it ignores trivial edits), and writes up a summary when
 something real happens.
 
 **What's working.** The expensive, valuable part is solid — the app is genuinely
@@ -49,10 +51,11 @@ good at reading messy sites, separating real changes from noise, and summarizing
 them. Keep it.
 
 **What's holding you back.**
+
 - **The automatic checking wasn't switched on.** The machinery existed but nothing
   pulled the trigger, so sites weren't refreshing on their own. What it means for
   you: your "live" intelligence wasn't live. Severity: Urgent. Effort: Small.
-  *(Already fixed.)*
+  _(Already fixed.)_
 - **The follow-up is manual.** When a change is found, updating your briefings and
   comparisons doesn't happen on its own — someone has to click "regenerate." What
   it means for you: if nobody clicks, the dashboard shows old information while
@@ -70,15 +73,15 @@ surprises** — which is the entire promise of the product.
 
 ### The technology bets
 
-**Pikku — the framework I'm suggesting you rebuild onto.** *Buys you:* one way to
+**Pikku — the framework I'm suggesting you rebuild onto.** _Buys you:_ one way to
 write a capability and drive it from anywhere — web, timers, background jobs,
 assistants — so the tracking rule is written once instead of three times, which is
-exactly the sprawl above. *Costs you:* it hasn't shipped a stable 1.0 (it's 0.12.x;
+exactly the sprawl above. _Costs you:_ it hasn't shipped a stable 1.0 (it's 0.12.x;
 0.13 is the first release promising backwards compatibility), so until then
 upgrades can break you — pin the version and budget for upgrade work. Its community
 and hiring pool are far smaller than the mainstream default's. That's normal for a
 young framework and survivable, but it's a real cost and it's yours to weigh.
-*Usually:* worth it when the problem is genuinely sprawl, as it is here — and worth
+_Usually:_ worth it when the problem is genuinely sprawl, as it is here — and worth
 waiting if nobody has capacity to own upgrades.
 
 ---

package/skills/pikku-product-second-opinion/references/report-template.md

@@ -6,7 +6,8 @@ reader. Delete any section that would be empty rather than padding it.
 ---
 
 # {App name}, in plain English — and where it could get better
-*A second opinion on {scope: the whole app / the competitor-tracking system / …}*
+
+_A second opinion on {scope: the whole app / the competitor-tracking system / …}_
 
 **How to read this:** no technical background needed. Part 1 is the summary — if
 you read nothing else, read that. Parts 2–3 go area by area for anyone who wants
@@ -21,9 +22,9 @@ opportunities. No jargon.}
 
 **If it were me, this is the order I'd tackle things:**
 
-| Fix | Why it matters to you | Effort | Payoff |
-|---|---|---|---|
-| {…} | {business impact} | Small/Medium/Large | High/Medium/Low |
+| Fix | Why it matters to you | Effort             | Payoff          |
+| --- | --------------------- | ------------------ | --------------- |
+| {…} | {business impact}     | Small/Medium/Large | High/Medium/Low |
 
 ---
 
@@ -38,6 +39,7 @@ opportunities. No jargon.}
 **What's working.** {genuine credit — the parts that are solid and worth keeping}
 
 **What's holding you back.**
+
 - **{Problem in plain terms}.** What it means for you: {business impact}.
   Severity: {Minor / Worth fixing / Serious / Urgent}. Effort to fix: {Small /
   Medium / Large}.
@@ -54,11 +56,12 @@ off. Say whether it's a cheap rewire or an expensive rebuild.}
 libraries — AND anything a rebuild would move them ONTO. Each gets both sides.}
 
 **{Technology}.**
-- *Buys you:* {in business terms}
-- *Costs you:* {in business terms — bills, hiring, shipping speed, upgrade work,
+
+- _Buys you:_ {in business terms}
+- _Costs you:_ {in business terms — bills, hiring, shipping speed, upgrade work,
   the risk of betting on something young. Don't soften it. If it hasn't shipped a
   stable 1.0, say so and say what that means: pin the version, budget upgrades.}
-- *Usually:* {recommendation tied to their stage — normally "keep it, watch this"}
+- _Usually:_ {recommendation tied to their stage — normally "keep it, watch this"}
 
 {The same bar applies to anything you're recommending they move to. A stack you
 propose with no cons listed is a pitch, not a second opinion.}

package/skills/pikku-queue/SKILL.md

@@ -63,7 +63,7 @@ Not every adapter supports every option. Each adapter declares a
 silently ignored — so check the startup logs if a setting appears to have no
 effect.
 
-`groupConcurrency` limits how many jobs run concurrently *per group* (jobs
+`groupConcurrency` limits how many jobs run concurrently _per group_ (jobs
 carrying a `JobGroup` with an `id` and optional `tier`), so one noisy tenant
 cannot consume the whole worker: