@pikku/skills 0.12.35 → 0.12.38

package/dist/snippets.d.ts

@@ -0,0 +1,26 @@
+export declare class UnclosedSnippetError extends Error {
+    constructor(name: string, file: string);
+}
+export declare class DuplicateSnippetError extends Error {
+    constructor(name: string, file: string, other: string);
+}
+export declare class MissingSnippetError extends Error {
+    constructor(name: string, file: string);
+}
+/**
+ * The `// @snippet start <name>` regions in a project's source, so an example
+ * in a doc comment can name one instead of restating it. The same mechanism the
+ * website uses to pull its code blocks out of the shop template: the code that
+ * reaches the reader is the code that compiles, and it cannot drift.
+ */
+export declare const collectSnippets: (projectDir: string, into?: Map<string, string>, origins?: Map<string, string>) => Promise<Map<string, string>>;
+export type Snippets = Record<string, string> | Map<string, string>;
+/** Every region a markdown document shows, in order. */
+export declare const snippetRegionsIn: (markdown: string) => string[];
+/**
+ * A skill's text with every marked fence replaced by its region's code. Used
+ * twice, deliberately: `scripts/embed.ts` bakes the result into the manifest
+ * that ships inside the CLI binary, and `readSkillFile` applies it to a
+ * filesystem copy so an installed package shows the same code the binary does.
+ */
+export declare const expandSkillMarkdown: (markdown: string, snippets: Snippets, file?: string) => string;

package/dist/snippets.js

