@pikku/skills 0.12.57 → 0.12.59

package/skills/pikku-build/references/phase-5-prove-and-ship.md

@@ -0,0 +1,148 @@
+# Phase 5 — Prove it, make it look designed, ship it (§7-§9)
+
+Part of the app workflow (`app.md` is the index and the rules that hold throughout). Building a changeset is §6-§6b, in `phase-4-build.md`.
+
+## 7. Prove it — scenarios
+
+A scenario is a user journey run as one of your virtual users, over the real
+transport, with that virtual user's session. It is the only kind of test worth writing
+here, because a passing one proves the app works the way a signed-in person
+experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
+green — and every scenario a changeset's plan names becomes one more.
+
+**Read the scenarios reference (see SKILL.md) before writing the changeset's scenarios,
+and again whenever one of these describes what you are doing.** It is the file
+where the expensive lessons live, and most of them produce a GREEN suite that
+proves nothing:
+
+- the shape of a scenario, and `do` vs `given`/`when`/`then`
+- what survives DSL extraction — a `then` in `return` position asserts nothing,
+  and a shared setup helper credits its steps to the wrong virtual user
+- what to assert — refusals must read the REASON, totals must be deltas, and the
+  assertion nobody writes is the row count
+- living without a state reset: the suite must be green on its SECOND run
+- how a shared step rots as later changesets add writers of the rows it selects
+- browser specifics — the click/navigate race, testids, and `Outlet` nesting
+
+Run them:
+
+```sh
+bunx --bun pikku scenario run local --spawn                  # server-side, the fast path
+bunx --bun pikku scenario run local --spawn --run browser    # the same journeys, driven as a human
+```
+
+In a multi-app project that one run covers both frontends: each virtual user carries
+its own `app` and `@pikku/playwright` resolves the base url from the
+environment's `appUrls` map, so there is no second environment to run.
+
+**Run the whole suite, not the changeset's own scenarios.** The changeset's
+scenarios are the ones you wrote to pass; the regression lives in someone
+else's. Tightening what "archived" means is a one-function change that reads as
+local and quietly breaks the first changeset's scenario nobody re-ran.
+
+**Restart the server after adding a function, and never edit one while a run is
+in flight.** Hot reload does not register a new RPC and does not re-run
+`afterStart`, so a fresh function answers 404 and anything provisioned at boot
+is missing — failures that read like a wiring bug and are nothing but a stale
+process. The same reload is what makes a run unrepeatable if you edit during
+it: a browser pass is long enough to feel like free time, and a schema touched
+at minute four hot-reloads into a half-generated contract, so every scenario
+after that point fails on something you have already fixed. Wait for the run or
+kill it — a run you edited under is not a result.
+
+### 7a. Coverage — which functions have actually been run
+
+Run it as each changeset closes, read `coverage/scenario-coverage.json`, and report the number when you hand
+the changeset over. The scenarios reference (see SKILL.md), "Coverage", has the commands and how to tell a
+missing scenario from a function that should not exist from a real deferral.
+
+## 8. Make it look like someone designed it
+
+**This section numbers 8, but half of it has already happened.** Read
+the design reference (see SKILL.md) before the first screen is built — a design pass run on
+eight changesets of scaffolded screens is a repaint, and it shows. What is left
+here at §8 is the theme you may have deferred and the critique you cannot run
+until there are screens to critique.
+
+Three separate jobs, and conflating them is why open-source builds come out
+looking like the template:
+
+- **Direction** — deciding what it should look like. **No open-source tool does
+  this.** A hosting platform may offer one; you have §1's answer and 8a below.
+- **Execution** — whether the screens actually realise that direction, or
+  default to whatever component was nearest. No theme does this, and it is where
+  "works but looks like nobody decided anything" comes from.
+  the design reference (see SKILL.md) carries the process for it, and it belongs at §6, per
+  screen.
+- **Critique** — judging how well the built screens execute the direction.
+  `impeccable` does this well, and it is free.
+
+Impeccable audits the design you chose. It will never tell you the app should
+have looked like something else — it will happily award a clean bill of health to
+a perfectly-executed default. Skip the first two and you ship Neutral with good
+spacing.
+
+### 8a. Author the theme — the step nothing does for you
+
+The look lives in `packages/theme` as data. **Read the theming reference (see SKILL.md)**: the file layout, what
+each field changes, turning a direction in words into a theme, setting the theme once instead of hardcoding
+colours, sharing it across apps (vary the register, not the palette), and writing the direction into
+`knowledge/decisions/design/`.
+
+### 8b. Compose real components, then critique
+
+**The design reference (see SKILL.md) is where design actually lives** — committing to a
+direction before the first screen, judging the result from screenshots rather
+than from source, the two screens that get skipped, and why you reset the dev
+database before judging anything. It prescribes no layouts on purpose: two apps
+built from this skill should not look like each other. What follows here is only
+the component inventory.
+
+**Compose with rich components — not tables and text everywhere:**
+
+- **shadcn `chart`** (Recharts underneath, coloured by `--chart-1` to `--chart-5`) for overviews — area,
+  bar, line and pie charts. A metric worth showing is
+  worth a chart, not a number in a paragraph.
+- **shadcn `calendar` and `date-picker`** for anything time-based, including
+  range inputs. Never hand-roll a date field.
+- Composed layouts over flat lists — a timeline for history, steps for
+  multi-step progress, `Card` + a CSS grid for a gallery, `Progress` for
+  completion, `Badge` for status.
+
+Add each one with the shadcn CLI and use the real component.
+
+Then critique it. Free, and works across coding agents:
+
+```sh
+npx impeccable install     # current releases need Node 22.18+
+```
+
+Impeccable scores a screen against interaction heuristics and names what is
+wrong: hierarchy, spacing, type registers, states you forgot. Run it on **every**
+screen in **every** app, fix what it finds, and re-run the ones you changed.
+
+Screenshots (desktop and ~390px), feeding them to impeccable, and resetting the dev database before you judge
+are in the design reference (see SKILL.md), "Judge it" and "Facts, not taste". The template already mounts a
+phone navigation per `AGENTS.md` — pick `MobileTabBar` or `MobileNavDrawer` deliberately per app, never both.
+
+The gate: **no P0 findings left on any screen, in any app, at either width**,
+and every screen honestly answers the questions in the design reference —
+including whether it looks like the direction you committed to or like the
+components you had. Don't silence a finding by deleting the feature it is
+about.
+
+## 9. Ship it, and stay deploy-ready
+
+When the queue is empty, `pikku knowledge gaps` lists nothing and the scenarios are green, read
+the ship reference (see SKILL.md). It carries the open-source deploy paths (`--provider
+standalone`, `cloudflare`, `aws`), how to serve several frontends behind one
+API, the pre-release gate to run, and the contract that keeps the project
+importable by a hosting platform 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.
+
+The deploy-readiness contract in that reference (no hardcoded host, port or `process.env` in a function; generated
+files stay generated) is cheaper to honour while building than to retrofit.

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

