@pikku/skills 0.12.28 → 0.12.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.28",
+  "version": "0.12.30",
   "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-services/SKILL.md

@@ -30,6 +30,16 @@ request-scoped logger or audit buffer is a wire service, and startup work that
 needs the singletons goes in `pikkuServerLifecycle` rather than in a module's
 top level.
 
+## Services the runtime injects
+
+`pikku dev` and `pikku serve` build a set of singletons before your
+`createSingletonServices` runs and hand them in as `existingServices` — among
+them `content`, a `LocalContent` storing files under `.pikku-runtime/content`
+and serving them from `/upload` and `/assets`. **You never construct these in
+`services.ts`, and their absence from that file is not evidence they are off.**
+The optional `content` block in `pikku.config.json` only overrides that
+service's paths and size limit; omitting it does not disable it.
+
 ## Pick the reference
 
 | You are…                                                                     | Read                                                         |

package/skills/pikku-wiring/references/mcp.md

@@ -166,49 +166,25 @@ export const deleteTodo = pikkuFunc({
 })
 ```
 
-## MCP Server Setup
+## Reaching the server
 
-`PikkuMCPServer` takes the server config and a logger — not your services. It
-loads the generated `mcp.gen.json`, and the bootstrap import is what registers
-your functions.
+You do not start an MCP server. `pikku dev`, `pikku serve` and a deployed app all
+mount one for you: codegen writes `.pikku/mcp/mcp.gen.json`, the runtime loads it,
+and the server is served at **`/mcp`** — so a tool you export is reachable at
+`https://<your-app-url>/mcp` with nothing else to wire. Set `mcpPath` to move it.
 
-```typescript
-// start.ts
-import { PikkuMCPServer } from '@pikku/modelcontextprotocol'
-import { createConfig, createSingletonServices } from './services.js'
-import mcpJSON from '../.pikku/mcp/mcp.gen.json' with { type: 'json' }
-import '../.pikku/pikku-bootstrap.gen.js'
-
-const config = await createConfig()
-const singletonServices = await createSingletonServices(config)
-
-const server = new PikkuMCPServer(
-  {
-    name: 'pikku-mcp-server',
-    version: '1.0.0',
-    mcpJSON,
-    capabilities: { logging: {}, tools: {}, resources: {}, prompts: {} },
-  },
-  singletonServices.logger
-)
-
-await server.init()
-
-// stdio — the transport desktop MCP clients spawn
-await server.connectStdio()
-singletonServices.logger = server.createMCPLogger()
-
-// …or streamable HTTP, for a hosted server
-const { close } = await server.connectHTTP({ port: 3000, host: '127.0.0.1' })
-```
+Two consequences worth stating outright, because both read as breakage:
 
-`capabilities` is a filter, not documentation: a surface you leave out is not
-advertised and its endpoints are never loaded, which is how you ship a tools-only
-server.
+- The mount is **conditional on there being something to serve**. An `mcp.gen.json`
+  with no tools, resources or prompts is not mounted at all, so `/mcp` 404s until
+  the first `mcp: true` function or `pikkuMCP*Func` exists.
+- There is no `wires/mcp` directory and no `mcp` block in `pikku.config.json`.
+  A tool *is* its own registration, so the absence of both is what correct MCP
+  wiring looks like — not evidence that something was missed.
 
-Over stdio the protocol owns stdout, so an ordinary console logger corrupts the
-frames — that is what `createMCPLogger()` is for. Swap the logger before
-anything logs.
+When you add a tool, tell whoever asked for it the URL. An assistant that cannot
+be pointed at an endpoint has not been connected to anything, and `/mcp` is the
+whole answer.
 
 ## Red flags
 
@@ -218,4 +194,4 @@ anything logs.
 | `uri`/`title` rejected on `pikkuMCPResourceFunc` | Those belong on `wireMCPResource`                               |
 | Resource returning `{ uri, blob, mimeType }`     | Resources are text only: `{ uri, text }`                        |
 | Client sees a tool with no description           | `mcp: true` without a `description` — check the codegen warning |
-| stdio client disconnects on the first log line   | Logger still writing to stdout; use `createMCPLogger()`         |
+| `/mcp` 404s                                      | Nothing to serve yet — the mount is skipped until one tool, resource or prompt exists |