@@ -0,0 +1,148 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+const START = /^\s*(?:\/\/|--)\s*@snippet start (\S+)\s*$/;
+const END = /^\s*(?:\/\/|--)\s*@snippet end (\S+)\s*$/;
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.sql'];
+const SKIPPED_DIRECTORIES = new Set(['node_modules', '.pikku', 'dist', '.git']);
+export class UnclosedSnippetError extends Error {
+    constructor(name, file) {
+        super(`The snippet "${name}" opens in ${file} and never closes. Add "// @snippet end ${name}".`);
+        this.name = 'UnclosedSnippetError';
+    }
+}
+export class DuplicateSnippetError extends Error {
+    constructor(name, file, other) {
+        super(`The snippet "${name}" is defined twice, in ${other} and ${file}. Snippet names are the reference an example uses, so they have to be unique.`);
+        this.name = 'DuplicateSnippetError';
+    }
+}
+export class MissingSnippetError extends Error {
+    constructor(name, file) {
+        super(`${file} shows the snippet "${name}", which no @snippet region defines. ` +
+            `Add "// @snippet start ${name}" to a compiled example project, or fix the fence.`);
+        this.name = 'MissingSnippetError';
+    }
+}
+const dedent = (lines) => {
+    const indents = lines
+        .filter((line) => line.trim().length > 0)
+        .map((line) => line.length - line.trimStart().length);
+    const shortest = indents.length > 0 ? Math.min(...indents) : 0;
+    return lines
+        .map((line) => line.slice(shortest))
+        .join('\n')
+        .trim();
+};
+const sourceFilesIn = async (directory, found = []) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const full = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIPPED_DIRECTORIES.has(entry.name) || entry.name.startsWith('.')) {
+                continue;
+            }
+            await sourceFilesIn(full, found);
+        }
+        else if (SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+            found.push(full);
+        }
+    }
+    return found;
+};
+/**
+ * The `// @snippet start <name>` regions in a project's source, so an example
+ * in a doc comment can name one instead of restating it. The same mechanism the
+ * website uses to pull its code blocks out of the shop template: the code that
+ * reaches the reader is the code that compiles, and it cannot drift.
+ */
+export const collectSnippets = async (projectDir, into = new Map(), origins = new Map()) => {
+    for (const file of await sourceFilesIn(projectDir)) {
+        const where = relative(projectDir, file);
+        const lines = (await readFile(file, 'utf8')).split('\n');
+        const open = new Map();
+        for (const line of lines) {
+            const end = line.match(END);
+            if (end?.[1] && open.has(end[1])) {
+                const name = end[1];
+                const existing = origins.get(name);
+                if (existing)
+                    throw new DuplicateSnippetError(name, where, existing);
+                into.set(name, dedent(open.get(name)));
+                origins.set(name, where);
+                open.delete(name);
+                continue;
+            }
+            const start = line.match(START);
+            if (start?.[1]) {
+                if (!open.has(start[1]))
+                    open.set(start[1], []);
+                continue;
+            }
+            if (end)
+                continue;
+            for (const body of open.values())
+                body.push(line);
+        }
+        const [unclosed] = open.keys();
+        if (unclosed)
+            throw new UnclosedSnippetError(unclosed, where);
+    }
+    return into;
+};
+/**
+ * A fence that names a region instead of carrying code:
+ *
+ * ```ts snippet:definePersonas
+ * ```
+ *
+ * The language is optional and kept. Marked fences are replaced whole — both
+ * the placeholder form and a filled-in block, so a skill can be migrated
+ * without hand-deleting the old copy.
+ */
+const SNIPPET_FENCE = /^(\s*)```(\S*)\s+snippet:([A-Za-z0-9_.-]+)\s*$/;
+const CLOSING_FENCE = /^\s*```\s*$/;
+const replace = (markdown, lookup) => {
+    const lines = markdown.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.match(SNIPPET_FENCE);
+        if (!match) {
+            out.push(line);
+            continue;
+        }
+        const indent = match[1] ?? '';
+        const lang = match[2] ?? '';
+        const region = match[3];
+        const body = lookup(region);
+        out.push(`${indent}\`\`\`${lang}`);
+        for (const bodyLine of body.split('\n')) {
+            out.push(bodyLine.length > 0 ? indent + bodyLine : '');
+        }
+        out.push(`${indent}\`\`\``);
+        while (i + 1 < lines.length && !CLOSING_FENCE.test(lines[i + 1]))
+            i++;
+        i++;
+    }
+    return out.join('\n');
+};
+/** Every region a markdown document shows, in order. */
+export const snippetRegionsIn = (markdown) => markdown
+    .split('\n')
+    .map((line) => line.match(SNIPPET_FENCE))
+    .filter((match) => match !== null)
+    .map((match) => match[3]);
+/**
+ * A skill's text with every marked fence replaced by its region's code. Used
+ * twice, deliberately: `scripts/embed.ts` bakes the result into the manifest
+ * that ships inside the CLI binary, and `readSkillFile` applies it to a
+ * filesystem copy so an installed package shows the same code the binary does.
+ */
+export const expandSkillMarkdown = (markdown, snippets, file = 'skill') => {
+    const lookup = (name) => {
+        const body = snippets instanceof Map ? snippets.get(name) : snippets[name];
+        if (body === undefined)
+            throw new MissingSnippetError(name, file);
+        return body;
+    };
+    return replace(markdown, lookup);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.35",
+  "version": "0.12.38",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -14,7 +14,7 @@
   "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "embed": "node scripts/embed.mjs",
+    "embed": "bun run scripts/embed.ts",
     "tsc": "bun run embed && tsc",
     "build": "bun run embed && tsc -b",
     "ncu": "npx npm-check-updates",

package/skills/pikku-addon/SKILL.md

@@ -3,8 +3,10 @@ name: pikku-addon
 description: >-
   Use when creating or consuming reusable function packages (addons) in Pikku. Covers wireAddon,
   ref(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, addons that ship
-  database tables (pikku db export), and cross-project function sharing. TRIGGER when: code uses wireAddon/ref()/pikkuAddonServices, user asks about
-  addons, reusable function packages, cross-project sharing, or addon package structure. DO NOT
+  database tables (pikku db export), generating an addon from an OpenAPI/Swagger spec, and
+  cross-project function sharing. TRIGGER when: code uses wireAddon/ref()/pikkuAddonServices, user
+  asks about addons, reusable function packages, cross-project sharing, or addon package structure,
+  or the user hands over an OpenAPI/Swagger spec (file or URL) to build on. DO NOT
   TRIGGER when: user asks about internal function composition (use pikku-wiring) or general function
   definitions (use pikku-concepts).
 installGroups: [core]
@@ -19,7 +21,7 @@ Use this skill as an execution checklist, not reference material.
 1. Discover before editing. 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.
+4. Validate with the narrowest relevant command first, then run `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.
 
 Addons are reusable Pikku function packages that can be shared across projects. They bundle functions, services, secrets, and variables into a self-contained NPM package.
@@ -48,6 +50,7 @@ wireAddon({
   rpcEndpoint?: string,            // Optional remote RPC endpoint for distributed execution
   auth?: boolean,                  // Require a session for every function in the addon
   mcp?: boolean | string[],        // true: every function the addon declared mcp: true; a list: the tools this app offers, typed against the addon's function names
+  expose?: boolean | string[],     // what rpc.exposed / POST /rpc may reach: unset/true = the addon's own expose: true, false = none, a list = exactly those (typed; PKU343 on unknown names)
   tags?: string[],                 // Tags applied to all addon functions
   scopes?: string[],               // Required of every function, on top of its own
   secretOverrides?: Record<string, string>,      // Remap secret names (and grant them)
@@ -146,7 +149,7 @@ second argument is always present — an addon never falls back to its own logge
 variables or secrets; the consuming app supplies them:
 
 ```typescript
-import { pikkuAddonServices } from '#pikku/setup'
+import { pikkuAddonServices } from '#pikku/addon/setup'
 
 export const createSingletonServices = pikkuAddonServices(
   async (config, { secrets, logger }) => {
@@ -167,7 +170,7 @@ config object.
 Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
 
 ```typescript
-import { pikkuAddonWireServices } from '#pikku/setup'
+import { pikkuAddonWireServices } from '#pikku/addon/setup'
 
 export const createWireServices = pikkuAddonWireServices(
   async (singletonServices, wire) => {
@@ -189,13 +192,17 @@ npx pikku new addon <name>          # name is a required positional
 npx pikku new addon stripe --display-name Stripe --category Payments --dir addons
 ```
 
+**Handed an OpenAPI or Swagger spec?** Don't hand-write the functions —
+`pikku new addon <name> --openapi <spec>` generates one function per operation,
+with its schemas, service and credential. Read `references/openapi.md`.
+
 This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json` (`addon: true`), `tsconfig.json` (`#pikku` path mapping), `src/services.ts`, `src/functions/`, and `types/application-types.d.ts`. For the full file contents/exports you rarely hand-edit, read `references/addon-package-manifest.md`.
 
 ### Services
 
 ```typescript
 // src/services.ts
-import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/setup'
+import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/addon/setup'
 import { TodoStore } from './todo-store.service.js'
 
 export const createSingletonServices = pikkuAddonServices(async () => {
@@ -213,18 +220,30 @@ export const createWireServices = pikkuAddonWireServices(
 
 ### Functions
 
-An addon's generated tree roots at `.pikku/addon/`, but its `imports` map points
-`#pikku/*` there, so it authors against the same subpaths an application does —
-`#pikku/function`, `#pikku/http`. The `addon` segment is the package's own
-business, never part of a specifier.
+An addon's generated tree roots at `.pikku/addon/`, and its own source reaches
+it by that path — `#pikku/addon/function`, `#pikku/addon/setup`. An application
+authors against `#pikku/function`; an addon never does, because inside the addon
+`#pikku/function` names a leaf that does not exist.
+
+**Declare zod schemas in a file that never imports `#pikku`.** `pikku all` loads
+the file that declares each schema to convert it, and at runtime `#pikku`
+resolves through the package's `imports` — into a `dist` the first build has not
+written yet. Inline, every schema fails with `Could not convert Zod schema …
+Cannot find module …/dist/.pikku/…` and the addon never builds from clean. A
+sibling `<fn>.schemas.ts` is what `--openapi` generates:
 
 ```typescript
-// src/functions/addTodo.function.ts
+// src/functions/addTodo.schemas.ts
 import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku/function'
 
-const AddTodoInput = z.object({ title: z.string() })
-const AddTodoOutput = z.object({ id: z.string(), title: z.string() })
+export const AddTodoInput = z.object({ title: z.string() })
+export const AddTodoOutput = z.object({ id: z.string(), title: z.string() })
+```
+
+```typescript
+// src/functions/addTodo.function.ts
+import { pikkuSessionlessFunc } from '#pikku/addon/function'
+import { AddTodoInput, AddTodoOutput } from './addTodo.schemas.js'
 
 export const addTodo = pikkuSessionlessFunc({
   description: 'Adds a new todo',
@@ -246,9 +265,7 @@ approvalDescription: async (_services, { title }) => `Add a todo called "${title
 ### Build
 
 ```bash
-yarn pikku all          # Generate types
-yarn tsc                # Compile TypeScript
-cp -r .pikku types dist/  # Ship the generated files and the types they import
+yarn build              # prebuild: pikku all, then tsc && pikku dist
 yarn pikku validate     # Check the published file set holds together
 ```
 
@@ -257,12 +274,11 @@ devDependency, and building it against a different CLI than it declares is how
 generated output ends up disagreeing with the packaged one. `npx pikku new
 addon` above is the exception — it runs before the addon, and its CLI, exist.
 
-`types/` has to be copied alongside `.pikku`: the generated files import
-`SingletonServices`, `Services`, `Config` and `UserSession` from
-`../../types/application-types.d.js`, and `tsc` never emits a hand-written
-`.d.ts` to `outDir`, so nothing else puts it in `dist`. Leave it out and the
-addon installs fine and fails to typecheck in every app that depends on it —
-which is what `pikku validate` is there to catch before you publish.
+`pikku dist` copies what `tsc` cannot emit — the generated `*.gen.json` meta and
+the hand-written `types/*.d.ts` the generated files import — to where `tsc` put
+everything else. Leave it out and the addon installs fine and fails to typecheck
+in every app that depends on it, which is what `pikku validate` is there to
+catch before you publish.
 
 ### Database tables
 
@@ -297,7 +313,7 @@ packed, or it never arrives:
 **An unresolvable artifact stops `db generate`.** Because the file is
 unconditional, absence means the package cannot say whether it ships tables —
 either it was built with an older CLI, or `exports`/`files` do not carry it. The
-error names both causes. An addon with genuinely no tables is *not* this case:
+error names both causes. An addon with genuinely no tables is _not_ this case:
 it publishes `{}` and is waved through.
 
 Two more loud ones: a malformed artifact (missing the SQL for a dialect it
@@ -343,6 +359,36 @@ export const myFunc = pikkuFunc({
 })
 ```
 
+### Wrap an addon function only to reshape it
+
+A screen that shows the addon's data as the addon returns it calls the addon
+function itself: name it in `wireAddon({ expose: ['listTodos'], auth: true })`
+and the frontend calls `rpc.invoke('todos:listTodos', …)` (over HTTP,
+`POST /rpc/todos:listTodos` with `{ "data": … }`), still behind the session.
+Use `ref('todos:listTodos')` on an HTTP or MCP wiring only when the addon needs
+a route of its own. Don't write an app function that calls `rpc.invoke` and
+returns the result unchanged: it's a second name and a second schema for the
+same thing, and it drifts. `expose: true` exposes only what the addon itself
+declared `expose: true` — an OpenAPI-generated addon declares none, so list
+the names.
+
+Write your own function when the app needs the data narrowed, typed, or
+combined (a flag the upstream sends as `"0"`, a total summed from several
+calls, one field out of fifty), or when the app adds a permission of its own.
+`wireAddon`'s `scopes` gate every function in the addon at once, and a wiring
+carries middleware, not permissions, so a rule on one addon function lives in
+the `permissions` of an app function that calls it. An addon called with the
+user's own credential is already limited upstream to what that user may do, so
+a data-aware `pikkuPermission` repeating that check (may they read *this*
+invoice?) adds nothing. A session-only `pikkuAuth` (a role, a tier) is still
+worth it: it can be checked before any input exists, so the functions a user
+can't call drop out of the tools an MCP client, an agent or a workflow is
+offered, instead of failing upstream when called. Name it for what the screen means
+(`getMyProfile`), not after the upstream operation (`usersRetrieveInfo`), and
+give it an `output:` schema of only what the app uses. For an OpenAPI-generated
+addon this matters more: its outputs mirror the upstream's loose, oversized
+payloads, and the wrapper is where they become the app's own shape.
+
 ### Wire to HTTP
 
 ```typescript

package/skills/pikku-addon/references/addon-package-manifest.md

@@ -22,7 +22,7 @@ An addon's generated tree roots one level down, at `.pikku/addon/`, so its own
 leaves are reached as `#pikku/addon/<leaf>` while an application's are
 `#pikku/<leaf>`. `paths` are global to a tsx process rather than scoped to the
 package that declared them, and the extra segment is what stops a linked addon's
-`#pikku/function` from matching the *host application's* flat leaf.
+`#pikku/function` from matching the _host application's_ flat leaf.
 
 ## pikku.config.json
 
@@ -68,20 +68,25 @@ package that declared them, and the extra segment is what stops a linked addon's
   "scripts": {
     "prebuild": "pikku all",
     "pikku": "pikku all",
-    "build": "tsc && cp -r .pikku types dist/"
+    "build": "tsc && pikku dist"
   }
 }
 ```
 
 **`imports` names `dist`, never the source tree.** `files: ["dist"]` is the whole
-published package, and `build` copies `.pikku` and `types` into it — so a
+published package, and `pikku dist` copies `.pikku` and `types` into it — so a
 `#pikku/*` target under `./.pikku/` resolves for the author and for nobody else.
 It is a silent break: the addon compiles, packs, installs and then throws
 `Cannot find module '.../.pikku/addon/function/index.ts'` on first import in the
-consuming app, out of a file the consumer never wrote. The addon's own build
+consuming app, out of a file the consumer never wrote. The addon's own `tsc`
 does not read `imports` at all — tsconfig `paths` covers it, which is why the
 two maps point at different trees.
 
+`pikku all` does read `imports`, though: it loads each file that declares a zod
+schema to convert it to JSON Schema, and at runtime `#pikku` resolves through
+`imports`, into a `dist` the first build has not written yet. So a schema must
+live in a file that never imports `#pikku` — see "Functions" in the skill.
+
 **`exports` targets carry the `addon` segment; the subpaths do not.** A consumer
 writes `@my-org/addon-todos/.pikku/rpc/...`, exactly as it would in an
 application, and the leaf stays the package's own business.

package/skills/pikku-addon/references/openapi.md

@@ -0,0 +1,130 @@
+# An addon from an OpenAPI spec
+
+When you are handed an OpenAPI or Swagger spec — a file, or a URL to one — the
+API it describes becomes an addon: one function per operation, each with its
+input and output schemas, behind one service that makes the HTTP calls. Say so
+before starting ("This is an OpenAPI spec — I'll turn it into an addon first"),
+then generate it. Don't hand-write the functions, and don't ask which
+operations to keep: generate the whole spec, however large.
+
+## Recognising one
+
+A JSON or YAML document with a top-level `openapi` key (3.x) or `swagger` key
+(2.0), and a `paths` object. A URL ending in `openapi.json`, `swagger.json` or
+`.yaml` is almost always one; open it and check the key before generating.
+
+## 1 — Look at the spec first
+
+`--openapi` takes a path or a URL. A spec published only to signed-in callers
+takes the key the way the API reads it: `--openapi-header "NAME: value"`
+(repeatable), or in the URL's query string when the API reads it there
+(Dolibarr's explorer takes `?DOLAPIKEY=`). A 401 while fetching says which.
+
+The generator warns loudly when the spec has fewer than five operations, or only
+auth routes. That is almost always the public half of a spec that shows more
+to an authenticated caller — fetch it again with the key, don't build on it.
+
+Keep a copy in `specs/` as the record of what the addon was generated from.
+
+## 2 — Generate, from the app's root
+
+```bash
+bunx --bun pikku new addon <name> --openapi <path-or-url>
+```
+
+One command. Inside an app it writes `packages/addon-<name>` as
+`@pikku/addon-<name>`, then installs it into the app:
+
+- the dependency in the root and the functions `package.json`
+- `src/addons/<name>.addon.ts` — `wireAddon` with `auth: true` and an explicit
+  `expose` list (every operation in per-user modes, only the `GET`s behind a
+  shared secret)
+- the auth wiring in `src/auth.ts` for the chosen mode
+- `<NAME>_BASE_URL` in `.env`
+
+and then runs install and the addon's build. `--no-install` generates the
+package alone.
+
+| Flag                                         | When                                                                             |
+| -------------------------------------------- | -------------------------------------------------------------------------------- |
+| `--auth user` (default)                      | Each user brings their own credential                                            |
+| `--auth shared`                              | One secret behind every user; locally it goes in `.env`                          |
+| `--auth none`                                | The API really takes no auth                                                     |
+| `--credential apikey\|bearer\|basic\|oauth2` | Override what the spec's `securitySchemes` declares                              |
+| `--auth-config <file>`                       | Users sign in with their upstream login, or the spec gets auth wrong             |
+| `--tags a,b` / `--include` / `--exclude`     | Keep part of a huge spec: tags, or globs on operationId, `/path`, `METHOD /path` |
+| `--mcp`                                      | The operations should also be MCP tools                                          |
+| `--camel-case`                               | The API's property names are snake_case and the app's are not                    |
+
+The mode comes from the spec unless a flag says otherwise. A spec with no
+machine-readable auth is refused rather than guessed: pass one of the flags the
+error names. Which mode fits, and the auth-config format, are in the
+`pikku-build` skill's `references/openapi.md`.
+
+## 3 — Check what was generated
+
+```
+packages/addon-<name>/
+├── <name>.svg                    # placeholder icon; replace with the real one
+├── src/<name>-api.service.ts     # one fetch wrapper, reads <NAME>_BASE_URL
+├── src/<name>.variable.ts        # <NAME>_BASE_URL: z.string().url(), the first server as default
+├── src/functions/<op>.function.ts
+├── src/functions/<op>.schemas.ts # the op's zod schemas — never import #pikku here
+└── src/index.ts                  # re-exports every function
+```
+
+An operation whose spec gives no response, or one too vague to validate
+against, outputs `z.unknown()`. Tighten it in `<op>.schemas.ts` once §6 shows
+what the API really returns.
+
+An upstream 401 on a per-user credential throws `CredentialRejectedError`
+(403, `reauth: 'sign-in' | 'connect'`); a UI shows the matching screen again
+rather than a generic error.
+
+## 4 — Call it from the app
+
+Operations are reached by reference — `ref('<name>:<operationFn>')` in a
+workflow, agent tool or HTTP wiring — the same way as any other addon. See
+"Consuming an Addon" in the skill. An exposed operation is also callable from
+the frontend at `POST /rpc/<name>:<operationFn>` with a body of
+`{ "data": { … } }`, as the signed-in user.
+
+## 5 — Verify
+
+```bash
+bunx --bun pikku all
+bunx --bun pikku validate
+```
+
+`Could not convert Zod schema … Cannot find module …/dist/.pikku/…` means a
+schema is declared in a file that imports `#pikku`. The generator never does
+that, so a hand edit moved it — put it back in `<op>.schemas.ts`.
+
+`pikku validate` reports a `skewed-type-identity` error (and `pikku all` warns
+`[PKU719]`) when the CLI and the app resolve different copies of `zod` or
+another shared package. Codegen then reads the app's
+schemas with the wrong copy and fails on schemas that are correct. Pin one
+version for the whole install, as the finding says, and reinstall.
+
+## 6 — Check the spec against the real API
+
+Specs are often wrong, and the generated schemas repeat every mistake. Before
+building on the addon:
+
+- **Call the reads you can.** The `GET`s the credential can reach, following ids
+  from lists into retrieves. Writes only if the user opts in.
+- **Fix the addon, not the app**: the schema in the op's `<op>.schemas.ts`, or the
+  request shape in `src/<name>-api.service.ts`. Then rebuild it.
+- **List each mismatch in `packages/addon-<name>/SPEC-ISSUES.md`**: a title and a
+  short description. No credentials or customer data.
+
+Then tell the user in one line: "FYI, the spec deviates from the real API in
+N ways: [SPEC-ISSUES.md](…)". Add to the file whenever a later call disagrees
+with its schema. Ask before sending it to the API's maintainers, because an issue
+on their tracker is a public post.
+
+## Then
+
+Go back to the mode you were building in (`pikku-build`). The addon is a
+dependency of the app, not the app: plan milestones around what the user wants
+to do with the API, and reach the operations through `ref()`.

package/skills/pikku-agent/references/agents.md

@@ -35,7 +35,9 @@ pikkuAgent({
   temperature?: number,
   providerOptions?: {            // passed through untouched, keyed by provider
     openai?: { reasoningEffort?: 'minimal' | ... },
-  },
+  },                             // inline literals only — a computed value
+                                 // cannot be read into the generated metadata
+                                 // and is reported as PKU156
 
   // --- capabilities: all three take ref() handles, not imported values ---
   tools?: unknown[],             // ref('todos:addTodo'), ref('graph:sleep'), …

package/skills/pikku-auth/references/better-auth.md

@@ -1,5 +1,21 @@
 # Pikku Better Auth Integration
 
+Every section, in the order it is usually needed:
+
+- [⚠️ MANDATORY RULE — READ FIRST](#mandatory-rule--read-first)
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [Standard Setup](#standard-setup)
+- [⚠️ Stateless session — ALWAYS enable `cookieCache` for deployed apps](#stateless-session--always-enable-cookiecache-for-deployed-apps)
+- [Social Providers needing extra config](#social-providers-needing-extra-config)
+- [Auth-Protected Functions](#auth-protected-functions)
+- [HTTP surface (call the real endpoints)](#http-surface-call-the-real-endpoints)
+- [Secret Management](#secret-management)
+- [`pikkuBetterAuth` API](#pikkubetterauth-api)
+- [Post-signup side effects](#post-signup-side-effects)
+- [Two-factor (2FA / MFA)](#two-factor-2fa--mfa)
+- [Security hardening](#security-hardening)
+
 ## ⚠️ MANDATORY RULE — READ FIRST
 
 **ALL authentication in Pikku apps MUST use `@pikku/better-auth`. No exceptions.**
@@ -291,7 +307,7 @@ singleton a 403 that leaves no platform user behind.
 
 ```typescript
 pikkuDelegatedAuth({
-  authenticate: async ({ email, password, apiKey }) => upstream.login(...),
+  authenticate: async ({ login, email, password, apiKey }) => upstream.login(...),
   storeCredential: (userId, identity) =>
     credentialService.set('acme', identity.credential, userId),
   defaultRole: 'member',
@@ -302,7 +318,10 @@ pikkuDelegatedAuth({
 ```
 
 `POST /sign-in/delegated` forwards the credentials the user already has to
-`authenticate`. On success it JIT-provisions a real user row (email-keyed and
+`authenticate`. The body takes `email`, `login` or `username` with `password`
+(or `apiKey`); whichever identifier was sent reaches `authenticate` as
+`credentials.login`, and `email` as well when it was one. Upstreams that sign in
+with a username — most ERPs — need nothing more. On success it JIT-provisions a real user row (email-keyed and
 `emailVerified` — the upstream just verified them), links it via an `account`
 row (`providerId: 'delegated'`, `accountId: externalId`), persists the upstream
 token **before** minting the session, and returns a normal session cookie.
@@ -317,6 +336,18 @@ a warning and the user still gets in.
 `storeCredential` failing, by contrast, **fails the sign-in**: every proxied
 call would be dead anyway.
 
+An upstream user with no email gets one made up from the login, and the
+identity says so with `syntheticEmail: true`. A made-up address never links to
+an existing user row, so it cannot take over someone else's account.
+
+For an addon generated from an OpenAPI spec, none of this is written by hand:
+`pikku new addon --openapi … --auth-config <file>` generates
+`authenticate<Name>Upstream` in the addon and wires this plugin, the stored
+credential and the actor credentials into `src/auth.ts`. The config format is
+in the `pikku-build` skill's `references/openapi.md`. When the upstream later
+refuses the stored token, the addon throws `CredentialRejectedError` (403,
+`reauth: 'sign-in'`): the UI shows the sign-in again.
+
 #### `pikkuFabric()` — control-plane operator sign-in
 
 ```typescript