@@ -26,9 +26,9 @@ failed; a showcase where every surface is a stub has also failed. The bar for
 each surface below: **it does something the app genuinely needs, and a scenario
 proves it.** A cron job that logs "tick" is not a schedule — it is a comment.
 
-Each surface lands with its console link, filtered by the person's level
-(SKILL.md, "Who you are talking to"): a non-technical person sees the workflow
-or agent page, never the queue, scheduler or wire pages behind it.
+Each surface is reported at the person's level (SKILL.md, "Who you are talking
+to"): a non-technical person hears about the workflow or the agent, never the
+queue, scheduler or wire behind it.
 
 Budget the extra surfaces at one changeset each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
@@ -46,7 +46,7 @@ at §1, and it is much cheaper than contriving a use later.
 
 The rest — MCP, triggers and webhooks, extra locales, contract versioning,
 addons — are chosen on merit. Write the motivation into the note. If you cannot
-name what one of *those* is for in this app, drop it and say why in
+name what one of _those_ is for in this app, drop it and say why in
 `knowledge/decisions/`: a documented omission is a stronger showcase than a
 contrived inclusion.
 
@@ -63,7 +63,6 @@ bunx --bun pikku enable events        # realtime events channel + SSE stream
 bunx --bun pikku enable remote-rpc    # internal RPC queue worker + HTTP endpoint
 bunx --bun pikku enable webhook       # outgoing webhook delivery queue worker
 bunx --bun pikku enable scenarios     # scenario instrumentation
