@pikku/skills 0.12.35 → 0.12.37

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.37",
   "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

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,99 @@
+# 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 — Put the spec in the repo
+
+`--openapi` reads a local path, not a URL. Download it to `specs/`, where it
+stays as the record of what the addon was generated from:
+
+```bash
+mkdir -p specs
+curl -fsSL <url> -o specs/<name>.openapi.json
+```
+
+## 2 — Generate
+
+Inside an app, the addon is a workspace package under `packages/`:
+
+```bash
+bunx --bun pikku new addon <name> --openapi specs/<name>.openapi.json --dir packages
+```
+
+This writes `packages/addon-<name>` as `@pikku/addon-<name>`, installs it and
+builds it. Inside a workspace the generated test app depends on it as
+`workspace:*`, so nothing is published.
+
+| Flag                          | When                                                                                      |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `--credential apikey\|bearer` | The spec's `securitySchemes` is an API key or a bearer token — each user brings their own |
+| `--credential oauth2`         | The spec's `securitySchemes` is OAuth2                                                    |
+| `--auth-config <file>`        | The spec gets auth wrong or leaves it out: a custom header, a delegated login endpoint    |
+| `--mcp`                       | The operations should also be MCP tools                                                   |
+| `--camel-case`                | The API's property names are snake_case and the app's are not                             |
+
+Read the spec's `securitySchemes` to pick the credential. Leave the flag off
+only when the API really takes no auth.
+
+## 3 — Check what was generated
+
+```
+packages/addon-<name>/
+├── src/<name>-api.service.ts     # one fetch wrapper, reads <NAME>_BASE_URL
+├── src/<name>.variable.ts        # <NAME>_BASE_URL, an enum of the spec's servers
+├── 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
+```
+
+`<NAME>_BASE_URL` is an enum of the spec's `servers`. When those are
+placeholders or a per-tenant host (`https://{tenant}.example.com`, or a server
+list that is only an example), change its schema in `src/<name>.variable.ts`
+to `z.string().url()` so each deployment sets its own.
+
+## 4 — Wire it into the app
+
+```typescript
+// src/addons.ts
+import { wireAddon } from '#pikku/addon'
+
+wireAddon({ name: '<name>', package: '@pikku/addon-<name>' })
+```
+
+Then call operations 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.
+
+## 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.
+
+## 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.**

package/skills/pikku-build/SKILL.md

@@ -24,7 +24,6 @@ agent:
         command: pikku knowledge validate
       - id: typechecks
         command: pikku all --tsc-summary
-
 ---
 
 # Build on Pikku
@@ -63,6 +62,24 @@ generated code depends on, and on a fresh scaffold **every command that touches
 codegen fails until it has run**, including ones you would reasonably reach for
 while still planning. Those failures look alarming and are nothing but this.
 
+## Start from what you were handed
+
+When the request comes with a file or a URL, look at it before planning
+anything. Two kinds are converted first and then built on:
+
+| Handed                                                                                                              | Say, then do                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| An **OpenAPI / Swagger spec** — top-level `openapi` or `swagger` key, a `paths` object                              | "This is an OpenAPI spec — I'll turn it into an addon first." Follow the `pikku-addon` skill's OpenAPI reference. |
+| An **n8n export** — an object with `nodes` and `connections`, an array of them, or a `{ workflows: [...] }` wrapper | "This is an n8n workflow — I'll import it first." Follow `pikku-n8n-import`.                                      |
+
+Say it at once, in one line, and start: this is the obvious first move, not a
+question for the user. Generate the whole spec, however large.
+
+Neither is the app. When the conversion compiles, come back here and carry on
+in the mode the request calls for — App by default — planning milestones around
+what the user wants to do with the API or the workflow, and reaching the
+generated functions through `ref()`.
+
 ## What holds in every mode
 
 - **The branch and the diff are the contract.** A reviewer sees real, compiled,

package/skills/pikku-build/references/app.md

@@ -494,6 +494,35 @@ Rules that are not optional:
   render the failure inline next to the control that triggered it — not a toast.
 - An exposed function with no session and no permission is reachable by anyone
   over `POST /rpc/:rpcName` (PKU574). Either gate it or drop `expose: true`.
