@pikku/skills 0.12.27 → 0.12.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.27",
+  "version": "0.12.29",
   "description": "The Pikku agent skills — the instruction set coding agents read to build, wire and deploy Pikku projects",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/skills/pikku-addon/SKILL.md

@@ -2,8 +2,8 @@
 name: pikku-addon
 description: >-
   Use when creating or consuming reusable function packages (addons) in Pikku. Covers wireAddon,
-  ref(), pikkuAddonServices, pikkuAddonWireServices, addon package structure, and cross-project
-  function sharing. TRIGGER when: code uses wireAddon/ref()/pikkuAddonServices, user asks about
+  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
   TRIGGER when: user asks about internal function composition (use pikku-wiring) or general function
   definitions (use pikku-concepts).
@@ -264,6 +264,49 @@ addon` above is the exception — it runs before the addon, and its CLI, exist.
 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
+
+An addon may **ship** tables. It must never **create** them: it runs inside the
+consumer, against the consumer's database, so a boot-time `CREATE TABLE` puts a
+second authority on a schema the consumer's migrations own. It declares instead,
+and the consumer's migration history absorbs the declaration.
+
+Author the DDL per dialect:
+
+```text
+db/sqlite/0001-labels.sql
+db/postgres/0001-labels.sql
+```
+
+`pikku all` publishes `<outDir>/db/pikku-db-meta.gen.json` on every build — per
+dialect, the SQL verbatim plus a table/column map — and writes it **empty** when
+the addon has no tables, because a consumer reads an absent file as a package
+that cannot say. (`pikku db export` writes the same file on demand.) The
+consumer resolves it **through the package name**, so it must be exported and
+packed, or it never arrives:
+
+```json
+{
+  "exports": {
+    "./.pikku/db/pikku-db-meta.gen.json": "./dist/.pikku/addon/db/pikku-db-meta.gen.json"
+  },
+  "files": ["dist"]
+}
+```
+
+**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:
+it publishes `{}` and is waved through.
+
+Two more loud ones: a malformed artifact (missing the SQL for a dialect it
+claims) is rejected rather than half-applied, and an addon publishing only a
+dialect the consumer does not use gets an error naming what it does support.
+
+`verifiers/db-schema` runs this end to end on both dialects — copy its addon
+`package.json` when wiring a new one.
+
 ## Consuming an Addon
 
 ### Install & Register
@@ -281,6 +324,14 @@ wireAddon({ name: 'todos', package: '@my-org/addon-todos' })
 
 After registration, run `yarn pikku all` to generate types for the addon's functions.
 
+If the addon ships tables, `pikku db generate` then writes one migration per
+addon — named after the package, carrying the addon's own SQL — after Better
+Auth's and the runtime's, so an addon table may reference `user` or a runtime
+table. `pikku db migrate` applies it; re-running `generate` writes nothing once
+covered, and writes only the delta after an addon upgrade. An addon wired with
+`wireRemoteAddon` contributes no schema at all: its tables belong to the
+deployment that runs its functions.
+
 ### Call via RPC
 
 ```typescript

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

