@pikku/skills 0.12.10 → 0.12.11

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

@@ -0,0 +1,238 @@
+---
+name: pikku-build-quick
+description: >-
+  Build a working app on open-source Pikku fast — scaffold to running screens, skipping the
+  knowledge base and the milestone ladder. For spikes, throwaway demos, and ideas nobody has
+  committed to yet. TRIGGER when: the user asked for something quick, a prototype, a spike, a
+  demo of an idea, or "just get it running", or picked "Quick" from the build-mode question. DO
+  NOT TRIGGER when: the request is an unqualified "build me an X on Pikku" with no signal of
+  speed or throwaway-ness — App is the default and small or toy-sounding apps do not change that
+  (use pikku-build-app); the user wants a real product someone else will pick up (use
+  pikku-build-app); the user wants a demo of Pikku itself — one that shows off surfaces like
+  workflows, queues, realtime or i18n (use pikku-build-platform); or the user is adding a feature
+  to an app that already exists rather than building one from a fresh scaffold (use
+  pikku-feature).
+installGroups: [core]
+---
+
+# Build an app on Pikku, fast
+
+You have a scaffolded project with skills installed. Get it to working, seeded,
+signed-in screens in as few steps as possible.
+
+**What this mode deliberately skips**, and what that costs:
+
+| Skipped | Cost |
+|---|---|
+| `knowledge/` | Another agent — or you next week — cannot resume this. Nothing records *why*. |
+| Milestone planning | No build order, no per-piece proof. Fine at this size, painful past it. |
+| Design direction | It will look like the template. |
+| Refusal scenarios | Access control is asserted, not proven. |
+
+**Say this out loud to the user, once, when you finish.** A quick build that gets
+mistaken for a real one is the only way this mode does damage. §6 is the way out.
+
+## Agent Operating Procedure
+
+1. Read `AGENTS.md` at the project root before your first screen — routing slots,
+   `useNavItems()`, and the shipped component kit.
+2. Keep generated files generated. Never hand-edit `.pikku/`, `*.gen.*`, or the SDK.
+3. Run `pikku all` after touching functions, wirings or schemas. It is the gate,
+   and its criticals are real.
+
+## 1. One question, then build
+
+Ask **one** thing, and only if the original request left it open: **who uses
+it — one kind of person, or several?** Everything else you decide yourself.
+
+- **One kind** — no roles to declare. The rule is ownership: you see yours, not
+  theirs.
+- **Several** — declare a role each in §2 and keep the count honest. An invented
+  role becomes invented screens.
+
+Do not ask about design, deployment, or scope. This is the quick mode; the
+defaults are the point.
+
+## 2. Personas — 60 seconds, not optional
+
+`packages/functions/src/personas.ts` ships with a `visitor`. Add one persona per
+kind of person, plus **a second one of the primary kind** — that is what makes
+"you see yours, not theirs" observable when you click around.
+
+**One kind of person** — no `defineSystemRole` at all. Ownership is the only
+rule, and it lives in each function's `permissions`, not in a role:
+
+```typescript
+import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+
+definePersonas({
+  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+  amina: { name: 'Amina', jobTitle: 'Gardener', account: {} },
+  bilal: { name: 'Bilal', jobTitle: 'Gardener', account: {} },
+})
+```
+
+**Several kinds** — one role each, and only for the kinds the user actually
+named:
+
+```typescript
+import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
+import { defineSystemRole } from '#pikku'
+
+defineSystemRole({
+  owner: { displayName: 'Owner', description: 'Sees only their own rows', scopes: [] },
+  tenant: { displayName: 'Tenant', description: 'Sees only their own tenancy', scopes: [] },
+})
+
+definePersonas({
+  visitor: { name: 'Visitor', jobTitle: 'Synthetic health-check user', account: {} },
+  amina: { name: 'Amina', jobTitle: 'Owner', roles: ['owner'], account: {} },
+  bilal: { name: 'Bilal', jobTitle: 'Owner', roles: ['owner'], account: {} },
+  chidi: { name: 'Chidi', jobTitle: 'Tenant', roles: ['tenant'], account: {} },
+})
+```
+
+Two owners in both examples, deliberately: one owner cannot demonstrate that
+owners are separated from each other.
+
+- **Keep `visitor`.** The shipped scenarios name `actors.visitor`; removing it
+  fails `pikku all` and nothing you write after that registers.
+- **One `definePersonas` call for the whole project.**
+- **Never write an email address** — each is derived from the persona id and
+  `scenarios.emailDomain` in `pikku.config.json`.
+- `roles` is typechecked against `defineSystemRole`; an undeclared role is a
+  build error.
+
+## 3. Build
+
+Run `bunx --bun pikku bootstrap` once first. It wires the `#pikku` import alias
+codegen depends on; without it your first `db migrate` fails with
+`Cannot find package '#pikku'`.
+
+Then, in this order — it is the order codegen depends on:
+
+1. **Migration** — SQL in `db/sqlite/`, numbered on from what is there. Apply
+   with `bunx --bun pikku db migrate`, which regenerates the Kysely types.
+2. **Seed** — rows in `db/sqlite-dev-seed.sql`. There is no seed command:
+   `bunx --bun pikku db reset` wipes, migrates and seeds in one go, and is the
+   only thing that applies the file. It always starts from a wiped database, so
+   the file is plain `INSERT`s — no `ON CONFLICT DO NOTHING`. **Be generous, and
+   seed rows for both personas.** An empty app demos badly, and you cannot see a
+   layout break against zero rows.
+3. **Functions** — one `pikkuFunc` per `*.function.ts`, `expose: true`. Pikku
+   generates the typed RPC client and React Query hooks; you do NOT write HTTP
+   routes. `wireHTTP` only for a real REST shape (a third-party webhook).
+4. `bunx --bun pikku all`
+5. **UI** — pages in `apps/app/src/pages/`, one route file each in
+   `apps/app/src/routes/`, calling `usePikkuQuery` / `usePikkuMutation` from
+   `@project/functions-sdk/pikku/api.gen`. Compose `@/components/<Name>` —
+   `PageHeader`, `Panel`, `StatGrid`, `DataTable` — rather than hand-rolling.
+   Register each screen in `useNavItems()`; that one file feeds the desktop
+   sidebar and the phone navigation.
+
+**Aim for two or three real entities and three screens** — a working surface, a
+detail view, and somewhere to land. One table with a form on it is not an app,
+and it is not faster to build.
+
+Rules that stay non-negotiable even here, because breaking them costs more time
+than they save:
+
+- Input and output types come from `input:`/`output:` zod schemas. Never generic
+  type params, never an inline return type. The schema is the type.
+- Permission checks go in the `permissions` field, never the function body. An
+  exposed function with no session and no permission is reachable by anyone over
+  `POST /rpc/:rpcName` (PKU574).
+- No `process.env` inside a function — use the injected `variables` / `secrets`
+  services.
+- A `z.date()` **input** arrives over RPC as an ISO string, not a `Date`.
+  `new Date(value)` before calling date methods, or it throws
+  `.getTime is not a function` at runtime.
+- On SQLite, `db/annotations.ts` is where a `DATETIME` becomes a `Date` and a
+  `JSON` column becomes a typed object. Without an entry they are `string` and
+  `unknown` (PKU481). Add the annotation rather than casting.
+- Surface errors inline next to the control that failed. No empty catch.
+- Every user-facing string is a translation key, not a literal. It is one extra
+  keystroke now and a rewrite later.
+- Never hardcode a host or port — the API base resolves to same-origin `/api`.
+
+Then run it:
+
+```sh
+bun run prebuild && bun run dev
+```
+
+API on :3000, app on the port vite prints. A frontend against a dead API looks
+exactly like an app bug, so if every request fails, check both came up.
+
+## 4. Look at it — actually
+
+Sign up, click every screen. **HTTP 200 is not evidence:** pages are
+client-rendered, so the server returns 200 with an empty shell and a page whose
+component throws still looks fine to `curl`. Open a browser, or drive it
+headlessly and assert on rendered text.
+
+**Screenshot at 390px too.** A layout that is fine at 1440 routinely breaks on a
+phone — an overflowing table, a row of buttons wrapped into a pile, a modal
+taller than the viewport. It is the most likely width your demo gets opened at.
+
+If you have five spare minutes, `npx impeccable install` (Node 22.18+) scores
+each screen against interaction heuristics and names what is wrong. Feed it
+screenshots, not source. It will polish the default look; it will not give the
+app a look — that is `pikku-build-app` §8a.
+
+## 5. One smoke scenario
+
+Not the full ladder — one journey, end to end, as a real persona, so the app has
+at least one thing that stays true.
+
+```typescript
+import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+
+export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>({
+  title: 'An owner creates a thing and sees it',
+  tags: ['scenario', 'smoke'],
+  func: async (_services, _data, { scenario, actors }) => {
+    const row = await scenario.do('creates', 'createThing', { name: 'first' }, { actor: actors.amina })
+    await scenario.then('sees it listed', 'thingShowsInList', { id: row.id }, { actor: actors.amina })
+    return { id: row.id }
+  },
+})
+```
+
+- **`do` takes an RPC name; `given`/`when`/`then` take a declared
+  `pikkuScenarioStep`.** An RPC name in a `then` will not resolve.
+- **Every scenario must assert.** A ladder with no `then` is a PKU680 critical —
+  it fails `pikku all`, stopping codegen rather than a test.
+- **Add `SCENARIO_ACTOR_SECRET` to `.env`.** `bun run dev` writes that file with
+  only a `BETTER_AUTH_SECRET`; without the actor secret
+  `/api/auth/sign-in/actor` is disabled and every scenario fails at sign-in, for
+  a reason that reads like an auth bug.
+- **There is no state reset** — scope what you create to unique ids.
+
+Keep the three shipped scenarios in `packages/functions/test/scenarios/` green.
+
+```sh
+bunx --bun pikku scenario run local --spawn
+```
+
+## 6. Hand it over honestly
+
+Tell the user, in one short paragraph: what runs, what it is seeded with, and
+that this is a quick build — no knowledge base, no milestones, no design pass,
+access control clicked-through rather than proven.
+
+**Upgrading to a real build is additive, not a rewrite.** If they want it, switch
+to `pikku-build-app` and do this, in order:
+
+1. Write `knowledge/` for what already exists — `entities/` for what you built,
+   `decisions/` for what you chose silently, `questions/` for what you guessed
+   at. Then `pikku knowledge index && pikku knowledge validate`.
+2. Backfill a milestone note per screen you built, at `status: built`, each with
+   its gherkin block.
+3. Write the refusal scenarios — the ones proving one persona cannot reach
+   another's rows. This is the gap that matters most.
+4. Then pick up `pikku-build-app` at its §4 (apps) or §5 (milestones) for
+   anything new.
+
+Nothing built here has to be thrown away to do that — which is the whole reason
+this mode is allowed to skip those steps in the first place.