-bunx --bun pikku enable console       # console functions
 bunx --bun pikku enable rpc           # public RPC endpoint
 ```
 
@@ -73,7 +72,7 @@ write the function — not the other way round.
 ## The surfaces
 
 Each has an installed skill that is authoritative on its API. Read it before
-writing the wiring; this section says what the surface is *for* and how to prove
+writing the wiring; this section says what the surface is _for_ and how to prove
 it, not how to call it.
 
 ### Workflows — `pikku-workflow`

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

@@ -49,7 +49,7 @@ defaults are the point.
 Do not ask about language either — take the defaults and note them in §6.
 Identifiers are English in every project, whatever the product's market;
 `metaLocale` in `pikku.config.json` (the language of `description`/`title`/step
-`template`, which the Console renders) stays `en` unless the user already told
+`template`) stays `en` unless the user already told
 you otherwise. If the request says the app's UI is not English, that is the
 message catalogue only: add the locale and set `defaultLocale`, and leave
 `baseLocale` at `en`. the app workflow's §1a has the three axes in full; getting
@@ -262,7 +262,7 @@ bunx --bun pikku scenario run local --spawn
 ## 6. Hand it over honestly
 
 Tell the user, in one short paragraph and at their level (SKILL.md, "Who you
-are talking to"), with console links rather than descriptions: what runs, what
+are talking to"), with the app and API links `bun run dev` printed: what runs, what
 it is seeded with, and that this is a quick build — no knowledge base, no
 changesets, no design pass, access control clicked-through rather than proven.
 

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

@@ -41,7 +41,6 @@ shape:
   "grouping": {
     "strategy": "single",
     "rules": [
-      { "unit": "console", "addon": "console" },
       { "unit": "pdf", "tags": ["pdf"] }
     ]
   }
@@ -50,11 +49,11 @@ shape:
 
 `strategy` is the fallback for a function no rule matches:
 
-| strategy | fallback |
-| --- | --- |
+| strategy   | fallback                                                      |
+| ---------- | ------------------------------------------------------------- |
 | `services` | one unit per distinct set of singleton services (the default) |
-| `function` | one unit each |
-| `single` | one shared unit |
+| `function` | one unit each                                                 |
+| `single`   | one shared unit                                               |
 
 Rules are ordered, first match wins, and match on `tags`, an `addon` namespace
 or `routes` globs. A rule always beats the strategy, so under `function` a rule

package/skills/pikku-changes/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: pikku-changes
-description: 'Work a project''s changes queue — the todo list someone filed by circling things in the running app. Covers `pikku changes wait|claim|show|ask|reply|shot|done`: waiting for work without polling, asking instead of guessing, saying why an item is left undone, offering options as images, one commit per item. TRIGGER when: the user says "run the changes against a stage", "work the changes (queue)", "watch the changes", "pick up the changes", names a change by its #number, or you are otherwise idle in a checkout with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, and not for deploying or debugging a stage.'
+description: >-
+  Work a project's changes queue, the todo list filed by circling things in the running app: `pikku
+  changes wait|claim|show|ask|reply|shot|done`, asking instead of guessing, saying why an item is
+  undone, options as images, one commit per item. TRIGGER when: the user says to run/work/watch/pick
+  up the changes (e.g. against a stage), names a change by #number, or you are idle in a checkout
+  with open changes (`pikku changes list`). DO NOT TRIGGER for git changes, diffs or changelogs, or
+  for deploying or debugging a stage.
 ---
 
 # Working a changes queue
@@ -39,12 +45,12 @@ something changed. `wait` does the waiting and exits only when there is work.
 
 2. When it exits, read the exit code:
 
-   | code | meaning                                                | do                                              |
-   | ---- | ------------------------------------------------------ | ----------------------------------------------- |
-   | 0    | work printed (claimed, and/or `Answered`)              | work it, then step 3                            |
-   | 2    | `--timeout`/`--once` found nothing                     | stop, or restart `wait`                         |
-   | 3    | auth refused                                           | relay the CLI's message; stop                   |
-   | 1    | anything else                                          | report the message; stop                        |
+   | code | meaning                                   | do                            |
+   | ---- | ----------------------------------------- | ----------------------------- |
+   | 0    | work printed (claimed, and/or `Answered`) | work it, then step 3          |
+   | 2    | `--timeout`/`--once` found nothing        | stop, or restart `wait`       |
+   | 3    | auth refused                              | relay the CLI's message; stop |
+   | 1    | anything else                             | report the message; stop      |
 
 3. For each item: `show` → fix → commit → `done`; or `ask` and move on; or `reply`
    saying why you are leaving it. Then start `wait` again, in the background.

package/skills/pikku-concepts/SKILL.md

@@ -1,13 +1,12 @@
 ---
 name: pikku-concepts
 description: >-
-  Use FIRST in any Pikku codebase, before writing an import or reaching for another pikku skill.
-  Covers the core mental model, function types, project structure, code generation and testing,
-  and how to read `pikku doc` — the API surface of the pikku actually installed here, which also
-  indexes which skill teaches each door. TRIGGER when: starting any Pikku task, about to import
-  from `#pikku/*`, unsure whether an export exists or what its options are called, choosing which
-  pikku skill to load, a build failed on an unknown import or option, or migrating an existing
-  backend to Pikku. DO NOT TRIGGER when: the task is not a Pikku project.
+  Use FIRST, and whenever you are about to write or change Pikku code: core mental model, function
+  types, project structure, code generation, testing, and reading `pikku doc` (the installed API surface, which also indexes which
+  skill teaches each area). TRIGGER when: starting any Pikku task, about to import from `#pikku/*`,
+  unsure an export or option exists, choosing which pikku skill to load, a build failed on an
+  unknown import or option, or migrating a backend to Pikku. DO NOT TRIGGER when: the task is not a
+  Pikku project.
 installGroups: [core]
 ---
 
