@pikku/cli 0.12.91 → 0.12.93

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

@@ -1,49 +0,0 @@
-# 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

@@ -1,173 +0,0 @@
-#!/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-tag-middleware/SKILL.md

@@ -1,13 +0,0 @@
----
-name: pikku-tag-middleware
-description: 'Deprecated — use pikku-middleware instead. Tag middleware (addTagMiddleware) is now documented as a section within the pikku-middleware skill, alongside global HTTP middleware, execution order, and the service-to-service bearer auth pattern.'
----
-
-# 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
-- Service-to-service bearer auth pattern
-- Session-setting middleware pattern

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

@@ -1,40 +0,0 @@
----
-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 `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 *)
-installGroups: [core]
----
-
-# Pikku Template Post-Clone Cleanup
-
-## Agent Operating Procedure
-
-Run this **once**, right after a template is cloned or scaffolded into a new
-project. The goal is to turn template scaffolding into a real project. Make the
-smallest changes and land them as one focused `chore: post-clone cleanup`
-commit, separate from any feature work.
-
-1. **Replace the template README.** The shipped `README.md` describes the
-   _template_, not the user's project — leaving it in place is misleading.
-   Either delete it (`git rm README.md`) or rewrite it with the new project's
-   name and purpose. Never ship a clone with the generic template README.
-2. **Keep the lockfile committed.** Templates ship a committed `yarn.lock`; do
-   NOT re-add `yarn.lock` to `.gitignore`. A real project commits its lockfile
-   for reproducible installs. The correct pattern is `yarn.lock` followed by
-   `!/yarn.lock`, which commits the root lockfile while keeping generated
-   per-unit lockfiles under `.deploy/` (and `e2e/`) ignored.
-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
-   placeholder content that only made sense for the template.
-
-Do not touch generated files (`.pikku/`, `*.gen.*`) or run a full reinstall as
-part of cleanup — this step is project hygiene, not a build.
-
-## Why this exists
-
-Templates are structure-only starting points. Without this pass, clones carry a
-misleading README, a placeholder package name, and (historically) a gitignored
-lockfile — all of which leak template assumptions into a real project. Running
-it immediately after clone keeps every Pikku project, OSS or Fabric, starting
-from a clean, honest baseline.

package/skills/pikku-trigger/SKILL.md

@@ -1,181 +0,0 @@
----
-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).
-installGroups: [core]
----
-
-# Pikku Trigger Wiring
-
-## 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.
-
-Wire Pikku functions to fire when external events occur. Triggers connect event sources (Redis pub/sub, PostgreSQL LISTEN/NOTIFY, polling, webhooks) to Pikku functions.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and their types
-pikku info tags --verbose        # Understand project organization
-```
-
-See `pikku-concepts` for the core mental model.
-
-## API Reference
-
-### `wireTrigger(config)`
-
-Define the target function that handles trigger events:
-
-```typescript
-import { wireTrigger } from '@pikku/core/trigger'
-
-wireTrigger({
-  name: string, // Trigger name (matches source)
-  func: PikkuFunc, // Function to call when event fires
-})
-```
-
-### `wireTriggerSource(config)`
-
-Define the event source that fires triggers:
-
-```typescript
-import { wireTriggerSource } from '@pikku/core/trigger'
-
-wireTriggerSource({
-  name: string, // Must match wireTrigger name
-  func: PikkuTriggerFunc, // Source function (sets up listener)
-  input: object, // Configuration for the source
-})
-```
-
-### `pikkuTriggerFunc<TInput, TEvent>`
-
-Define a trigger source function. Returns a cleanup function.
-
-```typescript
-import { pikkuTriggerFunc } from '#pikku'
-
-const source = pikkuTriggerFunc<
-  InputType, // Configuration input
-  EventType // Shape of events it emits
->(async (services, input, { trigger }) => {
-  // Set up listener...
-  trigger.invoke(eventData) // Fire the trigger
-
-  // Return cleanup function
-  return async () => {
-    /* teardown */
-  }
-})
-```
-
-## Usage Patterns
-
-### Redis Pub/Sub Source
-
-```typescript
-const redisSubscribe = pikkuTriggerFunc<
-  { channels: string[] },
-  { channel: string; message: any }
->(async ({ redis }, { channels }, { trigger }) => {
-  const subscriber = redis.duplicate()
-
-  subscriber.on('message', (channel, message) => {
-    trigger.invoke({ channel, message: JSON.parse(message) })
-  })
-
-  await subscriber.subscribe(...channels)
-
-  return async () => {
-    await subscriber.unsubscribe()
-    await subscriber.quit()
-  }
-})
-
-// Target function
-const onOrderEvent = pikkuSessionlessFunc({
-  title: 'On Order Event',
-  func: async ({ db, logger }, { channel, message }) => {
-    logger.info(`Order event on ${channel}`, message)
-    await db.processOrderEvent(message)
-  },
-})
-
-// Wire them together
-wireTrigger({
-  name: 'order-events',
-  func: onOrderEvent,
-})
-
-wireTriggerSource({
-  name: 'order-events',
-  func: redisSubscribe,
-  input: { channels: ['orders:created', 'orders:updated'] },
-})
-```
-
-### Triggers vs Queues
-
-| Feature     | Trigger                            | Queue                          |
-| ----------- | ---------------------------------- | ------------------------------ |
-| Execution   | Synchronous, in-process            | Async, distributed             |
-| Reliability | At-most-once                       | At-least-once (with retries)   |
-| Use case    | React to events immediately        | Reliable background processing |
-| Source      | External systems (Redis, PG, etc.) | Enqueued programmatically      |
-
-Use triggers for real-time reactions. Use queues for reliable, retryable background work.
-
-## Complete Example
-
-```typescript
-// functions/triggers.functions.ts
-const pgListen = pikkuTriggerFunc<{ channel: string }, { payload: any }>(
-  async ({ db }, { channel }, { trigger }) => {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(channel)) {
-      throw new Error(`Invalid channel name: ${channel}`)
-    }
-    const client = await db.pool.connect()
-
-    client.on('notification', (msg) => {
-      trigger.invoke({ payload: JSON.parse(msg.payload) })
-    })
-
-    await client.query(`LISTEN ${channel}`)
-
-    return async () => {
-      await client.query(`UNLISTEN ${channel}`)
-      client.release()
-    }
-  }
-)
-
-const onUserCreated = pikkuSessionlessFunc({
-  title: 'On User Created',
-  func: async ({ emailService, logger }, { payload }) => {
-    logger.info('New user created', { userId: payload.id })
-    await emailService.sendWelcome(payload.email)
-  },
-})
-
-// wirings/triggers.wiring.ts
-wireTrigger({ name: 'user-created', func: onUserCreated })
-wireTriggerSource({
-  name: 'user-created',
-  func: pgListen,
-  input: { channel: 'user_created' },
-})
-```