package/skills/pikku-cli/SKILL.md

@@ -41,7 +41,7 @@ All three factories come from `#pikku` (the generated types re-export
 loses your project's service and middleware types.
 
 ```typescript
-import { wireCLI } from '#pikku'
+import { wireCLI } from '#pikku/cli'
 
 wireCLI({
   program: string,              // Program name (e.g. 'todos')
@@ -65,7 +65,7 @@ wireCLI({
 ### `pikkuCLICommand(config)`
 
 ```typescript
-import { pikkuCLICommand } from '#pikku'
+import { pikkuCLICommand } from '#pikku/cli'
 
 pikkuCLICommand({
   parameters?: string,          // Positional args (e.g. '<text>', '<username> <email>')
@@ -111,7 +111,7 @@ How the parser reads them, which is worth knowing before you name one:
 ### `pikkuCLIRender(fn)`
 
 ```typescript
-import { pikkuCLIRender } from '#pikku'
+import { pikkuCLIRender } from '#pikku/cli'
 
 const renderer = pikkuCLIRender<OutputType>((services, data) => {
   // Format and print output to terminal
@@ -122,10 +122,10 @@ const renderer = pikkuCLIRender<OutputType>((services, data) => {
 ### Wire object (`wire.cli`)
 
 ```typescript
-wire.cli.program   // program name
-wire.cli.command   // string[] — the resolved command path
-wire.cli.data      // all positionals and options, merged
-wire.cli.channel   // the channel when served remotely (see below)
+wire.cli.program // program name
+wire.cli.command // string[] — the resolved command path
+wire.cli.data // all positionals and options, merged
+wire.cli.channel // the channel when served remotely (see below)
 ```
 
 ## Usage Patterns

package/skills/pikku-cli/references/complete-example.md

@@ -32,7 +32,7 @@ export const deleteUser = pikkuFunc({
 })
 
 // wirings/cli.wiring.ts
-import { wireCLI, pikkuCLICommand, pikkuCLIRender } from '#pikku'
+import { wireCLI, pikkuCLICommand, pikkuCLIRender } from '#pikku/cli'
 
 const userRenderer = pikkuCLIRender<{ user: User }>((_services, { user }) => {
   console.log(`Created user: ${user.username} (${user.email}) [${user.role}]`)

package/skills/pikku-concepts/SKILL.md

@@ -236,7 +236,9 @@ await server.start()
 
 Run `npx pikku all` to generate:
 
-- `pikku-types.gen.ts` — Typed function factories and wiring functions
+- one directory per wiring (`function/`, `http/`, `workflow/`, …), each with an
+  `index.ts` reached as `#pikku/<name>` — typed function factories and wiring
+  functions, split so an app pulls in only the wirings it uses
 - `pikku-fetch.gen.ts` — Type-safe HTTP client
 - `pikku-websocket.gen.ts` — Type-safe WebSocket client
 - `pikku-bootstrap.gen.ts` — Runtime initialization (auto-imports all wirings)
@@ -271,7 +273,8 @@ src/
 ├── middleware.ts         # Middleware definitions (see pikku-security)
 ├── permissions.ts       # Permission definitions (see pikku-security)
 └── .pikku/              # Generated (gitignored)
-    ├── pikku-types.gen.ts
+    ├── function/        # #pikku/function
+    ├── http/            # #pikku/http
     ├── pikku-fetch.gen.ts
     └── pikku-bootstrap.gen.ts
 ```

package/skills/pikku-concepts/references/concept-mapping.md

@@ -472,7 +472,7 @@ if (!canEdit(user, todo)) {
 **Pikku:**
 
 ```typescript
-import { NotFoundError, ForbiddenError } from '@pikku/core/errors'
+import { NotFoundError, ForbiddenError } from '#pikku/error'
 
 const updateTodo = pikkuFunc(async (services, { id, title }, wire) => {
   const todo = services.todoStore.getTodo(id)

package/skills/pikku-config/SKILL.md

@@ -75,7 +75,9 @@ greppable. Call it at the point the value reaches the thing that needs it:
 ```typescript
 // services.ts — allowed
 const createSingletonServices = pikkuServices(async (config, { secrets }) => ({
-  stripe: new StripeService((await secrets.getSecret('STRIPE_CONFIG')).reveal()),
+  stripe: new StripeService(
+    (await secrets.getSecret('STRIPE_CONFIG')).reveal()
+  ),
 }))
 
 // functions/*.ts — ask the service, never the secret store
@@ -162,7 +164,7 @@ defineCredential({
 
 ### Usage
 
-```typescript
+````typescript
 // Per-user API key — no oauth2 block
 defineCredential({
   name: 'stripe',
@@ -208,7 +210,7 @@ export const createWireServices = pikkuWireServices(async (_services, wire) => {
 export const postMessage = pikkuFunc({
   func: async ({ slack }, { channel, text }) => slack.postMessage(channel, text),
 })
-```
+````
 
 A `wire` credential resolves per user, so an unconnected user hits
 `MissingCredentialError` rather than silently acting as someone else; a

package/skills/pikku-deploy-azure/SKILL.md

@@ -59,10 +59,11 @@ import { createAzureHandler } from '@pikku/azure-functions'
 import { createConfig, createSingletonServices } from './services.js'
 import './.pikku/pikku-bootstrap.gen.js'
 
-const handlers = createAzureHandler(
-  { createConfig, createSingletonServices },
-  ['fetch', 'queue', 'scheduled']
-)
+const handlers = createAzureHandler({ createConfig, createSingletonServices }, [
+  'fetch',
+  'queue',
+  'scheduled',
+])
 
 app.http('api', {
   methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],

package/skills/pikku-emails/SKILL.md

@@ -36,8 +36,8 @@ generated output is never edited by hand.
 ```jsonc
 // pikku.config.json
 {
-  "emailTemplatesDir": "emails",   // relative to rootDir; omit to disable emails
-  "outDir": ".pikku"               // gen lands in <outDir>/email/
+  "emailTemplatesDir": "emails", // relative to rootDir; omit to disable emails
+  "outDir": ".pikku", // gen lands in <outDir>/email/
 }
 ```
 
@@ -121,9 +121,9 @@ render with sample data and read the result rather than trusting that it compile
 
 ```ts
 const rendered = renderEmailTemplate({
-  name: 'verify-email',        // EmailTemplateName (autocompleted)
-  locale: 'en',                // optional, defaults to 'en'
-  data: { verifyUrl: url },    // EmailTemplateVariables<'verify-email'>
+  name: 'verify-email', // EmailTemplateName (autocompleted)
+  locale: 'en', // optional, defaults to 'en'
+  data: { verifyUrl: url }, // EmailTemplateVariables<'verify-email'>
 })
 // rendered: { name, locale, subject, html, text?, variables, hash }
 ```

package/skills/pikku-fabric/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-fabric
-description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
+description: 'Build and convert apps for the Pikku Fabric platform. Covers SQLite/libSQL database setup with Kysely, fabric project layout, deploy provider config, `fabric.config.json`, and the pikku-verify workflow. TRIGGER when: user is working on a Fabric-hosted Pikku project, converting an app to Fabric format, or asking about Fabric deployment, database, or project conventions. TRIGGER when: user asks about a `pikku fabric validate` finding, including app-missing-actor-quick-login. DO NOT TRIGGER when: user is working on a generic (non-Fabric) Pikku deployment — use pikku-deploy-cloudflare, pikku-deploy-fastify, etc. instead.'
 installGroups: [fabric]
 ---
 
@@ -115,7 +115,7 @@ and refuses a database outside the runtime directory. Anything a real environmen
 needs — accounts, role grants — is provisioning, not seeding, and belongs in
 `pikku persona sync` or a migration.
 
-A Better Auth app has a second constraint: the plugins you enable (`admin()`,
+A Better Auth app has a second constraint: the plugins you enable (`ban()`,
 `actor()`, …) each declare columns, and `pikku db migrate` refuses to run while
 the applied schema is missing any of them. `pikku db generate` writes the
 migration that closes the gap.
@@ -311,13 +311,37 @@ Always call the `pikku-verify` tool after modifying functions, wirings, or schem
 
 The output card shows whether any breaking changes were detected.
 
+### `app-missing-actor-quick-login-<app>`
+
+The `fabric validate` finding people most often misread. It fires when an app has
+a **login screen** but no dev actor switcher, and it is not a style nit: a sandbox
+reviewer has no seed password, so without the control they are locked out of the
+app they were asked to look at.
+
+Satisfy it with `<DevActorSwitcher />` from `@pikku/mantine/dev`, or with your
+own UI built on `useDevActors()` from `@pikku/react` — validate accepts either
+call site as evidence, so custom rendering passes. See **pikku-react** for the
+props and **pikku-scenario** for where the actor list comes from.
+
+The validator also accepts the shapes that predate the package — a hand-rolled
+`signInAsActor()` or a literal `POST /auth/sign-in/actor` — so an older app does
+not fail the build. **Treat that as a grace period, not the target: migrate those
+to `<DevActorSwitcher />`.** The hand-copied version is exactly the duplication
+the package exists to remove, and the copies drift — the ones that prompted this
+had already diverged on the `import.meta.env.DEV` gate that keeps the shared
+secret out of production bundles.
+
+Do **not** satisfy it with Better Auth's `/dev/quick-login`. That is a different
+endpoint with a different purpose — one fixed admin, not the declared personas —
+and it does not clear this rule.
+
 ## Hard rules
 
 These apply in every Fabric app:
 
 - **No `process.env`** — use `variables.get('NAME')` and `secrets.getSecret('NAME')`. Declare with `defineVariable` / `defineSecret`.
 - **No `as any`** — fix types properly.
-- **No generic `Error`** — throw `NotFoundError`, `ConflictError`, `BadRequestError`, `UnauthorizedError` from `@pikku/core/errors`.
+- **No generic `Error`** — throw `NotFoundError`, `ConflictError`, `BadRequestError`, `UnauthorizedError` from `#pikku/error`.
 - **No auth checks in function bodies** — use `permissions:` field on the function config with a `pikkuPermission` factory.
 - **No hand-editing `.pikku/db/schema.gen.ts`** — write a migration and re-run `pikku db migrate`.
 - **One runtime unit per file** — never define multiple functions/workflows in a single source file.

package/skills/pikku-fabric-debug/SKILL.md

@@ -87,7 +87,7 @@ without it, even though the flag reads as optional.
 pikku fabric status     # active + in-flight deployment, per stage, with gitSha
 ```
 
-Check this *before* deep-diving. A stage still serving an older `gitSha`, or a
+Check this _before_ deep-diving. A stage still serving an older `gitSha`, or a
 deploy stuck in flight, explains a whole class of "my fix did nothing".
 
 ## Known gaps — do not misread these as bugs in your app

package/skills/pikku-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-feature
-description: 'Drive create-a-feature work for a Pikku project: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "build a todo app", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, or asks about Pikku concepts (use pikku-concepts).'
+description: 'Drive create-a-feature work inside a Pikku project that already exists: discover project context, work on a feature branch, implement + verify + commit, and ask the user to review via the diff. TRIGGER when: the user asks to "create a feature", "add X to my Pikku project", "wire up a new endpoint", or anything that implies turning a natural-language request into Pikku functions/wirings/migrations within a working app. DO NOT TRIGGER when: the user asks for a one-off code edit in an existing function, asks about Pikku concepts (use pikku-concepts), or is building a whole app from a fresh scaffold rather than extending one (use pikku-build-app, or pikku-build-quick / pikku-build-platform).'
 installGroups: [core]
 allowed-tools: Bash(yarn pikku meta *), Bash(yarn pikku all *), Bash(yarn tsc), Bash(git status *), Bash(git diff *), Bash(git switch *), Bash(git checkout *), Bash(git checkout -b *), Bash(git add *), Bash(git commit *), Bash(git log *), Bash(git branch *)
 argument-hint: '<feature description>'
@@ -121,7 +121,7 @@ in-app features don't.
   queue-dispatched.
 - **Auth checks belong on the function or wiring**, not in function bodies.
   Use the `permissions` field with a `pikkuPermission` factory.
-- **Throw typed errors** from `@pikku/core/errors` — `NotFoundError`,
+- **Throw typed errors** from `#pikku/error` — `NotFoundError`,
   `ConflictError`, `BadRequestError`. Never bare `Error`.
 - **Migrations are inline SQL files** in the project's migrations dir
   (typically `sql/`). Use a numbered prefix matching existing files.
@@ -141,8 +141,9 @@ Some patterns vary by project; **read a neighbour file before writing**:
   `CreateTodoOutput`) passed to `input`/`output` on the func config — vs
   generic-typed config. Schema name **must match codegen expectations** (the
   exported const name = the schema name in generated `.gen.json`).
-- **Imports**: usually `'#pikku'` for `pikkuFunc` / `pikkuSessionlessFunc`
-  etc. Copy what neighbours do.
+- **Imports**: `#pikku` is a namespace, not a module — one subpath per wiring.
+  `pikkuFunc` / `pikkuSessionlessFunc` come from `'#pikku/function'`, `wireHTTP`
+  from `'#pikku/http'`. Copy what neighbours do.
 - **Service usage**: e.g. `kysely`, `redis`. Look at how an existing function
   destructures services from its first arg. **Check `application-types.d.ts`**
   to see whether services like `kysely` are typed (`Kysely<DB>`) or untyped

package/skills/pikku-http/SKILL.md

@@ -38,7 +38,7 @@ Follow existing patterns you find (naming, tag usage, file organization). See `p
 
 ## API Reference
 
-All three come from `#pikku` (the generated `.pikku/pikku-types.gen.js`), which
+All three come from `#pikku/http` (the generated `.pikku/http/index.ts`), which
 binds them to your project's service, session and middleware types. The
 `@pikku/core/http` versions are the unbound generics — they compile, but you
 lose the typing that makes the wiring worth having.
@@ -59,7 +59,7 @@ addHTTPMiddleware('*', [authBearer()]) // All routes
 addHTTPMiddleware('/api/*', [rateLimit()]) // Pattern match
 ```
 
-> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-permissions`), or app-wide via `addGlobalPermission`. Tags/patterns are for *middleware* only now.
+> HTTP-route-level permissions (`addHTTPPermission`, a `permissions` field on the wiring) were removed in #972. Declare authorization on the function definition (`pikkuFunc({ permissions })`, see `pikku-permissions`), or app-wide via `addGlobalPermission`. Tags/patterns are for _middleware_ only now.
 
 ## Data Flow
 
@@ -211,7 +211,7 @@ Functions live in their own files (one per file) and supply behavior + `permissi
 
 ```typescript
 // functions/books.functions.ts
-import { pikkuFunc, pikkuSessionlessFunc } from '#pikku'
+import { pikkuFunc, pikkuSessionlessFunc } from '#pikku/function'
 
 export const listBooks = pikkuSessionlessFunc({
   title: 'List Books',
@@ -226,7 +226,7 @@ export const getBook = pikkuFunc({
 })
 
 // wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
-import { addHTTPMiddleware } from '#pikku'
+import { addHTTPMiddleware } from '#pikku/http'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])

package/skills/pikku-http/references/http-options.md

@@ -4,19 +4,19 @@
 
 Wire a single function to an HTTP endpoint. Import from `#pikku`.
 
-| Option | Type | Notes |
-| --- | --- | --- |
-| `method` | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head' \| 'options'` | HTTP verb |
-| `route` | `string` | e.g. `/books/:bookId` — `:params` become `data` fields |
-| `func` | `PikkuFunc` | The function to call |
-| `auth?` | `boolean` | Override default auth (`true` = require session) |
-| `tags?` | `string[]` | For grouping, middleware targeting |
-| `middleware?` | `PikkuMiddleware[]` | Per-route middleware |
-| `sse?` | `boolean` | Enable Server-Sent Events — **`method: 'get'` only** |
-| `query?` | `Array<keyof In>` | **`method: 'post'` only** — input fields also read from the query string |
-| `contentType?` | `'xml' \| 'json'` | Response content type |
-| `timeout?` | `number` | Request timeout in ms |
-| `headers?` | `HTTPHeadersSchema` | Expected headers schema |
+| Option         | Type                                                                     | Notes                                                                    |
+| -------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `method`       | `'get' \| 'post' \| 'put' \| 'patch' \| 'delete' \| 'head' \| 'options'` | HTTP verb                                                                |
+| `route`        | `string`                                                                 | e.g. `/books/:bookId` — `:params` become `data` fields                   |
+| `func`         | `PikkuFunc`                                                              | The function to call                                                     |
+| `auth?`        | `boolean`                                                                | Override default auth (`true` = require session)                         |
+| `tags?`        | `string[]`                                                               | For grouping, middleware targeting                                       |
+| `middleware?`  | `PikkuMiddleware[]`                                                      | Per-route middleware                                                     |
+| `sse?`         | `boolean`                                                                | Enable Server-Sent Events — **`method: 'get'` only**                     |
+| `query?`       | `Array<keyof In>`                                                        | **`method: 'post'` only** — input fields also read from the query string |
+| `contentType?` | `'xml' \| 'json'`                                                        | Response content type                                                    |
+| `timeout?`     | `number`                                                                 | Request timeout in ms                                                    |
+| `headers?`     | `HTTPHeadersSchema`                                                      | Expected headers schema                                                  |
 
 `sse` and `query` are constrained by the config union rather than by a runtime
 check, so a `sse: true` on a `post` fails to typecheck rather than silently

package/skills/pikku-i18n/SKILL.md

@@ -142,7 +142,8 @@ The wrapper alternative — a module that walks the namespace and pipes each mes
 
   `packages/console` is the one place in this repo that still wraps it, in `src/i18n/messages.ts`, to keep the debug mask (`█`) it carried over from i18next. That wrapper is a leftover, not a pattern — the generated-locale approach above is how a new app gets the same masking without touching every export. Don't copy it.
 
-  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message *function* and call it — the map is type-checked, a string is not.
+  The `mKey`/`mList` runtime resolvers that used to live beside it are **gone**, and must not come back. `mList` resolved indexed `prefix.0` keys that no longer exist; `mKey` took a computed string, which is exactly the type safety Paraglide exists to provide. Where a key really is dynamic, map the discriminant to a message _function_ and call it — the map is type-checked, a string is not.
+
 - Don't re-resolve messages by string key or re-implement `{param}` interpolation. A key-string resolver turns a missing key back into silent runtime text, surrendering the type safety that is the entire reason to use Paraglide.
 - Don't reach for i18next/react-i18next or a runtime-fetch translation loader — Paraglide's compiled functions are the whole delivery mechanism.
 - Don't tokenize backend error messages or logs here — those are not frontend display strings.

package/skills/pikku-info/SKILL.md

@@ -29,7 +29,7 @@ Use the `pikku info` CLI commands to inspect this Pikku project. Run the command
 
 There are exactly four subcommands — `functions`, `tags`, `middleware`,
 `permissions`. Routes, channels, schedulers and queues are not separate
-subcommands; they show up as the *transport* column of `info functions --verbose`.
+subcommands; they show up as the _transport_ column of `info functions --verbose`.
 
 ## Available Commands
 

package/skills/pikku-knowledge/SKILL.md

@@ -66,7 +66,7 @@ Frontmatter fields:
 
 | Field         | Meaning                                                                                                                 |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `type`        | **The only required field.** `slice`, `entity`, `decision`, `note`, `overview`. Lowercase — gates compare it literally. |
+| `type`        | **The only required field.** `slice` — or `milestone`, when the project's own `knowledge/index.md` names the section that way; `validate` accepts both, so follow the scaffold rather than this list. Then `entity`, `decision`, `note`, `overview`. Lowercase — gates compare it literally. |
 | `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
 | `description` | One line, used as the note's subtitle in a section index.                                                               |
 | `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
@@ -193,19 +193,19 @@ It is a **summary, not the note** — the argument continues in prose underneath
 
 **Every kind resolves.** That is the whole design: a kind that cannot be checked lets notes accumulate references nothing validates, and the graph rots into fiction exactly where it looks most authoritative.
 
-| Kind        | An id is                                           | Where it resolves                                                                 |
-| ----------- | -------------------------------------------------- | --------------------------------------------------------------------------------- |
-| `func:`     | a function id                                      | generated function meta                                                           |
-| `workflow:` | a workflow name                                    | generated workflow meta                                                           |
-| `schema:`   | a schema name                                      | generated schemas                                                                 |
-| `http:`     | a route, `method:route`, or the function behind it | generated http wirings                                                            |
-| `queue:`    | a queue name                                       | generated queue wirings                                                           |
-| `cron:`     | a scheduled task name                              | generated scheduler wirings                                                       |
-| `channel:`  | a channel name                                     | generated channel meta                                                            |
-| `table:`    | a table name                                       | the generated db schema                                                           |
-| `addon:`    | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                         |
+| Kind        | An id is                                           | Where it resolves                                                                          |
+| ----------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `func:`     | a function id                                      | generated function meta                                                                    |
+| `workflow:` | a workflow name                                    | generated workflow meta                                                                    |
+| `schema:`   | a schema name                                      | generated schemas                                                                          |
+| `http:`     | a route, `method:route`, or the function behind it | generated http wirings                                                                     |
+| `queue:`    | a queue name                                       | generated queue wirings                                                                    |
+| `cron:`     | a scheduled task name                              | generated scheduler wirings                                                                |
+| `channel:`  | a channel name                                     | generated channel meta                                                                     |
+| `table:`    | a table name                                       | the generated db schema                                                                    |
+| `addon:`    | `@pikku/addon-x` or bare `x`                       | the manifests that declare the dependency                                                  |
 | `scope:`    | a scope name                                       | the `scopes:` a function gates itself with, plus the scopes a `defineSystemRole()` confers |
-| `persona:`  | a persona name                                     | `definePersonas()`                                                                |
+| `persona:`  | a persona name                                     | `definePersonas()`                                                                         |
 
 Ids are case-sensitive: `createEntry` is not `createentry`.