@@ -72,70 +71,6 @@ which is what decides whether a thrown error becomes a 409 or a 500.
 `pikku doc` needs `@pikku/cli` 0.12.115 or newer. On an older pin, fall back to the door's
 skill and `pikku meta --json`, and do not guess at names the doc would have given you.
 
-## The CLI commands
-
-`pikku doc` is the API surface — the `#pikku/*` exports. It does **not** list
-commands, so this table is where they exist. `pikku <command> --help` has the
-flags; the "Read" column is the skill that teaches the thing, where one does.
-
-**Generating**
-
-| Command                                    | What it does                                         | Read                          |
-| ------------------------------------------ | ---------------------------------------------------- | ----------------------------- |
-| `all`                                      | Everything: types, schemas, wirings, clients         | this skill                    |
-| `bootstrap`                                | Type files only (the setup phase)                    | this skill                    |
-| `schemas`                                  | JSON Schemas for function input/output types         | this skill                    |
-| `fetch` / `websocket` / `rpc` / `realtime` | One client each, when you do not want `all`          | `pikku-wiring`, `pikku-react` |
-| `react-query` / `tanstack-start`           | React Query hooks; the TanStack Start `makeApi` shim | `pikku-react`                 |
-| `queue-service`                            | The queue service wrapper                            | `pikku-wiring`                |
-| `openapi`                                  | An OpenAPI spec from the HTTP routes                 | —                             |
-| `nextjs`                                   | Next.js backend and HTTP wrappers                    | `pikku-deploy`                |
-| `new`                                      | Scaffold a function or wiring                        | `pikku-wiring`                |
-| `enable`                                   | Turn a Pikku feature on                              | `pikku-build`                 |
-| `import`                                   | Import workflows from another system                 | `pikku-n8n-import`            |
-
-**Running**
-
-| Command                           | What it does                                                                   | Read                                         |
-| --------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------- |
-| `dev`                             | Local dev server, all services wired, watch + HMR                              | `pikku-build`                                |
-| `serve`                           | Bundled bun/node runner — no watch, no codegen                                 | `pikku-deploy`                               |
-| `watch`                           | Regenerate on file change, without a server                                    | —                                            |
-| `scenario list\|run`              | Scenarios as e2e tests and health checks                                       | `pikku-scenario`                             |
-| `virtual-user run`                | A declared virtual user, model-driven, against a stage                         | `pikku-scenario`, virtual-user-run reference |
-| `virtual-user list\|sync\|secret` | Who is declared; what an environment will provision; minting their credentials | `pikku-scenario`, virtual-user-run reference |
-| `db`                              | Local development database                                                     | `pikku-kysely`                               |
-
-**Inspecting and evolving**
-
-| Command                | What it does                                                            | Read                         |
-| ---------------------- | ----------------------------------------------------------------------- | ---------------------------- |
-| `doc`                  | The installed API surface                                               | this skill                   |
-| `meta` / `info`        | What the project declares, machine- and human-readable                  | `pikku-meta`                 |
-| `validate`             | Every check that applies — app structure, an addon's published file set | `pikku-build`, `pikku-addon` |
-| `versions` / `release` | Contract hashes, breaking-change detection, versioned releases          | `pikku-meta`                 |
-| `audit` / `update`     | Advisories; which `@pikku/*` can move and what peers that needs         | `pikku-meta`                 |
-| `scopes` / `roles`     | Declared authorization scopes; roles from `defineSystemRole`            | `pikku-auth`                 |
-| `knowledge`            | The knowledge base — what this app is, in its users' language           | `pikku-knowledge`            |
-| `emails`               | Email template generation                                               | `pikku-emails`               |
-
-**Shipping, and the CLI itself**
-
-| Command                       | What it does                                                                                                                                   | Read           |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| `deploy`                      | Deploy to cloud infrastructure                                                                                                                 | `pikku-deploy` |
-| `binary`                      | Compile an entrypoint to a native binary (`bun build --compile`)                                                                               | —              |
-| `dist`                        | Copy what `tsc` cannot emit — `.gen.json` meta, hand-authored `.d.ts` — into the build output. Run it after `tsc`, as a package's build script | —              |
-| `login` / `logout` / `whoami` | The CLI's session against a pikku server                                                                                                       | —              |
-| `skills`                      | Install these skills into an agent (Claude Code, opencode, pi)                                                                                 | —              |
-
-`-c/--config`, `--log-level`, `--json` and the filter flags are **global
-options**, not commands — they attach to the generating commands above.
-
-A dash means no skill covers it beyond this line. `--help` is then the whole of
-it — which is a reason to read `--help` rather than to assume the command does
-what its name suggests.
-
 ## Core Mental Model
 
 ```text
@@ -167,141 +102,6 @@ The function never imports Express, never reads `req.body`, never touches `ws.se
 
 Controllers/routes → `pikkuFunc`; auth/sessions and authorization checks → `pikku-auth`, a separate install; request interception → `pikku-middleware`; DI → `pikku-services`; transports (HTTP/WS/queue/cron) → their `wire*` + skill. For the full Generic Backend → Pikku mapping table (with side-by-side code examples), read `references/concept-mapping.md`.
 