package/skills/pikku-versioning/SKILL.md

@@ -1,173 +0,0 @@
----
-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).
-installGroups: [core]
----
-
-# Pikku Function Versioning
-
-## 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.
-
-Track and protect function contracts across releases. Pikku hashes each function's input/output schema into a manifest so you can detect breaking changes before they ship.
-
-## Before You Start
-
-```bash
-pikku info functions --verbose   # See existing functions and their versions
-```
-
-See `pikku-concepts` for the core mental model.
-
-## Function Versioning
-
-When you need to introduce a breaking change, keep the old function as a pinned version and let the new one become the latest.
-
-**The pattern:**
-
-1. Create a new file `my-function-v1.function.ts` — export a variable with the `V1` suffix
-2. Set `override: 'myFunction'` — this is the contract key the manifest groups under
-3. Set `version: 1` — pins this as version 1 of the contract
-4. The existing `my-function.function.ts` (no `version:` field) automatically becomes the latest version
-
-```typescript
-// my-function-v1.function.ts — old contract, kept for running workflows/agents
-export const getBookV1 = pikkuFunc({
-  override: 'getBook', // REQUIRED — links this to the 'getBook' contract family
-  version: 1,
-  input: z.object({ bookId: z.string() }),
-  output: z.object({ title: z.string() }),
-  func: async ({ db }, { bookId }) => {
-    return db.getBook(bookId)
-  },
-})
-
-// my-function.function.ts — latest contract, no version: field
-export const getBook = pikkuFunc({
-  input: z.object({
-    bookId: z.string(),
-    format: z.enum(['full', 'summary']),
-  }),
-  output: z.object({
-    title: z.string(),
-    author: z.string(),
-    isbn: z.string(),
-  }),
-  func: async ({ db }, { bookId, format }) => {
-    return db.getBook(bookId, format)
-  },
-})
-```
-
-**Why `override` is required:** The manifest groups functions by a shared contract key. Without `override: 'getBook'`, `getBookV1` is stored internally as `getBookV1@v1` (key: `getBookV1`), which is a different contract family from `getBook`. With `override: 'getBook'`, it becomes `getBook@v1` (key: `getBook`), which groups with the unversioned `getBook` — and the unversioned one is automatically promoted to `getBook@v2`.
-
-## Version Manifest (`versions.pikku.json`)
-
-Pikku tracks contract hashes to detect breaking changes:
-
-```json
-{
-  "manifestVersion": 1,
-  "contracts": {
-    "createTodo": {
-      "latest": 1,
-      "versions": {
-        "1": { "inputHash": "a1b2c3d4", "outputHash": "e5f6a7b8" }
-      }
-    },
-    "getTodos": {
-      "latest": 2,
-      "versions": {
-        "1": { "inputHash": "i9j0k1l2", "outputHash": "m3n4o5p6" },
-        "2": { "inputHash": "q7r8s9t0", "outputHash": "u1v2w3x4" }
-      }
-    }
-  }
-}
-```
-
-Each hash is derived from the function's input and output schemas plus the contract key. If a schema changes without a version bump, `pikku versions check` will fail.
-
-## CLI Commands
-
-```bash
-npx pikku versions init     # Initialize versioning manifest (run once)
-npx pikku versions check    # Detect contract changes (use in CI)
-npx pikku versions update   # Update contract hashes after version bump
-```
-
-**Workflow:**
-
-1. `pikku versions init` — run once to create `versions.pikku.json`
-2. Develop normally — add/modify functions
-3. `pikku versions check` — CI catches unversioned breaking changes
-4. If intentional: create `my-function-v1.function.ts` with `override` + `version: 1`, then `pikku versions update`
-
-## CI Integration
-
-```yaml
-# .github/workflows/ci.yml
-name: CI
-on: [push, pull_request]
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm ci
-      - run: npx pikku versions check
-```
-
-## Complete Example
-
-```typescript
-// create-todo-v1.function.ts — v1 locked contract
-export const createTodoV1 = pikkuSessionlessFunc({
-  override: 'createTodo', // groups under 'createTodo' contract family
-  version: 1,
-  input: z.object({ title: z.string() }),
-  output: z.object({ id: z.string(), title: z.string() }),
-  func: async ({ todoStore }, { title }) => todoStore.add(title),
-})
-
-// create-todo.function.ts — v2 (latest), called by default
-export const createTodo = pikkuSessionlessFunc({
-  input: z.object({
-    title: z.string(),
-    priority: z.enum(['low', 'medium', 'high']),
-  }),
-  output: z.object({
-    id: z.string(),
-    title: z.string(),
-    priority: z.string(),
-  }),
-  func: async ({ todoStore }, { title, priority }) =>
-    todoStore.add(title, priority),
-})
-```
-
-Result in manifest:
-
-```json
-"createTodo": {
-  "latest": 2,
-  "versions": {
-    "1": { "inputHash": "...", "outputHash": "..." },
-    "2": { "inputHash": "...", "outputHash": "..." }
-  }
-}
-```