@@ -57,7 +57,8 @@ package that declared them, and the extra segment is what stops a linked addon's
     "./.pikku/pikku-metadata.gen.json": "./dist/.pikku/addon/pikku-metadata.gen.json",
     "./.pikku/rpc/pikku-rpc-wirings-map.internal.gen.js": {
       "types": "./dist/.pikku/addon/rpc/pikku-rpc-wirings-map.internal.gen.d.ts"
-    }
+    },
+    "./.pikku/db/pikku-db-meta.gen.json": "./dist/.pikku/addon/db/pikku-db-meta.gen.json"
   },
   "files": ["dist"],
   "peerDependencies": {

package/skills/pikku-agent/SKILL.md

@@ -23,7 +23,7 @@ than what they look like.
 
 | You are… | Read |
 | --- | --- |
-| Defining or invoking an agent — tools, memory, streaming, approval, threads | `references/agents.md` |
+| Defining or invoking an agent — tools, memory, streaming, approval, threads, images | `references/agents.md` |
 | Wiring the runner, or pointing model strings at a provider or gateway | `references/runner-vercel.md` |
 | Adding speech in or out of an agent | `references/voice.md` |
 
@@ -44,7 +44,9 @@ session, the credentials and the RPC depth for you.
   key. `role`, `personality` and `goal` are concatenated in that order and
   nothing validates which text lands where, so the split buys legibility only.
 - **`output` is honoured only when the agent has no tools.** A structured-output
-  schema on a tool-calling agent is silently inert.
+  schema on a tool-calling agent is silently inert. The pairing that wants it is
+  reading an image or a document into typed data — one tool-free agent, an
+  `output` schema, and the picture passed as an `attachments` entry.
 - **`auth` defaults to `false`**, because agents are normally invoked from an
   already-authenticated `pikkuFunc`. `scopes` and `permissions` are enforced
   either way — see `pikku-auth`.

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

@@ -201,6 +201,36 @@ export const structuredAgent = pikkuAgent({
 })
 ```
 
+### Images and files
+
+`attachments` on the agent input is how a picture, a scan or a PDF reaches the
+model. Each entry carries **either** `data` (base64, no `data:` prefix) **or**
+`url`, plus a `mediaType`:
+
+```typescript
+const { object } = await rpc.agent.run('read-receipt', {
+  message: 'List every line item on this receipt.',
+  threadId, resourceId,
+  attachments: [{ type: 'image', data: base64Jpeg, mediaType: 'image/jpeg' }],
+})
+```
+
+- **`url` is downloaded server-side**, by the runner, before the model sees it —
+  so a caller-supplied URL is an SSRF surface. `VercelAgentRunner`'s third
+  constructor argument is a host allowlist; set it whenever an HTTP wiring
+  accepts attachment URLs, or take `data` and never accept a URL at all.
+- **The model has to be a vision model.** The provider prefix does not decide
+  this — `openai/gpt-5-mini` reads images, a text-only id in the same family
+  answers as though the attachment were not there rather than erroring.
+- **Reading an image into data is the tool-free case**, so it can use `output`:
+  an agent with an `output` schema and no tools resolves `result.object` as the
+  typed extraction. Add one tool and you get prose back instead — see
+  **Structured output** above.
+- **Base64 is the request body.** A phone photo is measured in megabytes and
+  goes through your function's input schema, the RPC payload and the model's
+  context. Downscale on the client before uploading — the model does not read
+  the pixels you paid to send.
+
 ### Narrowing tools per step
 
 `prepareStep` runs before each step with the live tool array for that step, so

package/skills/pikku-build/SKILL.md

@@ -33,9 +33,11 @@ plus more effort" — it is App plus a deliberate surface checklist, so read the
 base first and follow it in full rather than blending the two into one plan.
 
 The supporting references belong to whichever mode sends you to them:
-`references/multi-app.md` (a second frontend), `references/theming.md`
-(authoring the theme), `references/ship.md` (deploying, and the Fabric-readiness
-contract).
+`references/multi-app.md` (a second frontend), `references/design.md` (committing
+to a design direction and judging whether the screens realise it — read before
+the first screen is built, not after the last), `references/theming.md`
+(authoring the theme),
+`references/ship.md` (deploying, and the Fabric-readiness contract).
 
 ## Bootstrap before anything else
 

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

@@ -418,6 +418,12 @@ over, and an uncovered function is a half-milestone whether or not the note says
    file. Compose the kit from `@/components/<Name>` rather than hand-rolling.
    Register the screen in `useNavItems()` — that one file feeds both the desktop
    sidebar and the phone navigation.
+   **Read `references/design.md` before you write the first screen.** You commit
+   to a design direction there and are then accountable to it — it hands you no
+   layouts, because the design is yours to make. Screenshot each screen at 390
+   and 1440 with the seed in place at the END of every milestone, and look at the
+   images — not once at §8, where the only affordable fix is a repaint of eight
+   screens.
 6. **Scenario** (§7), then `status: built`.
 
 Rules that are not optional:
@@ -635,17 +641,29 @@ loud is a number nobody acts on.
 
 ## 8. Make it look like someone designed it
 
-Two separate jobs, and conflating them is why open-source builds come out looking
-like the template:
-
-- **8a. Direction** — deciding what it should look like. **No open-source tool
-  does this.** Fabric has `fabric-theme`; you have §1's answer and this section.
-- **8b. Critique** — judging how well the built screens execute that direction.
+**This section numbers 8, but half of it has already happened.** Read
+`references/design.md` before the first screen is built — a design pass run on
+eight milestones 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.** Fabric has `fabric-theme`; 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.
+  `references/design.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 8a and you ship Neutral with good spacing.
+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
 
@@ -674,6 +692,13 @@ theme is; only the note records why.
 
 ### 8b. Compose real components, then critique
 
+**`references/design.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 Mantine's rich components — not tables and text everywhere:**
 
 - **`@mantine/charts`** (Recharts underneath) for overviews — `AreaChart`,
@@ -710,8 +735,17 @@ a modal taller than the viewport. Mantine gives you the tools (responsive `Grid`
 them. 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.**
-Don't silence a finding by deleting the feature it is about.
+The gate: **no P0 findings left on any screen, in any app, at either width**,
+and every screen honestly answers the questions in `references/design.md` —
+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.
+
+**Critique the data too, not just the layout.** Scenario runs write run-tagged
+rows into the dev database, so by §8 the app is full of `Ripe peaches d193e2aa`
+seven copies deep. Run `pikku db reset` and restart the dev server before you
+screenshot anything — a screen judged against that data gets designed for a
+problem it does not have.
 
 ## 9. Ship it, and stay Fabric-ready
 
@@ -735,6 +769,8 @@ cheaper to honour than to retrofit:
 
 - `references/multi-app.md` — adding a second frontend (§4), at the milestone
   that needs it
+- `references/design.md` — committing to a design direction, and how to tell
+  whether the screens realise it. Read BEFORE the first screen (§6), not at §8
 - `references/theming.md` — authoring the theme (§8a)
 - `references/ship.md` — deploying, and the Fabric-readiness contract (§9)
 - Sibling skills: `pikku-knowledge` (§2), `pikku-auth` (§3),

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

@@ -0,0 +1,128 @@
+# Design
+
+Your job here is to design something worth the product — not to apply a house
+style. **There is no house style, and this file is not one.** Two apps built from
+this skill should not look like each other; if they do, something has gone wrong
+that no amount of spacing will fix.
+
+So: no prescribed layouts, no component rules, no ratios. What follows is the
+process that makes freedom accountable, the handful of facts that are not
+matters of taste, and the symptoms of a screen nobody actually designed.
+
+## Commit to a direction before the first screen
+
+An agent given "make it look good" and nothing else defaults — to the component
+nearest to hand, on every screen, in every app. Not because it lacks taste, but
+because there is nothing to be wrong against. A direction fixes that: state one,
+in words, before any screen exists.
+
+Say what this product *is* — its register, its reference points, what it feels
+like to use, what it is deliberately not. "A warm, food-forward thing you use
+standing at an open fridge door, closer to a recipe card than to a dashboard, and
+never clinical" is a direction. "Clean and modern" is not — it rules nothing out,
+so it cannot be departed from.
+
+Write it to `knowledge/decisions/design/`, then build the theme from it
+(`references/theming.md`). **From that point you are accountable to your own
+direction, not to this file.** That is the whole mechanism: the freedom is real,
+and so is the commitment.
+
+Be ambitious with it. A direction that could describe any SaaS app has not been
+chosen — it has been defaulted to in words instead of in components.
+
+## One screen, designed properly, before the rest exist
+
+Design the first real screen as if it were the only one, and take it further than
+feels necessary. Every screen after it inherits its register — its density, its
+rhythm, what a row of data looks like, how state is signalled. That inheritance
+happens whether you plan it or not, so make the first one worth inheriting.
+
+This is also the cheapest design work in the project. The eighth screen is a
+repaint of eight; the first is a decision.
+
+## Judge it — and don't grade your own homework
+
+Models rate their own output generously, and "does this look good?" answered by
+the thing that made it is always yes. Use evidence.
+
+- **Screenshot every screen and look at the image**, at ~390px and at ~1440px.
+  Judging your own UI from source is guessing, and the failures that matter —
+  proportion, hierarchy, a wall of identical boxes — are invisible in JSX.
+- **Run `impeccable`** (`npx impeccable install`, Node 22.18+) and feed it the
+  screenshots. It is external, it does not flatter, and it scores execution
+  against interaction heuristics. But it audits how well you executed the design
+  you chose — it will award a clean bill of health to a perfectly executed
+  default. It checks step 2; it never replaces it.
+- **Look at every milestone, not once at the end.** A screen that was fine at
+  three rows is a different screen at sixty, and the milestone that added the
+  sixty is the cheapest place to notice.
+
+Questions worth answering honestly, per screen. The answers are yours; only the
+questions are fixed:
+
+1. What question does someone open this screen to ask, and how fast do they get
+   the answer?
+2. What can be understood before reading a word?
+3. What is here that is not earning its space?
+4. What does it look like at real volume, and at 390px?
+5. Does it look like the direction you committed to — or like the components you
+   had?
+6. Would you show it to the user without apologising for it?
+
+## Facts, not taste
+
+These are not design opinions and are not open to a different answer.
+
+- **Reset the dev database before judging anything.** Scenario runs deliberately
+  tag rows with a run id so assertions do not collide, so after a few runs the
+  app is full of `Ripe peaches d193e2aa`, seven copies deep. Nobody's data looks
+  like that, and a screen designed against it is designed for a problem it does
+  not have. `pikku db reset` replays the migrations and the seed — and the dev
+  server holds an open handle to the file, so **restart it after**, or every call
+  fails with `disk I/O error` and the app looks broken for reasons that are not
+  the app.
+- **Seed generously and realistically.** A seed with a deliberate spread designs
+  the hard cases for you. Three identical rows teach you nothing.
+- **Never render a sign-in method that is not configured.** A "Continue with
+  Google" button on an app with no Google credentials is a dead control on the
+  first screen anyone sees. Render social buttons from what `socialProviders`
+  actually declares — and when it declares none, the divider goes too.
+- **Empty, loading and error are states that exist.** The empty state is what a
+  new user meets first and the one most often skipped entirely.
+- **Contrast and tap targets are measured, not judged.** `pikku-a11y` covers it.
+  One trap worth knowing: a Mantine `light` variant paints its label at the
+  generated ramp's stop, which lands just under AA on its own tint — name the
+  darker ink once and reuse it.
+
+## Two screens that get skipped
+
+Not rules about how they should look — only that they are yours to design.
+
+**The login page is the entry point.** It is the first thing anyone sees, where
+every demo starts, and routinely the least designed screen in the app: a default
+card with a wordmark, saying "scaffold" before the product has said anything. It
+gets the same direction as everything else.
+
+**The navigation is on every screen**, which makes it the highest-leverage
+surface you have. The scaffold mounts one that works; working is not the same as
+considered. Decide the destinations and their number deliberately, and style it
+through the theme rather than leaving the component defaults — the same look on
+every app is the tell.
+
+## Symptoms of a screen nobody designed
+
+If a screen shows these, you defaulted. **The fix is yours to choose** — these
+are a diagnosis, not a prescription, and the interesting answer is rarely the
+first one.
+
+- The top of the screen is a form, and the content it acts on starts below the
+  fold.
+- Two adjacent surfaces do the same job because both were added separately.
+- Everything is the same size, weight and colour, so nothing can be found
+  without reading it.
+- The same fact is stated twice in one line, in two different components.
+- A section named for an exception holds half the data.
+- Every row carries the same buttons, and the buttons outweigh the content.
+- The palette's meaningful colours are also used decoratively, so they have
+  stopped meaning anything.
+- It looks like the last app you built.

package/skills/pikku-fabric/SKILL.md

@@ -285,6 +285,39 @@ script, run `pikku dev` from the **project root** (it resolves `srcDirectories`
 relative to the config, so a nested cwd yields a doubled watch path and no hot
 reload).
 
+## Reaching a model
+
+An agent needs an `agentRunner` in singleton services, and locally you do not
+write one: `pikku dev` builds it from env when it finds a **matching pair** —
+`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or `LITELLM_PROXY_URL` + `LITELLM_API_KEY`
+— and registers it under `'*'`, so every `provider/model` prefix resolves
+through it. With neither pair complete it builds nothing and every agent call
+fails with `AIProviderNotConfiguredError` (a 503) — which reads like a broken
+agent rather than a missing key, so check `.env` first. Mixing halves is worse
+than missing them: a URL from one source with a key from the other 401s on every
+call, so the pairs are taken whole, OpenAI first.
+
+Two ways to fill them in:
+
+**The Fabric AI gateway.** One key, and every model the gateway fronts —
+OpenAI, Anthropic, Google, the OpenRouter catalogue — is reachable by id, billed
+through your Fabric account rather than per-vendor:
+
+```bash
+pikku fabric login
+pikku fabric llm key --env >> .env    # writes both pairs; --shell and --json also exist
+```
+
+It mints or reuses a developer-scoped key against your Fabric login. `link` is
+not required — the key is yours, not the project's.
+
+**Your own vendor key.** `OPENAI_BASE_URL=https://api.openai.com/v1` with your
+`OPENAI_API_KEY`, and model ids are then only the ones that vendor serves.
+
+A deployed stage takes the same names through `pikku fabric secrets set` /
+`variables set` — the agent units get their runner wired by the bundler, from
+those values.
+
 ## Deploy
 
 ```bash

package/skills/pikku-knowledge/SKILL.md

@@ -141,7 +141,8 @@ And writing again replaces it rather than adding a second
 ```
 ````
 
-- **`status`** is `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally.
+- **`status`** is `designing` → `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally. `designing` sits BEFORE `proposed`: the slice is written down but must not be built yet, because whoever is being shown its looks has not picked one. Only `proposed` is dispatchable, so the two cannot be one status without a slice being built out from under the person still choosing.
+- **`statusAt:` and `attempts:` are bookkeeping, not content — never hand-edit them.** A loop driving this base writes both. `statusAt:` is stamped by whatever moved the status, and is what makes "how long has this been building?" answerable; the file's mtime is not the transition time, because a note is edited after dispatch for all sorts of reasons. `attempts:` is `seat@hash` entries recording which seat has already tried to move this note forward, against the content it was trying to move — it is the loop's only brake, and clearing it by hand hands back a budget that exists to stop a note nothing can satisfy being rewritten forever. Rewriting the note's real content refunds that budget on its own, which is the point: an answer that changes the note is what unsticks it.
 - **`entities`** lists what the slice touches, **at most three**. Past three it is not one buildable piece — split it.
 - **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected. The console draws the keywords as a column and each quoted persona as a chip, so a first-person scenario is visibly a block with no personas in it.
 
@@ -243,6 +244,32 @@ pikku knowledge index --check   # report stale indexes without writing (CI gate)
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 
+### What to do next
+
+```bash
+pikku knowledge next            # the one thing to do next, derived from what is on disk
+```
+
+`next` is a pure read: it looks at the notes and answers with exactly one action —
+`repair-note`, `write-plan`, `ask-user`, `dispatch`, `hold`, or `idle`. Nothing has to
+be armed by whoever noticed a transition, so calling it twice is free and a state
+nobody anticipated is a missing answer rather than a run that quietly stops.
+
+Two things about the output matter if you are driving it:
+
+- **`reason` is machine wording.** It names the note, the frontmatter key and what the
+  gate wanted. Never repeat it to a person — they have not seen a note and it will read
+  as gibberish about files.
+- **`ask-user` carries a `question` as well.** That IS the version for a person: a
+  `header`, the question in the language of their app, and `options` when the answer
+  comes from a closed vocabulary (which `status:` it is, which `surface:` it is).
+  `options` is empty when the answer is free text, and an empty list means offer free
+  text — never invent choices to fill it.
+
+`hold` means a profile's own gate is holding the milestone and no seat this loop knows
+about can clear it. It names the hold and the notes it is about; what to do then
+belongs to that profile, not here.
+
 ### The milestone plan
 
 A milestone note says what the app must DO. Its **plan** — JSON beside the note, not prose — says what has to exist for it, and is what a finished build is measured against:

package/skills/pikku-kysely/SKILL.md

@@ -4,12 +4,13 @@ description: >-
   Use when WRITING KYSELY QUERIES (select/join/aggregate/insert/update/delete) inside a Pikku
   function body, or when setting up SQL database services with Kysely. Covers the query builder
   API (joins, aggregates + groupBy/having, returning, sql template, expression builder, $if,
-  transactions, jsonArrayFrom relation helpers) AND @pikku/kysely service setup (channel stores,
+  transactions, jsonArrayFrom relation helpers), HOW MANY ROUND TRIPS a function body costs and how to
+  collapse sequential awaits into one statement, AND @pikku/kysely service setup (channel stores,
   workflow services, secret services, AI storage, deployment services). TRIGGER when: writing any
   non-trivial kysely query (a join, an aggregate/count/sum, groupBy, subquery, transaction, or
   conditional query), the injected `kysely` service is used in a function body, or code uses
-  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, or the user asks
-  about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
+  PikkuKysely, KyselyChannelStore, KyselyWorkflowService, KyselySecretService, a function body
+  awaits more than one query, or the user asks about SQL setup with Pikku. DO NOT TRIGGER when: user asks about MongoDB or Redis-backed
   services (use pikku-service-backends).
 installGroups: [core]
 ---
@@ -119,6 +120,109 @@ await kysely.transaction().execute(async (trx) => {
 })
 ```
 
+## One statement, not five
+
+**Count the `await`s in the function body before you finish it.** In a deployed
+stage the database is not in the process — every terminal (`.execute()`,
+`.executeTakeFirst()`) is a network hop, and five in a row is five latencies the
+caller waits through in series. This is the single most common thing wrong with a
+generated function body, and it never shows up locally against a socket on the
+same machine.
+
+**Sequential is only correct when the second query needs the first one's
+VALUES.** Everything else is one of these four:
+
+**1. Independent reads → `Promise.all`.** Nothing about the SQL changes; they
+just stop queuing behind each other.
+
+```typescript
+// Three hops, in series
+const item = await kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst()
+const bins = await kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute()
+const moves = await kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute()
+
+// One hop's worth of latency
+const [item, bins, moves] = await Promise.all([
+  kysely.selectFrom('item').where('id','=',id).selectAll().executeTakeFirst(),
+  kysely.selectFrom('bin').where('warehouseId','=',wid).selectAll().execute(),
+  kysely.selectFrom('stockMove').where('itemId','=',id).selectAll().execute(),
+])
+```
+
+**2. Parent, then its children → `jsonArrayFrom` / `jsonObjectFrom`.** A loop
+containing an `await` is an N+1: one query per row, so the cost is the size of the
+result set rather than the size of the code. **Never `await` inside a `for`/`map`
+over rows you just fetched.** The relation helpers in the cookbook above collapse
+it into one statement that returns the nested shape your output schema already
+wants.
+
+```typescript
+// N+1 — one extra hop per warehouse
+const warehouses = await kysely.selectFrom('warehouse').selectAll().execute()
+for (const w of warehouses) {
+  w.bins = await kysely.selectFrom('bin').where('warehouseId','=',w.id).selectAll().execute()
+}
+// One hop — see NESTED DATA above
+```
+
+If the shape genuinely cannot be nested, fetch the children in **one** query with
+`where('warehouseId', 'in', warehouses.map((w) => w.id))` and group them in JS.
+Two hops beats N.
+
+**3. Read, decide, write → one write that returns.** A `select` to check
+existence followed by an `insert` is both two hops and a race — another request
+can insert between them. `returning()` and `onConflict` do it in one statement,
+and what comes back tells you which branch happened.
+
+```typescript
+// Two hops and a race
+const existing = await kysely.selectFrom('item').where('sku','=',sku).select('id').executeTakeFirst()
+if (existing) throw new ConflictError()
+await kysely.insertInto('item').values({ sku, name }).execute()
+
+// One hop, and the database arbitrates
+const created = await kysely
+  .insertInto('item')
+  .values({ sku, name })
+  .onConflict((oc) => oc.column('sku').doNothing())
+  .returning(['id', 'sku'])
+  .executeTakeFirst()
+if (!created) throw new ConflictError()
+```
+
+The same applies to fetch-then-update: `updateTable(...).where(...).returning(...)`
+in one call, and `undefined` back means the row was not there — that is your
+`NotFoundError`, not a reason for a preceding `select`. Many single-row inserts
+are one `.values([...])` with an array.
+
+**4. A read that only feeds the next query's `where` → a subquery or a CTE.**
+If the first result never reaches the response and never reaches JS, it should
+never have crossed the wire.
+
+```typescript
+// Two hops — the ids are only ever used as a filter
+const ids = await kysely.selectFrom('bin').where('warehouseId','=',wid).select('id').execute()
+const stock = await kysely.selectFrom('stock').where('binId','in', ids.map((b) => b.id)).selectAll().execute()
+
+// One hop
+const stock = await kysely
+  .selectFrom('stock')
+  .where('binId', 'in', (eb) =>
+    eb.selectFrom('bin').select('bin.id').where('bin.warehouseId', '=', wid)
+  )
+  .selectAll()
+  .execute()
+```
+
+`.with('name', (db) => ...)` builds a CTE when the same intermediate is needed
+twice inside one statement. A total alongside a page is a window function —
+`eb.fn.countAll<number>().over().as('total')` — not a second `count` query.
+
+**A transaction does NOT reduce round trips.** It adds `BEGIN` and `COMMIT` around
+whatever is inside it. Reach for it when several writes must land together or not
+at all; never as a way to make sequential queries cheaper, and never wrapped round
+reads that only needed `Promise.all`.
+
 Pikku provides SQL database services through six packages:
 
 - `@pikku/kysely` — Base service implementations (database-agnostic), the serialize plugins, `createAuditedKysely` and the `pikkuSchemas` helpers