-## Functions
-
-Three main function types:
-
-```typescript
-// Requires authentication — receives session in wire context.
-// input/output are Zod schemas; the data + return types are inferred from them.
-const updateTodo = pikkuFunc({
-  input: UpdateTodoInput,
-  output: TodoOutput,
-  func: async (services, data, wire) => {
-    const { session } = wire
-    return services.todoStore.update(data.id, data)
-  },
-})
-
-// No authentication required
-const listTodos = pikkuSessionlessFunc({
-  input: ListTodosInput,
-  output: TodoListOutput,
-  func: async (services, data) => {
-    return { todos: services.todoStore.list(data.filters) }
-  },
-})
-
-// No input or output (for scheduled tasks, lifecycle hooks)
-const cleanup = pikkuVoidFunc(async (services) => {
-  services.todoStore.cleanOldItems()
-})
-```
-
-Services can be destructured inline in the `func` signature (e.g. `async ({ logger, todoStore }, { title }) => ...`). Full config options:
-
-```typescript
-pikkuFunc({
-  // Identity and documentation — prose, so it follows `metaLocale` in
-  // pikku.config.json (default `en`). The identifier does not; see
-  // "What Language You Write In".
-  title?: string,           // Human-readable name
-  description?: string,     // What the function does
-  version?: number,         // Contract version (see pikku-meta)
-  override?: string,        // Logical name override, so several exports share a versioned base
-  tags?: string[],          // For grouping and middleware targeting
-
-  // Contract
-  input?: ZodSchema,        // Input validation schema
-  output?: ZodSchema,       // Output validation schema
-  errors?: Array<typeof PikkuError>,  // Errors this function may throw
-
-  // Reachability
-  expose?: boolean,         // Allow external RPC calls (see pikku-wiring)
-  remote?: boolean,         // Allow remote RPC calls
-  mcp?: boolean,            // Expose as MCP tool (see pikku-wiring)
-  readonly?: boolean,       // Declares the function performs no writes
-  deploy?: 'serverless' | 'server' | 'auto',
-
-  // Authorization — see pikku-auth
-  auth?: boolean,           // Override default auth requirement
-  scopes?: ScopeId[],       // AND-ed, checked before permissions; session required
-  permissions?: PermissionGroup,  // OR-ed pool
-  permissionsInBody?: boolean,    // Last resort; needs allow.permissionsInBody in config
-  middleware?: PikkuMiddleware[], // See pikku-middleware
-
-  // Agent tooling — see pikku-agent
-  approvalRequired?: boolean,
-  approvalDescription?: (services, data) => Promise<string>,
-
-  // Workflow step behavior — see pikku-workflow
-  workflowQueued?: boolean, // Dispatch via queue instead of inline
-  workflowRetries?: number,
-  workflowTimeout?: string, // e.g. '30s', '5m'
-
-  audit?: boolean | { durability?: 'best-effort' | 'transactional' },
-
-  func: async (services, data, wire) => { ... },
-})
-```
-
-`scopes` is the one option `pikkuSessionlessFunc` does not accept, and the
-omission is deliberate: scopes are AND-ed and fail closed, so an anonymous
-caller holds none and satisfies none — a sessionless function with scopes would
-reject every caller it exists to serve. Gate those with `permissions`, which
-receive the optional session and may pass anonymous.
-
-**Generics XOR `input`/`output` — never both.** A function's data and return
-types come from _one_ source: either the `input`/`output` schemas (preferred —
-they double as runtime validation and OpenAPI) or type generics
-(`pikkuFunc<In, Out>({ ... })`). Passing both makes the two disagree and forces
-`as any` casts. Do not annotate the `func` return type inline either — let the
-`output` schema (or the generic) be the single source of truth for the type.
-
-```typescript
-// Correct — schema-based (no generics, no inline return type)
-pikkuFunc({ input: MyInput, output: MyOutput, func: async (s, d) => { ... } })
-// Correct — generic-based (no input/output)
-pikkuFunc<MyIn, MyOut>({ func: async (s, d) => { ... } })
-// WRONG — mixing the two
-pikkuFunc<MyIn, MyOut>({ input: MyInput as any, func: async (s, d) => { ... } })
-```
-
-## Schemas (Validation)
-
-Pikku uses Standard Schema — works with Zod, Valibot, ArkType:
-
-```typescript
-import { z } from 'zod'
-
-const CreateTodoInputSchema = z.object({
-  title: z.string().min(1).max(200),
-  priority: z.enum(['low', 'medium', 'high']).optional(),
-  tags: z.array(z.string()).optional(),
-})
-```
-
-Schemas serve triple duty: runtime validation, TypeScript types, and OpenAPI documentation.
-
-## Server Bootstrap
-
-Two ways to start a Pikku app, and the choice is whether you need to own the HTTP server.
-
-**Let Pikku own it** — `pikku dev` and `pikku serve` create the config and singleton services,
-start the server and shut it down cleanly, so you write no bootstrap code at all. Startup and
-shutdown work goes in one exported `pikkuServerLifecycle` (`beforeStart` / `afterStart` /
-`beforeStop`). **Only `dev` and `serve` invoke those hooks** — no deploy runtime does, so anything
-a Workers or serverless stage needs done belongs on the request path that needs it.
-
-**Bootstrap it yourself** — required for Express, Fastify, uWS, Lambda, Cloudflare and Next.js,
-where Pikku is embedded in a server you own. Lifecycle hooks do not run on this path; do the
-startup work in the entrypoint.
-
-`pikku validate` warns when a project starts a server by hand _and_ depends on no runtime adapter,
-because that means the first path was available and unused.
-
-**`references/bootstrap.md`** has both entrypoints in full.
-
 ## Code Generation
 
 Run `npx pikku all` to generate:
@@ -351,59 +151,20 @@ src/
 
 ## What Language You Write In
 
-Three different things in a Pikku project have a human language, and they are **not** the same
-language. Collapsing them is the common mistake:
-
-| Axis            | Covers                                                                        | Decided by                                                    |
-| --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| **Identifiers** | Function, component, type and file names; tables and columns; commit messages | Nothing. **Always English.** There is no setting              |
-| **Meta**        | Prose authored inside the code — `description`, `title`, step `template`      | `metaLocale` in `pikku.config.json` (default `en`)            |
-| **Product UI**  | Every string the app shows a user                                             | `messages/<locale>.json`, and `active.json`'s `defaultLocale` |
-
-Identifiers are the surface every other tool binds to — the generated clients, the RPC map a
-scenario is typed over, the SQL types — and unlike a string an identifier cannot be translated
-later: renaming one is a migration. `metaLocale` exists so a team can read their own Console in
-their own language; it is not licence to rename anything. And `baseLocale` in
-`project.inlang/settings.json` stays `en`, because it names the message _source_ every other
-language is cloned from.
-
-**When a brief tells you the product speaks a language, it is telling you about the third axis and
-nothing else.** `references/language.md` has the three settings that satisfy such a brief, and the
-failure to avoid: reading one sentence about a product's users as an instruction about its codebase
-(German RPC names, German tables, no English catalogue to translate from).
-
-## Environment Variables
-
-Never use `process.env` inside Pikku functions. Use the `variables` service (see `pikku-services`):
-
-```typescript
-const apiKey = services.variables.get('API_KEY')
-```
-
-`process.env` belongs in server bootstrap code (`start.ts`) only.
+Identifiers (function, type, file, table and column names) are **always English**. `metaLocale` in
+`pikku.config.json` is the language of authored meta (`description`, `title`, step `template`).
+A product speaking another language is only about the UI strings in `messages/<locale>.json`.
+Read `references/language.md` before touching any of the three.
 
