@pikku/cli 0.12.83 → 0.12.86

package/skills/pikku-addon/SKILL.md

@@ -7,6 +7,7 @@ description: >-
   addons, reusable function packages, cross-project sharing, or addon package structure. DO NOT
   TRIGGER when: user asks about internal function composition (use pikku-rpc) or general function
   definitions (use pikku-concepts).
+installGroups: [core]
 ---
 
 # Pikku Addons

package/skills/pikku-ai-agent/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   uses pikkuAIAgent/runAIAgent/streamAIAgent, user asks about AI agents, chatbots, LLM assistants,
   tool-calling agents, or agent memory/streaming. DO NOT TRIGGER when: user asks about MCP tool
   exposure (use pikku-mcp) or general function definitions (use pikku-concepts).
+installGroups: [core]
 ---
 
 # Pikku AI Agent Wiring
@@ -42,7 +43,7 @@ pikkuAIAgent({
   name: string,                  // Unique agent identifier
   description: string,           // What the agent does
   instructions: string | string[],  // System prompt / behavior instructions
-  model: string,                 // LLM model (e.g. 'openai/gpt-4o-mini')
+  model: string,                 // LLM model (e.g. 'openai/gpt-5-mini')
   tools?: PikkuFunc[],           // Pikku functions the agent can call
   agents?: AIAgentConfig[],      // Sub-agents this agent can delegate to
   memory?: {
@@ -120,7 +121,7 @@ const todoAssistant = pikkuAIAgent({
   description: 'A helpful assistant that manages todos',
   instructions:
     'You help users manage their todo lists. Be concise and helpful.',
-  model: 'openai/gpt-4o-mini',
+  model: 'openai/gpt-5-mini',
   tools: [listTodos, createTodo, completeTodo],
   memory: {
     storage: 'aiStorage',
@@ -197,7 +198,7 @@ const todoAssistant = pikkuAIAgent({
     - Be concise and helpful
     - When creating todos, infer priority if not specified
     - When listing todos, summarize the results`,
-  model: 'openai/gpt-4o-mini',
+  model: 'openai/gpt-5-mini',
   tools: [listTodos, createTodo, completeTodo],
   memory: {
     storage: 'aiStorage',
@@ -214,7 +215,7 @@ wireHTTP({
   func: pikkuFunc({
     title: 'Chat',
     func: async (services, { message, threadId }, wire) => {
-      const session = await wire.session.get()
+      const { session } = wire
       return await runAIAgent(
         'todo-assistant',
         {

package/skills/pikku-ai-vercel/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   VercelAIAgentRunner, user asks about Vercel AI SDK integration, AI agent runners, or
   @pikku/ai-vercel. DO NOT TRIGGER when: user asks about AI agent wiring (use pikku-ai-agent) or
   voice I/O (use pikku-ai-voice).
+installGroups: [core]
 ---
 
 # Pikku AI Vercel (Agent Runner)

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

@@ -9,6 +9,7 @@ description: >-
   user asks about ANY form of authentication, login, logout, sessions, or user identity — always
   answer with this skill. DO NOT TRIGGER when: user asks about JWT middleware (use pikku-security)
   or custom session services (use pikku-services).
+installGroups: [core]
 ---
 
 # Pikku Better Auth Integration
@@ -119,6 +120,62 @@ Enabling `session: { cookieCache: { enabled: true } }` makes the CLI split out a
 
 In both cases a **route-scoped** registration (`addHTTPMiddleware('/some/path', [...])`) does NOT count — only a global one suppresses the generated default. The generated middleware in a `.gen.ts` file is also ignored by the detector, so regeneration never self-suppresses.
 
+### Admin capabilities are scopes, not a role
+
+Pikku does **not** use better-auth's `admin()` plugin, and nothing in this
+package reads a `role` column. A role is not a permission: "who may impersonate"
+and "who may rebind a shared credential" are different capabilities one user can
+hold independently, which a single `role` string cannot express. Every gate the
+package owns therefore resolves the caller's scopes through the registered
+`ScopeService` and checks the `admin:*` tree:
+
+| Gate | Scope required |
+| --- | --- |
+| `impersonation` (`betterAuthSession` / `betterAuthStatelessSession`) | `admin:impersonate` |
+| `credentialOAuth`'s `canLinkSingleton` | `admin:credentials:link` |
+| the console's user directory | `admin:users:list` |
+
+Holding the bare `admin` scope satisfies all of them — a parent grant covers
+everything nested beneath it — so `admin` is the direct replacement for the old
+`role === 'admin'`.
+
+Declare the tree in your own `wireScope` (the CLI extracts it by AST, so it must
+be an inline literal; `ADMIN_SCOPE_TREE` is exported from `@pikku/better-auth`
+as the reference shape). Apps wiring `@pikku/addon-console` inherit it already.
+
+```typescript
+wireScope({
+  admin: {
+    displayName: 'Administration',
+    description: 'Capabilities that act on the application as a whole',
+    scopes: {
+      impersonate: { description: 'Act as another user' },
+      credentials: {
+        description: 'Application-wide credentials',
+        scopes: {
+          link: { description: 'Bind a shared credential for every user' },
+        },
+      },
+      users: {
+        description: 'The user directory',
+        scopes: { list: { description: 'List and search users' } },
+      },
+    },
+  },
+})
+```
+
+Then grant it — via a role (`scopeService.createRole({ name: 'admin', scopes: ['admin'] })` plus `addUserToRole`) or directly with `addScopeToUser`.
+
+Every gate **fails closed**: with no `ScopeService` registered nothing can hold
+a scope, so nothing is authorized, and the denial is logged at `warn` because
+that is a configuration bug rather than a permissions decision. Pass your own
+`canImpersonate` / `canLinkSingleton` to override the default entirely.
+
+Sibling concerns — banning a user, listing users from your own screens — are
+actions your app *invokes*, not things pikku gates. Put them on your own
+functions with `scopes: ['admin:users:ban']` and friends.
+
 ### 2. Production database adapter
 
 For real deployments swap `memoryAdapter` for the Kysely adapter backed by an injected DB. Better Auth owns its own tables (`user`, `session`, `account`, `verification`, plus plugin tables) — generate its schema with `npx @better-auth/cli generate` and apply it as a migration.

package/skills/pikku-concepts/SKILL.md

@@ -71,7 +71,7 @@ const updateTodo = pikkuFunc({
   input: UpdateTodoInput,
   output: TodoOutput,
   func: async (services, data, wire) => {
-    const session = await wire.session.get()
+    const { session } = wire
     return services.todoStore.update(data.id, data)
   },
 })

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

@@ -192,17 +192,19 @@ router.delete('/users/:id', requireRole('admin'), deleteUser)
 **Pikku:**
 
 ```typescript
-const isAdmin = pikkuPermission(async (services, data, wire) => {
-  const session = await wire.session.get()
-  return session?.role === 'admin'
+const isOwner = pikkuPermission(async ({ db }, { userId }, wire) => {
+  const { session } = wire
+  return session?.userId === userId
 })
 
-// Declare on the function definition (the only place permissions live)
+// Declare on the function definition (the only place permissions live).
+// A capability like "may delete users" is a scope, not a permission.
 export const deleteUser = pikkuFunc({
   func: async (services, data) => {
     /* ... */
   },
-  permissions: { admin: [isAdmin] },
+  scopes: ['admin:users:delete'],
+  permissions: { owner: [isOwner] },
 })
 
 // App-wide baseline every function must also pass (AND gate, narrow-only)
@@ -476,7 +478,7 @@ const updateTodo = pikkuFunc(async (services, { id, title }, wire) => {
   const todo = services.todoStore.getTodo(id)
   if (!todo) throw new NotFoundError('Todo not found')
 
-  const session = await wire.session.get()
+  const { session } = wire
   if (todo.userId !== session.userId) throw new ForbiddenError()
 
   return { todo: services.todoStore.update(id, { title }) }
@@ -509,18 +511,18 @@ const login = pikkuSessionlessFunc(
   async ({ jwt }, { username, password }, wire) => {
     const user = authenticate(username, password)
     const token = await jwt.sign({ userId: user.id })
-    await wire.session.set({ userId: user.id, user }) // Set
+    await wire.setSession({ userId: user.id, user }) // Set
     return { token, user }
   }
 )
 
 const getMe = pikkuFunc(async (services, data, wire) => {
-  const session = await wire.session.get() // Get
+  const { session } = wire // Get
   return { user: session.user }
 })
 
 const logout = pikkuFunc(async (services, data, wire) => {
-  await wire.session.clear() // Clear
+  await wire.clearSession() // Clear
   return { success: true }
 })
 ```

package/skills/pikku-emails/SKILL.md

@@ -10,6 +10,7 @@ description: >-
   email (verification, password reset, invitation, receipt), wire email sending, or translate an
   email. DO NOT TRIGGER when: user asks about i18n for the app UI (use pikku-i18n) or auth flows
   in general (use pikku-better-auth).
+installGroups: [core]
 ---
 
 # Pikku Emails

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

@@ -0,0 +1,112 @@
+---
+name: pikku-fabric-debug
+description: 'Debug a deployed Fabric stage from the CLI — read logs, find recent errors, follow a single request end-to-end by traceId, and check request/error/latency metrics. TRIGGER when: a deployed Fabric app is erroring, timing out, or behaving differently than local; the user asks "why is prod failing", "check the logs", "what happened to this request"; or a deploy succeeded but the app misbehaves. DO NOT TRIGGER when: the failure reproduces locally (debug it locally), the deploy itself failed (use pikku-fabric — that is a build/config problem, not a runtime one), or the project is not deployed to Fabric.'
+installGroups: [fabric]
+---
+
+# Debugging a deployed Fabric stage
+
+## Agent Operating Procedure
+
+Use this skill as an execution checklist, not reference material.
+
+1. Reproduce locally first. If it fails locally too, debug it there — the
+   deployed stage adds cost and latency to every iteration.
+2. Start from `errors`, not `logs`. Errors are already filtered and carry the
+   traceId that unlocks the rest.
+3. Follow one trace end-to-end before forming a theory. A single failing request
+   tells you more than a hundred unrelated log lines.
+4. Fix the source cause and redeploy. Never leave the diagnosis at "it is flaky".
+5. Confirm the fix against the same stage — recheck `errors` for the function.
+
+Every command below requires a logged-in CLI and a linked project. Both fail
+with the exact remediation if not:
+
+```
+Not logged in. Run `pikku fabric login` first.
+No fabric project linked. Run `pikku fabric link` first.
+```
+
+## The loop
+
+**1 — What is broken?**
+
+```bash
+pikku fabric errors -b main                 # branch defaults to main
+pikku fabric errors -b main --function createOrder
+```
+
+Prints a `WHEN | FUNCTION | TRACE | MESSAGE` table. The message is **truncated
+to 100 characters** — treat it as a label, not the full error. The TRACE column
+is the input to the next step.
+
+**2 — What happened in that one request?**
+
+```bash
+pikku fabric trace <traceId> -b main
+pikku fabric trace <traceId> -b main --json
+```
+
+`--branch` is **required** here (no default). Each event prints as:
+
+```
+<timestamp> <scriptName> <wireType>:<wireId> <duration>ms — <error|message|outcome>
+```
+
+This is the whole request across the stage — every unit it touched, in order,
+with per-event durations. The last event before the failure is where to look.
+
+**3 — Is it one request or the whole stage?**
+
+```bash
+pikku fabric metrics -b main                       # last 24h
+pikku fabric metrics -b main --hours 2 --function createOrder
+```
+
+Rows are `reqs= err= (rate%) avg= min= max=` per bucket. A single bad request
+with a healthy error rate is a data problem; a climbing error rate is a
+deployment or dependency problem. `--json` additionally returns a `wireTypes`
+breakdown (requests per http/queue/scheduler/…) that the table output omits.
+
+**4 — Wider context around the failure**
+
+```bash
+pikku fabric logs -b main
+pikku fabric logs -b main --level warn
+pikku fabric logs -b main -f              # follow
+```
+
+`--branch` is **required** — `logs` throws `Specify --branch <branch-name>.`
+without it, even though the flag reads as optional.
+
+**5 — Is the running code the code you think it is?**
+
+```bash
+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
+deploy stuck in flight, explains a whole class of "my fix did nothing".
+
+## Known gaps — do not misread these as bugs in your app
+
+- **`pikku fabric logs --since` and `--deployment` are accepted and ignored.**
+  They are declared as options but the command never reads them, so
+  `--since 15m` silently returns the same default window as no flag at all. Do
+  not conclude "nothing happened in the last 15 minutes" from it. Narrow by
+  `--level`, or by `--function` via `errors`, instead.
+- **`--follow` is a 2-second client-side poll, not a server stream.** It
+  dedups against what it already printed, so it behaves like `tail -f`, but new
+  entries can appear up to ~2s late and it holds the process open until killed.
+
+## What NOT to do
+
+- **Do not SSH anywhere or query the telemetry backend directly.** These
+  commands are the supported surface; anything lower-level is Fabric-internal
+  and will not exist for your project.
+- **Do not debug by redeploying with added `console.log`s.** Get the traceId,
+  read the trace. A deploy cycle per hypothesis is the slow path.
+- **Do not read the truncated `errors` message as the full error.** Always
+  confirm against `trace` before changing code.
+- **Do not treat an empty `errors` table as "the app is fine"** — a request that
+  returns a wrong 200 logs nothing. Check `metrics` for the outcome mix.

package/skills/pikku-permissions/SKILL.md

@@ -58,8 +58,8 @@ export const isAuthenticated = pikkuAuth(
   async (_services, session) => !!session
 )
 
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
 )
 ```
 
@@ -88,11 +88,11 @@ export const hasBookAccess = pikkuPermission(
 
 ```typescript
 permissions: {
-  admin: isAdmin,                              // OR: admins can access
+  verified: isVerified,                        // OR: verified users can access
   owner: isBookOwner,                          // OR: owners can access
   reviewer: [isAuthenticated, hasBookAccess],  // AND: both must pass
 }
-// Logic: admin OR owner OR (isAuthenticated AND hasBookAccess)
+// Logic: verified OR owner OR (isAuthenticated AND hasBookAccess)
 ```
 
 Groups are OR'd. Entries within a group array are AND'd.
@@ -107,7 +107,7 @@ export const deleteBook = pikkuFunc({
     await db.deleteBook(bookId)
   },
   permissions: {
-    admin: isAdmin,
+    verified: isVerified,
     owner: isBookOwner,
   },
 })
@@ -146,8 +146,8 @@ export const isAuthenticated = pikkuAuth(
   async (_services, session) => !!session
 )
 
-export const isAdmin = pikkuAuth(
-  async (_services, session) => session?.role === 'admin'
+export const isVerified = pikkuAuth(
+  async (_services, session) => !!session?.emailVerified
 )
 
 export const isOrgMember = pikkuPermission(
@@ -162,7 +162,7 @@ export const deleteOrg = pikkuFunc({
     await db.deleteOrg(orgId)
   },
   permissions: {
-    admin: isAdmin,
+    verified: isVerified,
     owner: [isAuthenticated, isOrgMember],
   },
 })

package/skills/pikku-react/SKILL.md

@@ -36,15 +36,44 @@ import {
 Five exports. `usePikkuRealtime` is only valid when you wired a
 `PikkuRealtime` class via `createPikku` — see step 3 below.
 
+## Resolving the server URL
+
+Every client (`createPikku`, realtime, the auth client) resolves its base
+through one shared helper in `src/lib/env.ts`. Write this once:
+
+```ts
+// Endpoints come from env, never hardcoded.
+export function apiUrl(): string {
+  // SSR: the client hooks only run in the browser, so a placeholder is fine.
+  if (import.meta.env.SSR) {
+    return import.meta.env.VITE_API_URL ?? '/__api'
+  }
+  return import.meta.env.VITE_API_URL ?? `${window.location.origin}/api`
+}
+```
+
+**Never fall back to `http://localhost:3000`.** `import.meta.env.VITE_API_URL`
+is substituted by Vite at *build* time, so any deploy that supplies the URL as
+a *runtime* env var or platform binding leaves it `undefined` in the shipped
+bundle — the fallback is then the only branch that ever runs in the browser. A
+localhost fallback means every request from a deployed app goes to the user's
+own machine. `origin + '/api'` is same-origin, needs no build-time knowledge of
+the domain, and is correct wherever the app is served from.
+
+For local dev, set `VITE_API_URL`, or proxy `/api` → your backend in
+`vite.config.ts` under `server.proxy`. One `/api` entry also covers
+`/api/auth/*`; only add more entries for root-level routes outside `/api`.
+
 ## Setup at the app root
 
 ```tsx
 import { createPikku, PikkuProvider } from '@pikku/react'
 import { PikkuFetch } from './pikku/pikku-fetch.gen'
 import { PikkuRPC } from './pikku/pikku-rpc.gen'
+import { apiUrl } from './lib/env'
 
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000',
+  serverUrl: apiUrl(),
 })
 
 createRoot(document.getElementById('root')!).render(
@@ -62,7 +91,7 @@ the `PikkuRealtime` class as the third argument and the instance gets a
 import { PikkuRealtime } from './pikku/realtime.gen'
 
 const pikku = createPikku(PikkuFetch, PikkuRPC, PikkuRealtime, {
-  serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000',
+  serverUrl: apiUrl(),
 })
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch
 // (server URL + auth configured once).
@@ -159,7 +188,7 @@ or set headers on the fetch instance after creation. Common pattern:
 
 ```tsx
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: '...',
+  serverUrl: apiUrl(),
   fetchOptions: {
     onRequest: (req) => {
       const token = localStorage.getItem('token')

package/skills/pikku-react-query/SKILL.md

@@ -59,9 +59,11 @@ import { PikkuProvider, createPikku } from '@pikku/react'
 import { PikkuFetch } from './pikku/pikku-fetch.gen'
 import { PikkuRPC } from './pikku/pikku-rpc.gen'
 
+import { apiUrl } from './lib/env'
+
 const queryClient = new QueryClient()
 const pikku = createPikku(PikkuFetch, PikkuRPC, {
-  serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000',
+  serverUrl: apiUrl(),
 })
 
 <QueryClientProvider client={queryClient}>
@@ -75,6 +77,41 @@ The two generated files come from `pikku.config.json`'s
 `clientFiles.fetchFile` and `clientFiles.rpcWiringsFile`. Hooks live in
 the file at `clientFiles.reactQueryFile` (typically `api.gen.ts`).
 
+`apiUrl()` is the shared server-URL helper — see **pikku-react**. Never
+inline `?? 'http://localhost:3000'`: a deploy that supplies the URL as a
+runtime binding leaves `import.meta.env.VITE_API_URL` undefined in the
+bundle, so the fallback is the branch that actually runs.
+
+## TanStack Start (SSR)
+
+Under Start the provider mounts in `routes/__root.tsx` rather than
+`main.tsx`, and the same module is evaluated on the server. Three things
+differ:
+
+1. **`apiUrl()` must have an SSR branch.** `window` is undefined during
+   render; return the build-time var or a placeholder (the client hooks
+   only fire in the browser).
+2. **Build auth clients lazily.** Better Auth validates its baseURL with
+   `new URL(...)` at construction, so a module-scope `createAuthClient`
+   crashes SSR on the placeholder. Memoize it behind a getter:
+
+   ```ts
+   let _authClient: ReturnType<typeof createAuthClient> | undefined
+   export const authClient = () =>
+     (_authClient ??= createAuthClient({ baseURL: `${apiUrl()}/auth` }))
+   ```
+
+3. **The auth baseURL needs the `/auth` suffix.** Better Auth only
+   appends its default `/api/auth` when the baseURL carries no path.
+   `apiUrl()` already ends in `/api`, so a bare `apiUrl()` leaves the
+   client calling `/api/get-session` and 404ing.
+
+Server functions that need typed RPC access use the generated shim:
+
+```bash
+pikku tanstack-start   # emits the makeApi server-function shim
+```
+
 ## The hooks
 
 All hooks are imported from your generated `api.gen.ts`:

package/skills/pikku-realtime/SKILL.md

@@ -160,7 +160,7 @@ const pikku = createPikku(
   PikkuFetch,
   PikkuRPC,
   PikkuRealtime, // pass the realtime class as the third arg
-  { serverUrl: import.meta.env.VITE_API_URL ?? 'http://localhost:3000' }
+  { serverUrl: apiUrl() } // shared env helper — see pikku-react
 )
 // pikku.fetch / pikku.rpc / pikku.realtime — all share the same fetch.
 

package/skills/pikku-security/SKILL.md

@@ -36,7 +36,7 @@ const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id, role: user.role })
+    setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })
@@ -80,7 +80,7 @@ addHTTPMiddleware('*', [authAPIKey({ source: 'all' })])
 import { pikkuAuth, pikkuPermission } from '#pikku'
 
 export const isAuthenticated = pikkuAuth(async (_services, session) => !!session)
-export const isAdmin = pikkuAuth(async (_services, session) => session?.role === 'admin')
+export const isVerified = pikkuAuth(async (_services, session) => !!session?.emailVerified)
 
 // wirings/auth.wiring.ts
 import { authCookie } from '@pikku/core/middleware'
@@ -95,7 +95,7 @@ export const login = pikkuFunc({
   auth: false,
   func: async ({ jwt, db }, { email, password }, { setSession }) => {
     const user = await db.verifyCredentials(email, password)
-    setSession({ userId: user.id, role: user.role })
+    setSession({ userId: user.id })
     return { token: jwt.sign({ userId: user.id }) }
   },
 })

package/skills/pikku-services/SKILL.md

@@ -118,6 +118,40 @@ const getUser = pikkuFunc({
 })
 ```
 
+### Services Are Never Optional Inside a Function
+
+**Never write a `if (!service) throw ...` existence guard in a function body.** It is dead code, and it defeats the platform.
+
+Optionality lives in exactly one place — `services.ts` / the `SingletonServices` declaration — and it means *"this may not be created"*, not *"this may be missing at call time"*. A service is optional precisely because **nothing destructures it**, and `requireSingletonServices` therefore never creates it. The moment any wired function destructures it, Pikku creates it and guarantees it is there.
+
+The types enforce this rather than merely documenting it. The inspector records the services destructured by every wired `func`, `permissions` **and** `middleware`, and emits them as `RequiredSingletonServices`. The generated function types then default their service parameter to:
+
+```typescript
+export type WiredSingletonServices = RequiredSingletonServices & SingletonServices
+export type WiredServices = RequiredSingletonServices & Services
+```
+
+so a service that is `foo?: Foo` in `SingletonServices` arrives as a non-optional `Foo` in every function, permission and middleware that uses it. There is nothing to guard against.
+
+```typescript
+// ✅ Correct — destructure and use; creation is guaranteed by the manifest
+const listThreads = pikkuFunc({
+  func: async ({ agentRunService }, { threadId }) => {
+    return await agentRunService.getThreadMessages(threadId)
+  },
+})
+
+// ❌ Wrong — unreachable guard; signals a misunderstanding of service wiring
+const listThreads = pikkuFunc({
+  func: async ({ agentRunService }, { threadId }) => {
+    if (!agentRunService) throw new MissingServiceError('agentRunService')
+    return await agentRunService.getThreadMessages(threadId)
+  },
+})
+```
+
+If a service really is conditional at runtime (e.g. an optional integration a deployment may not configure), that is a **configuration** concern: branch on config, or fail fast at startup in `services.ts` — not per-request in every function.
+
 ### Dynamic Import Optimization
 
 Use the generated manifest to conditionally import heavy dependencies — only the services actually wired get instantiated:

package/skills/pikku-template-clone/SKILL.md

@@ -2,6 +2,7 @@
 name: pikku-template-clone
 description: 'Standard cleanup to run right after a Pikku template is cloned or scaffolded into a new project. TRIGGER when: a Pikku template was just cloned/scaffolded (via `npm create pikku`, `git clone <template>`, or the user says "I cloned the kanban template / starter / template"), or the working tree still looks like an untouched template (template README, placeholder `@project/*` name in package.json). DO NOT TRIGGER when: working in an established project mid-feature, or editing the template repo itself.'
 allowed-tools: Bash(git status *), Bash(git add *), Bash(git commit *), Bash(git rm *), Bash(git mv *), Bash(git log *)
+installGroups: [core]
 ---
 
 # Pikku Template Post-Clone Cleanup

package/cli.schema.json

@@ -1 +0,0 @@
-{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","additionalProperties":false,"properties":{"configFile":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"wires":{"type":"array","items":{"type":"string"}},"excludeWires":{"type":"array","items":{"type":"string"}},"userSessionType":{"type":"string"},"singletonServicesFactoryType":{"type":"string"},"wireServicesFactoryType":{"type":"string"},"outDir":{"type":"string"},"schemaDirectory":{"type":"string"},"typesDeclarationFile":{"type":"string"},"functionsFile":{"type":"string"},"functionsMetaFile":{"type":"string"},"functionsMetaJsonFile":{"type":"string"},"functionTypesFile":{"type":"string"},"httpWiringsFile":{"type":"string"},"httpWiringMetaFile":{"type":"string"},"httpWiringMetaJsonFile":{"type":"string"},"httpContractsMetaJsonFile":{"type":"string"},"httpContractsMetaFile":{"type":"string"},"httpMapDeclarationFile":{"type":"string"},"httpTypesFile":{"type":"string"},"gatewaysWiringFile":{"type":"string"},"gatewaysWiringMetaFile":{"type":"string"},"gatewaysWiringMetaJsonFile":{"type":"string"},"channelsWiringFile":{"type":"string"},"channelsWiringMetaFile":{"type":"string"},"channelsWiringMetaJsonFile":{"type":"string"},"channelContractsMetaJsonFile":{"type":"string"},"channelContractsMetaFile":{"type":"string"},"channelsMapDeclarationFile":{"type":"string"},"channelsTypesFile":{"type":"string"},"rpcInternalWiringMetaFile":{"type":"string"},"rpcInternalWiringMetaJsonFile":{"type":"string"},"rpcInternalMapDeclarationFile":{"type":"string"},"rpcMapDeclarationFile":{"type":"string"},"rpcRemoteMapDeclarationFile":{"type":"string"},"remoteRpcWorkersFile":{"type":"string"},"graphWiringsFile":{"type":"string"},"webhookWorkersFile":{"type":"string"},"publicRpcFile":{"type":"string"},"publicAgentFile":{"type":"string"},"consoleFunctionsFile":{"type":"string"},"scenariosFunctionsFile":{"type":"string"},"workflowRoutesFile":{"type":"string"},"eventsChannelFile":{"type":"string"},"triggersTypesFile":{"type":"string"},"triggersWiringFile":{"type":"string"},"triggersWiringMetaFile":{"type":"string"},"triggersWiringMetaJsonFile":{"type":"string"},"triggerSourcesMetaFile":{"type":"string"},"triggerSourcesMetaJsonFile":{"type":"string"},"schedulersWiringFile":{"type":"string"},"schedulersWiringMetaFile":{"type":"string"},"schedulersWiringMetaJsonFile":{"type":"string"},"schedulersTypesFile":{"type":"string"},"queueWorkersWiringFile":{"type":"string"},"queueWorkersWiringMetaFile":{"type":"string"},"queueWorkersWiringMetaJsonFile":{"type":"string"},"queueMapDeclarationFile":{"type":"string"},"queueTypesFile":{"type":"string"},"workflowsWiringFile":{"type":"string"},"workflowsWiringMetaFile":{"type":"string"},"workflowsWorkersFile":{"type":"string"},"workflowMapDeclarationFile":{"type":"string"},"workflowTypesFile":{"type":"string"},"workflowMetaDir":{"type":"string"},"scenarioActorsFile":{"type":"string"},"mcpWiringsFile":{"type":"string"},"mcpWiringsMetaFile":{"type":"string"},"mcpWiringsMetaJsonFile":{"type":"string"},"mcpTypesFile":{"type":"string"},"mcpJsonFile":{"type":"string"},"agentWiringsFile":{"type":"string"},"agentWiringMetaFile":{"type":"string"},"agentWiringMetaJsonFile":{"type":"string"},"agentTypesFile":{"type":"string"},"agentMapDeclarationFile":{"type":"string"},"cliWiringsFile":{"type":"string"},"cliWiringMetaFile":{"type":"string"},"cliWiringMetaJsonFile":{"type":"string"},"cliContractsMetaJsonFile":{"type":"string"},"cliContractsMetaFile":{"type":"string"},"cliBootstrapFile":{"type":"string"},"cliTypesFile":{"type":"string"},"servicesFile":{"type":"string"},"middlewareFile":{"type":"string"},"middlewareGroupsMetaJsonFile":{"type":"string"},"permissionsFile":{"type":"string"},"permissionsGroupsMetaJsonFile":{"type":"string"},"bootstrapFile":{"type":"string"},"packageFile":{"type":"string"},"addonTypesFile":{"type":"string"},"nodeTypesFile":{"type":"string"},"secretTypesFile":{"type":"string"},"secretsFile":{"type":"string"},"secretsMetaJsonFile":{"type":"string"},"credentialsFile":{"type":"string"},"credentialsMetaJsonFile":{"type":"string"},"scopeTypesFile":{"type":"string"},"scopesFile":{"type":"string"},"scopesMetaJsonFile":{"type":"string"},"variableTypesFile":{"type":"string"},"variablesFile":{"type":"string"},"variablesMetaJsonFile":{"type":"string"},"$schema":{"type":"string"},"extends":{"type":"string"},"rootDir":{"type":"string"},"runtimeDir":{"type":"string","description":"Runtime artifacts directory (dev.db, content, tmp). Resolved relative to rootDir. Defaults to <rootDir>/.pikku-runtime."},"srcDirectories":{"type":"array","items":{"type":"string"}},"ignoreFiles":{"type":"array","items":{"type":"string"}},"packageMappings":{"type":"object","additionalProperties":{"type":"string"}},"addon":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}},"icon":{"type":"string"},"displayName":{"type":"string"},"description":{"type":"string"},"serverlessIncompatible":{"type":"array","items":{"type":"string"}},"openapi":{"type":"object","properties":{"version":{"type":"string"},"hash":{"type":"string"}},"required":["version","hash"],"additionalProperties":false}},"additionalProperties":false}]},"addonName":{"type":"string"},"configDir":{"type":"string"},"tsconfig":{"type":"string"},"clientFiles":{"type":"object","properties":{"fetchFile":{"type":"string"},"websocketFile":{"type":"string"},"rpcWiringsFile":{"type":"string"},"reactQueryFile":{"type":"string"},"realtimeFile":{"type":"string"},"realtimeEventHubTopicsImport":{"type":"string","description":"Optional import for the EventHubTopics type so the realtime client is fully typed. Format: `<path>#<TypeName>` resolved relative to `realtimeFile`. Example: `../types/eventhub-topics.js#EventHubTopics`. If unset, the generated client treats topics as `Record<string, unknown>`."},"queueWiringsFile":{"type":"string"},"mcpJsonFile":{"type":"string"},"nextBackendFile":{"type":"string"},"nextHTTPFile":{"type":"string"},"nextBackendTransport":{"type":"string","enum":["local","worker-rpc","http"],"description":"Transport used by the generated nextBackendFile wrapper.\n- `'local'` (default): function code is loaded in-process via bootstrap +   createSingletonServices. Required for Node/dev runs.\n- `'worker-rpc'`: SSR dispatches every call through an injected `Fetcher`   ({ fetch(req): Promise<Response> }). Function code is NOT bundled into   the SSR worker. Pair with `nextBackendFetcherImport` to point at your   resolver module.\n- `'http'`: SSR dispatches every call through the generated `PikkuFetch`   client. Use this when your Next app should call a separately running   local/server API instead of importing function code in-process."},"nextBackendFetcherImport":{"type":"string","description":"Module that exports a `fetcher: Fetcher` (or default export) used by the worker-RPC variant of the next backend wrapper. Resolved relative to `nextBackendFile`. Required when `nextBackendTransport === 'worker-rpc'`."},"startServerFnsFile":{"type":"string","description":"Emit a TanStack Start server-function shim into this file. The shim exports `makeApi(): PikkuRPC` — a typed caller over the generated RPC map for use in Start loaders, actions and components. It reads the API base URL from `import.meta.env.VITE_API_URL` (throws if unset). Requires `rpcWiringsFile` (where the `PikkuRPC` class is generated)."}},"additionalProperties":false},"emailTemplatesDir":{"type":"string","description":"Directory containing email templates, locales, partials, and theme.json."},"authFile":{"type":"string","description":"Path to write the generated Better Auth wiring file (auth.gen.ts). Must be within srcDirectories so wireSecret calls are picked up by the inspector. Example: \"src/auth.gen.ts\""},"authTypesFile":{"type":"string","description":"Path to write the generated typed `pikkuBetterAuth` re-export (auth.types.ts). Defaults to `{outDir}/auth/auth.types.ts`. Re-exported from `#pikku` so user code can `import { pikkuBetterAuth } from '#pikku'` with project-typed services."},"authMetaJsonFile":{"type":"string","description":"Path to write the generated Better Auth metadata (auth-meta.gen.json) — the enabled social providers and plugins the console SSO page reads via getAuthProviders. Defaults to `{outDir}/auth/pikku-auth-meta.gen.json`."},"openAPI":{"type":"object","properties":{"outputFile":{"type":"string"},"additionalInfo":{"$ref":"#/definitions/OpenAPISpecInfo"}},"required":["outputFile","additionalInfo"],"additionalProperties":false},"schema":{"type":"object","properties":{"additionalProperties":{"type":"boolean"},"supportsImportAttributes":{"type":"boolean"}},"additionalProperties":false},"db":{"type":"object","properties":{"engine":{"type":"string","enum":["sqlite","postgres"]},"pgVersion":{"type":"number"}},"additionalProperties":false},"cli":{"type":"object","properties":{"entrypoints":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","const":"local"},"path":{"type":"string"}},"required":["type","path"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"channel"},"name":{"type":"string"},"route":{"type":"string"},"wirePath":{"type":"string"},"path":{"type":"string"}},"required":["type","wirePath"],"additionalProperties":false},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"type":{"type":"string","const":"local"},"path":{"type":"string"}},"required":["type","path"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"channel"},"name":{"type":"string"},"route":{"type":"string"},"wirePath":{"type":"string"},"path":{"type":"string"}},"required":["type","wirePath"],"additionalProperties":false}]}}]}}},"additionalProperties":false},"workflows":{"type":"object","properties":{"orchestratorQueue":{"type":"string"},"workerQueue":{"type":"string"}},"additionalProperties":false},"scenarios":{"type":"object","properties":{"actors":{"type":"object","additionalProperties":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"jobTitle":{"type":"string"},"personality":{"type":"string"}},"required":["email"],"additionalProperties":false},"description":"Global scenario actor registry — any scenario can impersonate any actor"},"environments":{"type":"object","additionalProperties":{"type":"object","properties":{"apiUrl":{"type":"string"},"signInPath":{"type":"string","description":"Actor sign-in path under apiUrl. Default: /auth/sign-in/actor"},"rpcPath":{"type":"string","description":"Exposed-RPC prefix under apiUrl. Default: /rpc"}},"required":["apiUrl"],"additionalProperties":false},"description":"Environments `pikku scenario run <environment>` can target; the actor secret comes from SCENARIO_ACTOR_SECRET, never config"}},"additionalProperties":false},"scaffold":{"type":"object","properties":{"addonDir":{"type":"string"},"functionDir":{"type":"string"},"wiringDir":{"type":"string"},"middlewareDir":{"type":"string"},"permissionDir":{"type":"string"},"pikkuDir":{"type":"string"},"graph":{"type":"boolean","description":"Wire the pikku addon-graph package so pikkuWorkflowGraph can reference its native transforms like graph:editFields."},"rpc":{"$ref":"#/definitions/PikkuScaffoldFeature"},"console":{"$ref":"#/definitions/PikkuScaffoldFeature"},"scenarios":{"$ref":"#/definitions/PikkuScaffoldFeature"},"agent":{"$ref":"#/definitions/PikkuScaffoldFeature"},"workflow":{"$ref":"#/definitions/PikkuScaffoldFeature"},"events":{"$ref":"#/definitions/PikkuScaffoldFeature"},"remoteRpc":{"$ref":"#/definitions/PikkuScaffoldFeature"},"webhook":{"type":"boolean","description":"The outgoing webhook delivery worker exposes no endpoint of its own, so it has no auth dimension — it is on or off."}},"additionalProperties":false},"addons":{"type":"object","properties":{"addonDir":{"type":"string"}},"additionalProperties":false,"description":"Community-registry addons installed via `pikku fabric addon add`. The source is copied into the project shadcn-style; each lands in `<addonDir>/<name>/` and the dir is registered as a yarn workspace so `wireAddon({ package })` resolves it by name. `addonDir` defaults to `addons` (top-level, outside the app's TS scan). Install provenance is tracked in pikku-addons.json."},"tests":{"type":"object","properties":{"outputDir":{"type":"string"}},"additionalProperties":false},"forceRequiredServices":{"type":"array","items":{"type":"string"}},"schemasFromTypes":{"type":"array","items":{"type":"string"}},"stateOutput":{"type":"string"},"stateInput":{"type":"string"},"verboseMeta":{"type":"boolean"},"security":{"type":"boolean","description":"Run the data-classification security lint (scans function return types for Private/Pii/Secret leaks). Off by default — it forces expensive return-type inference on every function and is not part of codegen. Enable here to always run it, or per-invocation via `pikku all --security`. Pair with `failOnError` to gate a build/CI on leaks."},"tsc":{"type":"boolean","description":"After codegen, run a real `tsc --noEmit` over the project's tsconfig and fail on type errors. `tsc` prints full diagnostics with code frames; `tscSummary` prints a compact one-line-per-error render (no code frames, capped) that's cheap for AI agents / CI logs. Off by default; enable per invocation via `pikku all --tsc` / `--tsc-summary`."},"tscSummary":{"type":"boolean"},"diff":{"type":"boolean","description":"After a successful codegen run, emit a structural diff of the generated `.pikku` meta (functions/wirings/workflows/emails added/removed/changed vs the state before this run) as a `PIKKU_DIFF <json>` line on stdout. Only emitted on exit 0. Off by default; enable per invocation via `pikku all --diff`. Consumed by the sandbox \"what changed\" build card."},"lint":{"type":"object","properties":{"servicesNotDestructured":{"type":"string","enum":["off","warn","error"]},"wiresNotDestructured":{"type":"string","enum":["off","warn","error"]},"functionDynamicImport":{"type":"string","enum":["off","warn","error"]}},"additionalProperties":false},"addonMetaJsonFile":{"type":"string"},"globalHTTPPrefix":{"type":"string"},"binary":{"type":"object","properties":{"entrypoint":{"type":"string"},"output":{"type":"string"},"targets":{"type":"array","items":{"type":"string"}}},"required":["entrypoint","output"],"additionalProperties":false},"deploy":{"type":"object","properties":{"providers":{"type":"object","additionalProperties":{"type":"string"}},"defaultProvider":{"type":"string"},"serverlessIncompatible":{"type":"array","items":{"type":"string"}},"defaultTarget":{"type":"string","enum":["serverless","server"],"description":"Default deploy target for functions that don't declare an explicit `deploy` flag and don't use a serverless-incompatible service. Defaults to 'serverless'."}},"required":["providers"],"additionalProperties":false},"namedFilters":{"type":"object","additionalProperties":{"$ref":"#/definitions/InspectorFilters"},"description":"Named filter presets keyed by name, used via CLI --filter <name>."},"filters":{"$ref":"#/definitions/InspectorFilters"}},"required":["addonTypesFile","agentMapDeclarationFile","agentTypesFile","agentWiringMetaFile","agentWiringMetaJsonFile","agentWiringsFile","bootstrapFile","channelContractsMetaFile","channelContractsMetaJsonFile","channelsMapDeclarationFile","channelsTypesFile","channelsWiringFile","channelsWiringMetaFile","channelsWiringMetaJsonFile","cliBootstrapFile","cliContractsMetaFile","cliContractsMetaJsonFile","cliTypesFile","cliWiringMetaFile","cliWiringMetaJsonFile","cliWiringsFile","configDir","consoleFunctionsFile","credentialsFile","credentialsMetaJsonFile","eventsChannelFile","filters","functionTypesFile","functionsFile","functionsMetaFile","functionsMetaJsonFile","gatewaysWiringFile","gatewaysWiringMetaFile","gatewaysWiringMetaJsonFile","httpContractsMetaFile","httpContractsMetaJsonFile","httpMapDeclarationFile","httpTypesFile","httpWiringMetaFile","httpWiringMetaJsonFile","httpWiringsFile","mcpJsonFile","mcpTypesFile","mcpWiringsFile","mcpWiringsMetaFile","mcpWiringsMetaJsonFile","middlewareFile","middlewareGroupsMetaJsonFile","nodeTypesFile","outDir","packageFile","packageMappings","permissionsFile","permissionsGroupsMetaJsonFile","publicAgentFile","publicRpcFile","queueMapDeclarationFile","queueTypesFile","queueWorkersWiringFile","queueWorkersWiringMetaFile","queueWorkersWiringMetaJsonFile","rootDir","rpcInternalMapDeclarationFile","rpcInternalWiringMetaFile","rpcInternalWiringMetaJsonFile","rpcMapDeclarationFile","rpcRemoteMapDeclarationFile","scenarioActorsFile","scenariosFunctionsFile","schedulersTypesFile","schedulersWiringFile","schedulersWiringMetaFile","schedulersWiringMetaJsonFile","schemaDirectory","scopeTypesFile","scopesFile","scopesMetaJsonFile","secretTypesFile","secretsFile","secretsMetaJsonFile","servicesFile","srcDirectories","triggerSourcesMetaFile","triggerSourcesMetaJsonFile","triggersTypesFile","triggersWiringFile","triggersWiringMetaFile","triggersWiringMetaJsonFile","tsconfig","typesDeclarationFile","variableTypesFile","variablesFile","variablesMetaJsonFile","workflowMapDeclarationFile","workflowMetaDir","workflowRoutesFile","workflowTypesFile","workflowsWiringFile","workflowsWiringMetaFile","workflowsWorkersFile"],"definitions":{"OpenAPISpecInfo":{"type":"object","properties":{"info":{"type":"object","properties":{"title":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"termsOfService":{"type":"string"},"contact":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"email":{"type":"string"}},"additionalProperties":false},"license":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name"],"additionalProperties":false}},"required":["title","version","description"],"additionalProperties":false},"servers":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"}},"required":["url"],"additionalProperties":false}},"tags":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"],"additionalProperties":false}},"externalDocs":{"type":"object","properties":{"description":{"type":"string"},"url":{"type":"string"}},"required":["url"],"additionalProperties":false},"securitySchemes":{"type":"object"},"security":{"type":"array","items":{"type":"object","additionalProperties":{"type":"array","items":{}}}}},"required":["info","servers"],"additionalProperties":false},"PikkuScaffoldFeature":{"type":["string","boolean"],"enum":["auth","no-auth",false]},"InspectorFilters":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"wires":{"type":"array","items":{"type":"string"}},"directories":{"type":"array","items":{"type":"string"}},"httpRoutes":{"type":"array","items":{"type":"string"}},"httpMethods":{"type":"array","items":{"type":"string"}},"excludeNames":{"type":"array","items":{"type":"string"}},"excludeTags":{"type":"array","items":{"type":"string"}},"excludeWires":{"type":"array","items":{"type":"string"}},"excludeDirectories":{"type":"array","items":{"type":"string"}},"excludeHttpRoutes":{"type":"array","items":{"type":"string"}},"excludeHttpMethods":{"type":"array","items":{"type":"string"}},"target":{"type":"array","items":{"type":"string","enum":["serverless","server"]}},"excludeTarget":{"type":"array","items":{"type":"string","enum":["serverless","server"]}},"serverlessIncompatible":{"type":"array","items":{"type":"string"}},"defaultTarget":{"type":"string","enum":["serverless","server"]}},"additionalProperties":false}}}