@pikku/skills 0.12.20 → 0.12.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.20",
+  "version": "0.12.22",
   "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

@@ -146,7 +146,7 @@ second argument is always present — an addon never falls back to its own logge
 variables or secrets; the consuming app supplies them:
 
 ```typescript
-import { pikkuAddonServices } from '#pikku/addon/setup'
+import { pikkuAddonServices } from '#pikku/setup'
 
 export const createSingletonServices = pikkuAddonServices(
   async (config, { secrets, logger }) => {
@@ -167,7 +167,7 @@ config object.
 Define per-request services for an addon package (created fresh per HTTP request, queue job, etc.):
 
 ```typescript
-import { pikkuAddonWireServices } from '#pikku/addon/setup'
+import { pikkuAddonWireServices } from '#pikku/setup'
 
 export const createWireServices = pikkuAddonWireServices(
   async (singletonServices, wire) => {
@@ -195,7 +195,7 @@ This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json
 
 ```typescript
 // src/services.ts
-import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/addon/setup'
+import { pikkuAddonServices, pikkuAddonWireServices } from '#pikku/setup'
 import { TodoStore } from './todo-store.service.js'
 
 export const createSingletonServices = pikkuAddonServices(async () => {
@@ -213,14 +213,15 @@ export const createWireServices = pikkuAddonWireServices(
 
 ### Functions
 
-An addon generates its whole tree under `#pikku/addon/*`, so it authors against
-`#pikku/addon/function`, `#pikku/addon/http` and so on. An application's leaves
-stay flat, which is what stops a linked addon resolving against its host.
+An addon's generated tree roots at `.pikku/addon/`, but its `imports` map points
+`#pikku/*` there, so it authors against the same subpaths an application does —
+`#pikku/function`, `#pikku/http`. The `addon` segment is the package's own
+business, never part of a specifier.
 
 ```typescript
 // src/functions/addTodo.function.ts
 import { z } from 'zod'
-import { pikkuSessionlessFunc } from '#pikku/addon/function'
+import { pikkuSessionlessFunc } from '#pikku/function'
 
 const AddTodoInput = z.object({ title: z.string() })
 const AddTodoOutput = z.object({ id: z.string(), title: z.string() })

package/skills/pikku-better-auth/SKILL.md

@@ -237,12 +237,12 @@ Banning is the one capability with a schema requirement, and it has its own
 small plugin:
 
 ```typescript
-import { ban } from '@pikku/better-auth'
+import { pikkuBan } from '@pikku/better-auth'
 
-betterAuth({ plugins: [ban()] })
+betterAuth({ plugins: [pikkuBan()] })
 ```
 
-`ban()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
+`pikkuBan()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
 create a session for a banned user, lapsing an expired ban as it goes. It makes
 no authorization decision — who may ban is decided by `admin:users:ban` — so it
 never needs to know about scopes or roles.
@@ -252,22 +252,28 @@ never needs to know about scopes or roles.
 Five, all imported from the package root and passed to `betterAuth({ plugins })`
 like any other. None is automatic — an app wires the ones it needs.
 
-| Plugin              | Plugin `id`        | Adds                                                                    | Use it when                                                   |
-| ------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `ban()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
-| `actor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
-| `credentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
-| `delegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
-| `fabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+| Plugin                   | Plugin `id`        | Adds                                                                    | Use it when                                                   |
+| ------------------------ | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `pikkuBan()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
+| `pikkuActor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
+| `pikkuCredentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
+| `pikkuDelegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
+| `pikkuFabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+
+Every one carries a `pikku` prefix, because a `plugins: [...]` array mixes these
+with better-auth's own and a bare `actor()` next to `organization()` says
+nothing about where it came from. The unprefixed names — `ban`, `actor`,
+`credentialOAuth`, `delegatedAuth`, `fabric` — are still exported as deprecated
+aliases, so existing apps keep working.
 
 The plugin's `id` is what better-auth stores; the **export name** is what the
 inspector reads off your `plugins` array and what generated metadata is keyed
-by, so the two differ for `ban` and `delegatedAuth`.
+by, so the two differ for every one of them.
 
-#### `credentialOAuth()` — link API credentials, not identities
+#### `pikkuCredentialOAuth()` — link API credentials, not identities
 
 ```typescript
-credentialOAuth({
+pikkuCredentialOAuth({
   config: [
     {
       providerId: 'github',
@@ -308,10 +314,10 @@ by construction. Tokens land in better-auth's `account` table, so
 An undeclared `providerId` is a 404; an anonymous caller a 401; a refused
 singleton a 403 that leaves no platform user behind.
 
-#### `delegatedAuth()` — the upstream API is the identity provider
+#### `pikkuDelegatedAuth()` — the upstream API is the identity provider
 
 ```typescript
-delegatedAuth({
+pikkuDelegatedAuth({
   authenticate: async ({ email, password, apiKey }) => upstream.login(...),
   storeCredential: (userId, identity) =>
     credentialService.set('acme', identity.credential, userId),
@@ -338,10 +344,10 @@ a warning and the user still gets in.
 `storeCredential` failing, by contrast, **fails the sign-in**: every proxied
 call would be dead anyway.
 
-#### `fabric()` — control-plane operator sign-in
+#### `pikkuFabric()` — control-plane operator sign-in
 
 ```typescript
-fabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
+pikkuFabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
 ```
 
 `POST /sign-in/fabric` verifies a short-lived RS256 token that the Fabric
@@ -468,9 +474,9 @@ someone" means **a particular kind of user** rather than one fixed admin.
 Register it explicitly — it is not automatic:
 
 ```typescript
-import { actor } from '@pikku/better-auth'
+import { pikkuActor } from '@pikku/better-auth'
 
-plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
+plugins: [pikkuActor({ secret: SCENARIO_ACTOR_SECRET })]
 ```
 
 `POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
@@ -510,9 +516,9 @@ an `actor: true` row only under `pikku dev`. With the opt-in set, a stage signs
 in as the personas the deployment provisioned when it started and refuses
 everything else (`No actor account exists for that address`), so holding the
 secret on such a stage does not let anyone invent identities. Those rows are
-written by `provisionPersonas` from `@pikku/better-auth`, called in the server's
-own lifecycle, so provisioning needs no actor secret and works on a stage whose
-endpoint is shut.
+written by the fabric plugin when an operator asks to act as an address the
+stage has no account for, so provisioning needs no actor secret and works on a
+stage whose endpoint is shut.
 
 **`SCENARIO_ACTOR_SECRET` is a credential as powerful as the most privileged
 persona.** Provisioning grants declared roles to actor accounts, so an
@@ -538,30 +544,46 @@ This is the endpoint `pikku scenario` signs its actors in through, and the one
 the frontend dev switcher posts to — see `pikku-scenario` for declaring the
 actors and `pikku-react` for `useDevActors()`.
 
-### Provisioning personas (`provisionPersonas`)
+### Provisioning personas
 
-Anywhere but `pikku dev`, the accounts have to exist before anyone signs in.
-The deployment creates them itself, from its own lifecycle:
+Anywhere but `pikku dev`, the accounts have to exist before anyone signs in. The
+stage creates them itself, from the personas you hand `pikkuFabric`:
 
 ```ts
-import { provisionPersonas } from '@pikku/better-auth'
+import { pikkuFabric } from '@pikku/better-auth'
 import {
   personaConfigs,
   personaEnvironments,
 } from '#pikku/pikku-personas.gen.js'
 
-await provisionPersonas(singletonServices, {
-  personas: personaConfigs,
-  environments: personaEnvironments,
+pikkuFabric({
+  publicKey,
+  audience,
+  scopeService,
+  personas: {
+    personas: personaConfigs,
+    environments: personaEnvironments,
+  },
 })
 ```
 
-It runs where the database already is, which is the point: the CLI has no
-connection to a deployed environment's database — it resolves one from the local
-project config — so a `pikku persona sync staging` that wrote rows would write
-them to whatever database the checkout happened to point at. `pikku persona sync
-<environment>` still exists, and reports who that environment will provision and
-why anyone was skipped, which is what you run _before_ the deploy.
+There is nothing else to call and nothing to schedule. The plugin's operator
+endpoint resolves the address the caller wants to act as; a miss provisions the
+declaration and looks again. On a stage that already holds the persona that is
+one query, and the pass only runs when there is genuinely something absent to
+create.
+
+**Do not reach for `pikkuServerLifecycle`'s `afterStart` for this.** That hook is
+invoked by `pikku serve` and `pikku dev` and by nothing else — no deploy runtime
+calls it — so a stage on Workers or a serverless target that provisioned from
+`afterStart` provisioned nothing, and every persona signed in holding no roles.
+
+Provisioning runs where the database already is, which is the point: the CLI has
+no connection to a deployed environment's database — it resolves one from the
+local project config — so a `pikku persona sync staging` that wrote rows would
+write them to whatever database the checkout happened to point at. `pikku persona
+sync <environment>` still exists, and reports who that environment will provision
+and why anyone was skipped, which is what you run _before_ the deploy.
 
 It creates missing accounts as `actor: true`, applies the roles each persona
 declares, and is additive — it never revokes. `PIKKU_ENV` (or an explicit
@@ -577,15 +599,20 @@ open. By default provisioning warns about those accounts and changes nothing.
 `orphans: 'ban'` shuts them:
 
 ```ts
-await provisionPersonas(singletonServices, {
-  personas: personaConfigs,
-  environments: personaEnvironments,
-  orphans: 'ban',
+pikkuFabric({
+  publicKey,
+  audience,
+  scopeService,
+  personas: {
+    personas: personaConfigs,
+    environments: personaEnvironments,
+    orphans: 'ban',
+  },
 })
 ```
 
 It writes the same `banned` column the console's ban RPC writes (so it needs the
-`ban()` plugin wired, and says so if it isn't), revokes the account's sessions,
+`pikkuBan()` plugin wired, and says so if it isn't), revokes the account's sessions,
 and leaves the row, its grants and its history intact — provisioning lifts the
 ban again by itself if the persona comes back. Deleting is deliberately not
 offered: an actor row is referenced by whatever those scenarios did while it

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

@@ -210,7 +210,7 @@ people the user named, and the roles they imply.
 
 ```typescript
 import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
-import { defineSystemRole } from '#pikku'
+import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
   owner: {
@@ -484,7 +484,7 @@ experiences it. Three ship in `packages/functions/test/scenarios/` — keep them
 green — and every milestone's gherkin block from §5 becomes one more.
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const tenantReportsAFaultScenario = pikkuScenario<void, { id: string }>({
   title: 'A tenant reports a fault and the owner sees it',

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

@@ -85,7 +85,7 @@ named:
 
 ```typescript
 import { definePersonas } from '#pikku/scopes/pikku-personas.gen.js'
-import { defineSystemRole } from '#pikku'
+import { defineSystemRole } from '#pikku/scopes'
 
 defineSystemRole({
   owner: { displayName: 'Owner', description: 'Sees only their own rows', scopes: [] },
@@ -199,7 +199,7 @@ Not the full ladder — one journey, end to end, as a real persona, so the app h
 at least one thing that stays true.
 
 ```typescript
-import { pikkuScenario } from '#pikku/workflow/pikku-workflow-types.gen.js'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const ownerCreatesAndSeesItScenario = pikkuScenario<void, { id: string }>({
   title: 'An owner creates a thing and sees it',

package/skills/pikku-concepts/SKILL.md

@@ -247,6 +247,8 @@ export const lifecycle = pikkuServerLifecycle<SingletonServices>({
 
 Export exactly one `pikkuServerLifecycle` from anywhere in `srcDirectories` — the inspector finds it by the wrapper call. Every hook is optional and receives the already-created singleton services. See pikku-services for the ordering and the `afterStop` caveat.
 
+**Only `pikku dev` and `pikku serve` invoke these hooks.** No deploy runtime does, so anything a Workers or serverless stage needs done cannot live here — put it on the request path that needs it, guarded by a cheap check.
+
 **2. Bootstrap it yourself (required for a specific runtime)**
 
 Express, Fastify, uWS, Lambda, Cloudflare and Next.js need their own entrypoint, because Pikku is embedded in a server you own:
@@ -333,7 +335,7 @@ bottom.
 | Axis            | What it covers                                                                                                                                                    | What decides it                                                                                             |
 | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | **Identifiers** | Function, component, type, variable and file names. Database tables and columns. Branch names and commit messages.                                                | Nothing. **Always English.** There is no setting.                                                           |
-| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                          |
+| **Meta**        | The prose authored _inside_ the code: `description` on functions and steps, `name`/`title` on features and scenarios, step `template`, role/persona descriptions. | `metaLocale` in `pikku.config.json`. Defaults to `en`.                                                      |
 | **Product UI**  | Every string the app shows a user.                                                                                                                                | `messages/<locale>.json`, with `active.json`'s `defaultLocale` choosing what a first-time visitor opens in. |
 
 ### Identifiers are English, and nothing changes that

package/skills/pikku-fabric/SKILL.md

@@ -119,7 +119,7 @@ without it in production?"** If yes, it is configuration and belongs in a
 migration, however much it looks like sample data. A venue and its rooms, a
 product catalogue, a tenant, a country list, the organization the whole
 deployment hangs off — all configuration. Accounts and role grants are
-provisioning: `provisionPersonas` at deployment, or a migration. What is left
+provisioning: the fabric plugin's `personas`, or a migration. What is left
 over is the seed's job — the bookings, orders and messages a demo needs and a real
 environment starts without.
 
@@ -129,8 +129,8 @@ a stage whose pages return 200 — the shell renders fine — while its first da
 read throws `no result` or a foreign-key violation on a row the seed was
 silently supplying.
 
-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
+A Better Auth app has a second constraint: the plugins you enable (`pikkuBan()`,
+`pikkuActor()`, …) 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.
 
@@ -306,13 +306,13 @@ tells you nothing about whether it worked. `--sync` waits for a terminal state
 and exits non-zero unless the deployment went live, which is the only form worth
 running in CI:
 
-| exit | meaning |
-| ---- | ------- |
-| 0 | live (or queued, without `--sync`) |
-| 1 | the command could not run — not logged in, unsafe git state, bad flags |
-| 2 | the deployment failed, errored, timed out server-side, or was cancelled |
-| 3 | the deployment is blocked and nothing the CLI can do will unblock it |
-| 4 | the wait hit `--timeout` with the deployment still in flight |
+| exit | meaning                                                                 |
+| ---- | ----------------------------------------------------------------------- |
+| 0    | live (or queued, without `--sync`)                                      |
+| 1    | the command could not run — not logged in, unsafe git state, bad flags  |
+| 2    | the deployment failed, errored, timed out server-side, or was cancelled |
+| 3    | the deployment is blocked and nothing the CLI can do will unblock it    |
+| 4    | the wait hit `--timeout` with the deployment still in flight            |
 
 Fabric parks every deploy at a gate after the plan phase (`status: suspended`).
 Why it parked is the whole story, and it is `statusReason`, not `status`:

package/skills/pikku-feature/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pikku-feature
 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).'
-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 *)
+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 *), Bash(yarn pikku fabric report *), Bash(npx --no pikku fabric report *)
 argument-hint: '<feature description>'
 ---
 
@@ -16,6 +16,7 @@ Use this skill as an execution checklist, not reference material.
 3. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 4. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
 5. If validation fails, fix the source cause and rerun validation. Do not paper over generated errors by editing generated files.
+6. Report anything about pikku itself that cost you time, the moment it happens — see **Report what fought you**.
 
 End-to-end flow: **discover → state intent → branch → implement → verify → commit → hand to reviewer**.
 
@@ -246,6 +247,106 @@ feature/<slug>` and surface the PR-create URL.
 
 Do not push without explicit confirmation. Do not merge.
 
+## Report what fought you
+
+When pikku itself is what cost you time, report it with `pikku fabric report`.
+Nothing is written to the repo; the finding goes to the linked fabric project
+and the terminal shows you exactly what was sent.
+
+**Report at the moment it happens**, not at the end from memory — a run that
+falls over never reaches its end. One finding per thing that fought you.
+
+### The ladder
+
+1. **Find the quicker workaround.** The user is paying for their feature, not
+   for pikku's health.
+2. **Investigate** only when there is no workaround, or when the user asks why
+   something is slow or wrong.
+3. **Report at the depth you already reached.** Never spend extra effort to
+   file; never throw away effort you already spent. If the investigation took
+   you to the mechanism, the finding says so — named file, named function, what
+   is actually happening, and what pikku should do instead.
+
+**Never fix pikku itself.** Not a patch in `node_modules`, not a linked
+checkout, not a branch in the framework repo. Many agents each patching pikku to
+unblock themselves is many divergent copies and a merge problem nobody signed up
+for. Work around it in the app, report it, and let the fix happen once.
+
+### What counts
+
+Anything that cost you time and would cost the next person the same. Most of
+these never produce an error: output that is quietly wrong, a generated type
+that disagrees with the runtime, a check that passes when it should not, a
+narrowing you had to write by hand because the framework should have written it.
+**Having to write code the framework should have written for you is a finding.**
+
+So is anything that only shows up in one place — invisible locally, fatal
+deployed, or the reverse. Say which, with `--surface`.
+
+Not a finding: a preference, a thing you would have designed differently, or
+baseline noise that was already failing before you started.
+
+### Two kinds
+
+- `--kind product` — pikku behaved wrongly. Fixing it is a change to the
+  framework.
+- `--kind harness` — a skill misled you: it told you to run something that does
+  not exist, described a flag that is spelled differently, or contradicted what
+  the CLI actually did. Pass `--skill <name>` and `--passage "<the line or
+  section>"`. This is the most useful kind to file, because it is fixable
+  immediately — so file it even when the cost was small.
+
+### When there was no workaround
+
+Report it anyway with `--unresolved`, and put what you tried and how each
+attempt failed in `--tried`. That is what stops the next person walking the same
+dead ends. Tell the user what you did instead — abandoned it, shipped something
+degraded, or stopped.
+
+`--unresolved` means **no workaround was found**. It does not mean the
+workaround was unpleasant.
+
+### The command
+
+Send it as JSON on stdin. Most of a finding is prose, and prose carries
+apostrophes, quotes, backticks and newlines — each one a shell metacharacter
+before it is a character in your sentence. A stack trace passed to `--error`
+breaks the command at its first newline; a backtick in `--actual` runs whatever
+follows it. Quote the heredoc delimiter (`<<'EOF'`, never `<<EOF`) so the shell
+leaves the body alone.
+
+```bash
+pikku fabric report --stdin <<'EOF'
+{
+  "title": "<one-line title>",
+  "kind": "product",
+  "model": "<the model you are>",
+  "expected": "<what you expected pikku to do>",
+  "actual": "<what it did instead>",
+  "command": "<the command you ran>",
+  "workaround": "<what you did instead, inside the app>"
+}
+EOF
+```
+
+Add whichever of these you actually have: `error` (the error's message line,
+verbatim), `repro` (the shortest way to reach it again), `proposal` (what pikku
+should do), `area`, `surface` (`local`, `deployed` or `both`), `cost` (measured
+if you measured it — "98s vs 20s steady" ranks; "slow" does not), `run` (an id
+shared by every finding from this build), `deployTarget`.
+
+The same fields exist as flags — `--kind`, `--expected` and so on — for a
+finding short enough to type. Anything with a newline or a quote in it goes
+through `--stdin`.
+
+Versions, platform and package manager are read off the installed tree for you.
+Do not pass them and do not ask the user for them.
+
+Reporting never fails a build. A finding that cannot be sent — logged out, or
+fabric unreachable — is held on the machine and goes out with the next report
+that succeeds, so nothing you file is lost. If it says the finding was queued,
+carry on with the feature; do not try to fix it, and do not file it again.
+
 ## Hard constraints
 
 The skill's `allowed-tools` does **not** permit:
@@ -254,7 +355,8 @@ The skill's `allowed-tools` does **not** permit:
 - `yarn dbmigrate` (never run migrations against the real DB during planning)
 - `pikku deploy apply` (never deploy)
 - secret writes
-- network calls beyond what the implementation requires
+- network calls beyond what the implementation requires, except
+  `pikku fabric report`, which is explicitly permitted
 
 If the feature genuinely needs any of these, **stop and ask** with a clear
 explanation of why and what would change.

package/skills/pikku-http/SKILL.md

@@ -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/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 import { cors, authBearer } from '@pikku/core/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])

package/skills/pikku-middleware/SKILL.md

@@ -23,7 +23,7 @@ installGroups: [core]
 ## The `pikkuMiddleware` Factory
 
 ```typescript
-import { pikkuMiddleware } from '#pikku/function'
+import { pikkuMiddleware } from '#pikku/middleware'
 
 // Simple: just a function
 const myMiddleware = pikkuMiddleware(async (services, wire, next) => {
@@ -139,7 +139,7 @@ Tags from the function definition and the wire object are merged — middleware
 ### Registering Tag Middleware
 
 ```typescript
-import { addTagMiddleware } from '#pikku/function'
+import { addTagMiddleware } from '#pikku/middleware'
 
 addTagMiddleware('machine-agent', [machineAgentBearerAuth])
 ```
@@ -277,7 +277,7 @@ export const getToken = () => _token
 ```typescript
 // wirings/http.wiring.ts
 import { timingSafeEqual } from 'node:crypto'
-import { addTagMiddleware, pikkuMiddleware } from '#pikku/function'
+import { addTagMiddleware, pikkuMiddleware } from '#pikku/middleware'
 import { UnauthorizedError } from '#pikku/error'
 import { getToken } from '../lib/host-token.js'
 

package/skills/pikku-permissions/SKILL.md

@@ -58,7 +58,7 @@ Use for checks that read the session but need no request data — and that asser
 something **beyond** merely having a session (a flag, a tier, a claim).
 
 ```typescript
-import { pikkuAuth } from '#pikku/function'
+import { pikkuAuth } from '#pikku/auth'
 
 // Good: a real gate on the session's contents, not just its existence.
 export const isVerified = pikkuAuth(
@@ -89,7 +89,7 @@ A permission answers "_may this user do this?_" (role, ownership, tier) — neve
 Use when authorization depends on the actual request data (e.g., resource ownership).
 
 ```typescript
-import { pikkuPermission } from '#pikku/function'
+import { pikkuPermission } from '#pikku/auth'
 
 export const isBookOwner = pikkuPermission(
   async ({ db }, { bookId }, { session }) => {
@@ -139,7 +139,7 @@ export const deleteBook = pikkuFunc({
 A global permission is an app-wide baseline that **every** function must additionally pass. It is an independent AND gate: it can only ever _narrow_ access — it never grants access a function's own `permissions` would deny.
 
 ```typescript
-import { addGlobalPermission } from '#pikku/function'
+import { addGlobalPermission } from '#pikku/auth'
 
 addGlobalPermission([isEmployee]) // every function now also requires an employee session
 ```
@@ -248,7 +248,7 @@ declared, inspectable, and reusable.
 
 ```typescript
 // src/permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/function'
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
 
 export const isVerified = pikkuAuth(
   async (_services, session) => !!session?.emailVerified

package/skills/pikku-scenario/SKILL.md

@@ -46,7 +46,7 @@ Scenarios live in `srcDirectories` like any other function — by convention `*.
 `pikkuScenario` comes from the **generated** workflow types, not `@pikku/core`:
 
 ```typescript
-import { pikkuScenario } from '#pikku/scenario'
+import { pikkuScenario } from '#pikku/scenarios'
 
 export const orderSupportScenario = pikkuScenario<
   { value?: number },
@@ -175,7 +175,7 @@ Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs
 `pikkuFeature` groups scenarios the way gherkin's `Feature:` groups `Scenario:`. Scenarios are referenced by **imported identifier**, so a renamed or deleted scenario is a compile error rather than a silent skip:
 
 ```typescript
-import { pikkuFeature } from '#pikku/scenario'
+import { pikkuFeature } from '#pikku/scenarios'
 import {
   credentialLazyLoadScenario,
   credentialRoundTripScenario,
@@ -240,7 +240,7 @@ Utilities are **not steps**. They are plain exported functions, they take the br
 
 ```typescript
 // shop.browser.ts — shared actions. Not steps: nothing here is an intent.
-import type { PikkuBrowserWire } from '#pikku/scenario'
+import type { PikkuBrowserWire } from '#pikku/scenarios'
 import type {} from '@pikku/playwright'
 
 /** Arrive on the shop, from wherever the browser happens to be. */
@@ -462,7 +462,7 @@ Assertions with no possible browser witness are a different thing and should not
 `scenario.do` can only name an RPC. A **step** is a named, typed unit of scenario behaviour whose body is an ordinary pikku function — so it can call several RPCs as its actor, assert, or drive a browser.
 
 ```typescript
-import { pikkuScenarioStep } from '#pikku/scenario'
+import { pikkuScenarioStep } from '#pikku/scenarios'
 
 export const buysAnApple = pikkuScenarioStep<
   { qty: number },

package/skills/pikku-security/SKILL.md

@@ -62,7 +62,7 @@ Apply these via `addHTTPMiddleware` in a wirings file:
 
 ```typescript
 import { authBearer, authCookie, authAPIKey } from '#pikku/middleware'
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 
 // JWT bearer token — reads Authorization header
 addHTTPMiddleware('*', [authBearer()])
@@ -118,7 +118,7 @@ response.
 
 ```typescript
 // permissions.ts
-import { pikkuAuth, pikkuPermission } from '#pikku/function'
+import { pikkuAuth, pikkuPermission } from '#pikku/auth'
 
 export const isAuthenticated = pikkuAuth(
   async (_services, session) => !!session
@@ -129,7 +129,7 @@ export const isVerified = pikkuAuth(
 
 // wirings/auth.wiring.ts
 import { authCookie } from '#pikku/middleware'
-import { addHTTPMiddleware } from '#pikku/http'
+import { addHTTPMiddleware } from '#pikku/middleware'
 
 addHTTPMiddleware('*', [
   authCookie({

package/skills/pikku-services/SKILL.md

@@ -38,7 +38,7 @@ pikku info tags --verbose        # Understand project organization
 ### `pikkuServices(factory)` — singleton services (created once at startup)
 
 ```typescript
-import { pikkuServices } from '#pikku/function'
+import { pikkuServices } from '#pikku/setup'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'
 
@@ -61,7 +61,7 @@ export const createSingletonServices = pikkuServices(
 ### `pikkuWireServices(factory)` — per-request services (fresh per HTTP request, queue job, CLI command, etc.)
 
 ```typescript
-import { pikkuWireServices } from '#pikku/function'
+import { pikkuWireServices } from '#pikku/setup'
 
 export const createWireServices = pikkuWireServices(
   async (singletonServices, wire) => {
@@ -240,7 +240,7 @@ const createSingletonServices = pikkuServices(async (config) => {
 
 ```typescript
 // services.ts
-import { pikkuServices, pikkuWireServices } from '#pikku/function'
+import { pikkuServices, pikkuWireServices } from '#pikku/setup'
 import { ConsoleLogger } from '@pikku/core/services'
 import { JoseJWTService } from '@pikku/jose'