-## Secrets
-
-`secrets` is not part of a function's services. It is available only in
-`pikkuServices`, `pikkuWireServices`, addon service factories and middleware —
-read it there, give the value to a service, and have the function ask that
-service. Reaching for it through a cast throws at runtime.
-
-## Testing
-
-Functions are easily testable because they're pure:
-
-```typescript
-const mockServices = {
-  logger: new MockLogger(),
-  todoStore: new MockTodoStore(),
-}
+## Available Packages
 
-// Call function directly — no HTTP, no framework
-const result = await listTodos.func(mockServices, { userId: 'test' })
-expect(result.todos).toHaveLength(3)
-```
+Pikku ships runtime adapters (`@pikku/express`, `@pikku/fastify`, `@pikku/next`, `@pikku/lambda`, `@pikku/cloudflare`, `@pikku/uws`, `@pikku/modelcontextprotocol`, ...) and service packages (`@pikku/jose`, `@pikku/schema-ajv`, `@pikku/pino`, `@pikku/kysely`, `@pikku/redis`, `@pikku/queue-bullmq`, `@pikku/queue-pg-boss`, ...). For the full list with use cases, read `references/packages.md`.
 
-## Available Packages
+## Where the rest lives
 
-Pikku ships runtime adapters (`@pikku/express-server`, `@pikku/fastify-server`, `@pikku/next`, `@pikku/aws-lambda`, `@pikku/cloudflare`, `@pikku/uws-server`, `@pikku/modelcontextprotocol`, ...) and service packages (`@pikku/jose`, `@pikku/schema-ajv`, `@pikku/pino`, `@pikku/kysely`, `@pikku/redis`, `@pikku/queue-bullmq`, `@pikku/queue-pg-boss`, ...). For the full list with use cases, read `references/packages.md`.
+- `references/cli.md` — every CLI command, with its flags.
+- `references/functions.md` — function types, config keys and schemas (Standard Schema).
+- `references/bootstrap.md` — letting Pikku own the server versus bootstrapping it yourself.
+- `references/testing.md` — calling `.func` directly with mock services.
+- Env vars and secrets: `pikku-services`. Never `process.env` inside a function.
+- `references/language.md`, `references/concept-mapping.md`, `references/packages.md`.

package/skills/pikku-concepts/references/cli.md

@@ -0,0 +1,63 @@
+# The Pikku CLI commands
+
+`pikku doc` is the API surface — the `#pikku/*` exports. It does **not** list
+commands, so this table is where they exist. `pikku <command> --help` has the
+flags; the "Read" column is the skill that teaches the thing, where one does.
+
+**Generating**
+
+| Command                                    | What it does                                         | Read                          |
+| ------------------------------------------ | ---------------------------------------------------- | ----------------------------- |
+| `all`                                      | Everything: types, schemas, wirings, clients         | this skill                    |
+| `bootstrap`                                | Type files only (the setup phase)                    | this skill                    |
+| `schemas`                                  | JSON Schemas for function input/output types         | this skill                    |
+| `fetch` / `websocket` / `rpc` / `realtime` | One client each, when you do not want `all`          | `pikku-wiring`, `pikku-react` |
+| `react-query` / `tanstack-start`           | React Query hooks; the TanStack Start `makeApi` shim | `pikku-react`                 |
+| `queue-service`                            | The queue service wrapper                            | `pikku-wiring`                |
+| `openapi`                                  | An OpenAPI spec from the HTTP routes                 | —                             |
+| `nextjs`                                   | Next.js backend and HTTP wrappers                    | `pikku-deploy`                |
+| `new`                                      | Scaffold a function or wiring                        | `pikku-wiring`                |
+| `enable`                                   | Turn a Pikku feature on                              | `pikku-build`                 |
+| `import`                                   | Import workflows from another system                 | `pikku-n8n-import`            |
+
+**Running**
+
+| Command                           | What it does                                                                   | Read                                         |
+| --------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------- |
+| `dev`                             | Local dev server, all services wired, watch + HMR                              | `pikku-build`                                |
+| `serve`                           | Bundled bun/node runner — no watch, no codegen                                 | `pikku-deploy`                               |
+| `watch`                           | Regenerate on file change, without a server                                    | —                                            |
+| `scenario list\|run`              | Scenarios as e2e tests and health checks                                       | `pikku-scenario`                             |
+| `virtual-user run`                | A declared virtual user, model-driven, against a stage                         | `pikku-scenario`, virtual-user-run reference |
+| `virtual-user list\|sync\|secret` | Who is declared; what an environment will provision; minting their credentials | `pikku-scenario`, virtual-user-run reference |
+| `db`                              | Local development database                                                     | `pikku-kysely`                               |
+
+**Inspecting and evolving**
+
+| Command                | What it does                                                            | Read                         |
+| ---------------------- | ----------------------------------------------------------------------- | ---------------------------- |
+| `doc`                  | The installed API surface                                               | this skill                   |
+| `meta` / `info`        | What the project declares, machine- and human-readable                  | `pikku-meta`                 |
+| `validate`             | Every check that applies — app structure, an addon's published file set | `pikku-build`, `pikku-addon` |
+| `versions` / `release` | Contract hashes, breaking-change detection, versioned releases          | `pikku-meta`                 |
+| `audit` / `update`     | Advisories; which `@pikku/*` can move and what peers that needs         | `pikku-meta`                 |
+| `scopes` / `roles`     | Declared authorization scopes; roles from `defineSystemRole`            | `pikku-auth`                 |
+| `knowledge`            | The knowledge base — what this app is, in its users' language           | `pikku-knowledge`            |
+| `emails`               | Email template generation                                               | `pikku-emails`               |
+
+**Shipping, and the CLI itself**
+
+| Command                       | What it does                                                                                                                                   | Read           |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `deploy`                      | Deploy to cloud infrastructure                                                                                                                 | `pikku-deploy` |
+| `binary`                      | Compile an entrypoint to a native binary (`bun build --compile`)                                                                               | —              |
+| `dist`                        | Copy what `tsc` cannot emit — `.gen.json` meta, hand-authored `.d.ts` — into the build output. Run it after `tsc`, as a package's build script | —              |
+| `login` / `logout` / `whoami` | The CLI's session against a pikku server                                                                                                       | —              |
+| `skills`                      | Install these skills into an agent (Claude Code, opencode, pi)                                                                                 | —              |
+
+`-c/--config`, `--log-level`, `--json` and the filter flags are **global
+options**, not commands — they attach to the generating commands above.
+
+A dash means no skill covers it beyond this line. `--help` is then the whole of
+it — which is a reason to read `--help` rather than to assume the command does
+what its name suggests.