+- A public, signed-out read (a homepage's programme, a price list) is a
+  `pikkuSessionlessFunc`. `pikkuFunc` with `auth: false` still answers
+  `MissingSessionError` over `/rpc` to a caller with no session.
+- Better Auth already owns the `user`, `session`, `account` and `verification`
+  tables. A domain table with one of those names — a class *session*, a drop-in
+  *session* — collides in the migration. Name it for the domain instead
+  (`evening`, `class_meeting`) and keep the word in the UI copy.
+- The template's `/` redirects to `/app`, so the login screen — and its "Sign in
+  as …" switcher — is what a signed-out visitor sees first. Replace `/` with a
+  public homepage and that stops being true: mount `<DevActorSwitcher />` in the
+  public layout as well, or a reviewer lands on a site with no way in.
+
+Before the first run, make sure `.env` at the project root holds the two
+secrets the local stack needs. `bun run dev` appends whichever is missing, but
+check anyway — a project scaffolded from an older template, or a `.env` copied
+in from elsewhere, can lack one, and neither failure names the variable:
+
+- `BETTER_AUTH_SECRET` — without it the first sign-up is a 500.
+- `SCENARIO_ACTOR_SECRET` — without it `/api/auth/sign-in/actor` is disabled:
+  every scenario fails at sign-in before its first step, and the "Sign in as …"
+  switcher renders nothing.
+
+```sh
+grep -q '^BETTER_AUTH_SECRET=' .env 2>/dev/null || echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env
+grep -q '^SCENARIO_ACTOR_SECRET=' .env 2>/dev/null || echo "SCENARIO_ACTOR_SECRET=$(openssl rand -base64 32)" >> .env
+```
+
+`.env` is gitignored and local only — never commit it. A deployed stage gets its
+secrets from the platform (`pikku fabric secrets`), not from this file.
 
 Then run it:
 
@@ -505,6 +534,19 @@ That starts the API on :3000 and every frontend in `pikkufabric.config.json`. A
 frontend running against a dead API looks exactly like an app bug, so if every
 request fails, check that both halves came up.
 
+**Start the stack through `bun run dev`, not by launching `vite` or `pikku dev`
+yourself.** The dev script reads the personas, derives one credential per
+persona from `SCENARIO_ACTOR_SECRET`, and hands both to the frontend as
+`VITE_DEV_ACTORS` / `VITE_DEV_ACTOR_SECRETS`. Vite reads those once, at boot. A
+frontend started any other way — or restarted by hand later — has an empty
+actor list, and the switcher silently disappears from every page. If you do
+start the frontend on its own (say :3000 is taken by another project), you owe
+it three things: the two `VITE_DEV_*` values the dev script would have computed,
+and `VITE_API_PROXY` pointing at your API — the dev proxy defaults to
+`http://localhost:3000`, so beside another project's server your sign-ins go to
+*its* API and come back `401 Invalid actor secret`, which reads like a bad
+credential rather than the wrong server.
+
 The `--bun` in `bunx --bun pikku …` is load-bearing — keep it. Without it the
 CLI's `#!/usr/bin/env node` shebang hands the process to whatever Node is on
 PATH, which fails below Node 24 with `ERR_UNKNOWN_BUILTIN_MODULE: No such
@@ -614,10 +656,11 @@ export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
 - **Write the refusals.** The third step above is the whole point of §4: one
   persona reaching for another's row has to be rejected, and that rejection is a
   scenario. It is how you prove access control instead of asserting it.
-- **Add `SCENARIO_ACTOR_SECRET` to `.env`.** `bun run dev` generates that file
-  with a `BETTER_AUTH_SECRET` and nothing else, and without the actor secret
-  `/api/auth/sign-in/actor` is disabled — every scenario then fails at sign-in,
-  before its first step, for a reason that reads like an auth bug.
+- **`SCENARIO_ACTOR_SECRET` must be in `.env`** (§6, before the first run).
+  Without it `/api/auth/sign-in/actor` is disabled — every scenario then fails
+  at sign-in, before its first step, for a reason that reads like an auth bug.
+  `pikku scenario run` reads it from the environment, so source `.env` first
+  (`set -a && . ./.env && set +a`) when you run outside `bun run dev`.
 - **There is no state reset.** A scenario runs against a live server: scope what
   you create to your own rows and unique ids, and never assume a clean database.
 
@@ -786,6 +829,11 @@ standalone`, `cloudflare`, `aws`), how to serve several frontends behind one
 API, the pre-release gate to run, and the contract that keeps `pikku fabric init`
 a one-command import later rather than a migration.
 
+The app is not handed over without its user guide. The scenarios you wrote are
+already its skeleton: read **pikku-guide**, write one page per audience citing
+every feature, and build it from a full, passing `--run browser --screenshots`
+run.
+
 Two things from it are worth knowing before you get there, because they are
 cheaper to honour than to retrofit: