@pikku/skills 0.12.1 → 0.12.4

package/package.json

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

@@ -16,7 +16,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -15,7 +15,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -15,7 +15,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

package/skills/pikku-aws/SKILL.md

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

package/skills/pikku-backblaze/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -54,7 +54,7 @@ Better Auth owns its own HTTP surface, database tables, and session cookie. The
 1. **`pikkuBetterAuth(factory)`** — you export ONE `pikkuBetterAuth` call whose factory returns a configured `betterAuth({...})` instance. The pikku CLI inspects this export and generates everything else.
 2. **Generated `auth.gen.ts`** — a catch-all `${basePath}{/*splat}` HTTP route per method (GET + POST) that forwards every request under the base path to better-auth's own internal router. The enabled providers and plugins are written to `auth/pikku-auth-meta.gen.json` (read by the console SSO page via `getAuthProviders`).
 3. **Generated session middleware** — with `session.cookieCache` enabled (recommended), a separate `auth-middleware.gen.ts` adds the lean stateless `betterAuthStatelessSession()`; without it, `auth.gen.ts` adds the stateful `betterAuthSession()` that bundles the full server into every unit. See "Stateless session" below.
-4. **Generated `auth-secrets.gen.ts`** — a `wireSecret` for `BETTER_AUTH_SECRET` and for each social provider's OAuth credentials, plus a `wireVariable` for any non-secret provider config (e.g. `tenantId`).
+4. **Generated `auth-secrets.gen.ts`** — a `defineSecret` for `BETTER_AUTH_SECRET` and for each social provider's OAuth credentials, plus a `defineVariable` for any non-secret provider config (e.g. `tenantId`).
 
 You do NOT hand-write routes, the session middleware, or the secret wiring — `pikkuBetterAuth` + the CLI generate all of it. Re-run `pikku all` to regenerate.
 
@@ -86,7 +86,12 @@ export const auth = pikkuBetterAuth(async ({ secrets }) => {
     secret: BETTER_AUTH_SECRET,
     // memoryAdapter needs an array per model — `{}` throws "Model user not found"
     // at runtime. Swap for the Kysely adapter in production (see below).
-    database: memoryAdapter({ user: [], session: [], account: [], verification: [] }),
+    database: memoryAdapter({
+      user: [],
+      session: [],
+      account: [],
+      verification: [],
+    }),
     emailAndPassword: { enabled: true },
     // ALWAYS enable for deployed apps — see "Stateless session" below.
     session: { cookieCache: { enabled: true } },
@@ -98,7 +103,8 @@ export const auth = pikkuBetterAuth(async ({ secrets }) => {
 ```
 
 **Key points:**
-- `socialProviders` keys must be string literals — the CLI reads them statically to emit a `wireSecret` per provider. Provider keys mirror better-auth's built-in ids exactly (e.g. `microsoft`, NOT `microsoft-entra-id`; `cognito`; `github`).
+
+- `socialProviders` keys must be string literals — the CLI reads them statically to emit a `defineSecret` per provider. Provider keys mirror better-auth's built-in ids exactly (e.g. `microsoft`, NOT `microsoft-entra-id`; `cognito`; `github`).
 - The factory runs lazily on the first auth request, so it pulls secrets/DB off the injected `services`.
 - The default `basePath` is `/api/auth`. Override it by passing `basePath` to `betterAuth`.
 - **Enable `session: { cookieCache: { enabled: true } }`** so non-auth units tree-shake the better-auth server out (see below).
@@ -115,7 +121,7 @@ Enabling `session: { cookieCache: { enabled: true } }` makes the CLI split out a
 
 **Customizing the session bridge (`mapSession`, `impersonation`, `apiKey`, …):** you do NOT chain a second middleware on top of the generated one — register your OWN global session middleware and the CLI steps aside (it stops generating its default). This works on both paths and is detected the same way:
 
-- **Stateless (cookieCache on):** register `betterAuthStatelessSession({ mapSession })` **globally** — `addHTTPMiddleware('*', [...])` or `addGlobalMiddleware([...])`. The CLI sees the global registration and skips emitting `auth-middleware.gen.ts` (pikkujs/pikku#754), so you keep cookieCache's lean bundles *and* your custom fields.
+- **Stateless (cookieCache on):** register `betterAuthStatelessSession({ mapSession })` **globally** — `addHTTPMiddleware('*', [...])` or `addGlobalMiddleware([...])`. The CLI sees the global registration and skips emitting `auth-middleware.gen.ts` (pikkujs/pikku#754), so you keep cookieCache's lean bundles _and_ your custom fields.
 - **Stateful (cookieCache off):** register `betterAuthSession({ mapSession, impersonation })` **globally**. The CLI detects it (`hasUserSessionMiddleware`) and omits its own `addHTTPMiddleware('*', [betterAuthSession()])` from `auth.gen.ts` — so there's exactly one session bridge in the chain, yours.
 
 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.
@@ -129,22 +135,22 @@ 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` |
+| 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
+Declare the tree in your own `defineScope` (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({
+defineScope({
   admin: {
     displayName: 'Administration',
     description: 'Capabilities that act on the application as a whole',
@@ -173,7 +179,7 @@ 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
+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
@@ -184,9 +190,9 @@ For real deployments swap `memoryAdapter` for the Kysely adapter backed by an in
 import { kyselyAdapter } from 'better-auth/adapters/kysely'
 
 export const auth = pikkuBetterAuth(async ({ secrets, kysely }) => {
-  const { BETTER_AUTH_SECRET } = await secrets.getSecrets<{ BETTER_AUTH_SECRET: string }>([
-    'BETTER_AUTH_SECRET',
-  ])
+  const { BETTER_AUTH_SECRET } = await secrets.getSecrets<{
+    BETTER_AUTH_SECRET: string
+  }>(['BETTER_AUTH_SECRET'])
   return betterAuth({
     secret: BETTER_AUTH_SECRET,
     database: kyselyAdapter(kysely, { type: 'postgres' }),
@@ -204,7 +210,7 @@ If you place `auth.ts` under `srcDirectories` it is inspected automatically. The
 
 ## Social Providers needing extra config
 
-Some providers require non-secret config alongside the OAuth secret — the CLI emits a `wireVariable` for these:
+Some providers require non-secret config alongside the OAuth secret — the CLI emits a `defineVariable` for these:
 
 - `microsoft` → `MICROSOFT_TENANT_ID` (or `"common"`)
 - `cognito` → `COGNITO_DOMAIN`, `COGNITO_REGION`, `COGNITO_USER_POOL_ID`
@@ -221,7 +227,12 @@ export const auth = pikkuBetterAuth(async ({ secrets, variables }) => {
 
   return betterAuth({
     secret: BETTER_AUTH_SECRET,
-    database: memoryAdapter({ user: [], session: [], account: [], verification: [] }),
+    database: memoryAdapter({
+      user: [],
+      session: [],
+      account: [],
+      verification: [],
+    }),
     socialProviders: {
       microsoft: { ...MICROSOFT_OAUTH, tenantId: MICROSOFT_TENANT_ID },
     },
@@ -258,13 +269,13 @@ For public endpoints that optionally vary by viewer, use `pikkuSessionlessFunc`
 
 Better Auth serves everything under `basePath` (default `/api/auth`). Call these directly — the Pikku SDK does not wrap them.
 
-| Action | Request | Result |
-|---|---|---|
-| Sign up | `POST /api/auth/sign-up/email` `{ name, email, password }` | 200 + `better-auth.session_token` cookie |
-| Log in | `POST /api/auth/sign-in/email` `{ email, password }` | 200 + cookie; wrong creds → 401 `{ code: "INVALID_EMAIL_OR_PASSWORD" }` |
-| Session | `GET /api/auth/get-session` | `{ session, user }` or `null` |
-| Social sign-in | `POST /api/auth/sign-in/social` `{ provider, callbackURL }` | 200 `{ url, redirect }` (authorize URL) |
-| Sign out | `POST /api/auth/sign-out` | 200, clears cookie |
+| Action         | Request                                                     | Result                                                                  |
+| -------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Sign up        | `POST /api/auth/sign-up/email` `{ name, email, password }`  | 200 + `better-auth.session_token` cookie                                |
+| Log in         | `POST /api/auth/sign-in/email` `{ email, password }`        | 200 + cookie; wrong creds → 401 `{ code: "INVALID_EMAIL_OR_PASSWORD" }` |
+| Session        | `GET /api/auth/get-session`                                 | `{ session, user }` or `null`                                           |
+| Social sign-in | `POST /api/auth/sign-in/social` `{ provider, callbackURL }` | 200 `{ url, redirect }` (authorize URL)                                 |
+| Sign out       | `POST /api/auth/sign-out`                                   | 200, clears cookie                                                      |
 
 **`Origin` header on state-changing POSTs:** better-auth enforces an `Origin` header matching `baseURL` on POSTs such as sign-out — omit it and you get `403`. Browsers send it automatically; server-to-server callers must set it.
 

package/skills/pikku-cli/SKILL.md

@@ -15,7 +15,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

package/skills/pikku-concepts/SKILL.md

@@ -17,7 +17,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.
@@ -221,6 +221,13 @@ const apiKey = services.variables.get('API_KEY')
 
 `process.env` belongs in server bootstrap code (`start.ts`) only.
 
+## Secrets
+
+`secrets` is not part of a function's services. It is available only in
+`pikkuServices`, `pikkuWireServices`, addon service factories and middleware —
+read it there, give the value to a service, and have the function ask that
+service. Reaching for it through a cast throws at runtime.
+
 ## Testing
 
 Functions are easily testable because they're pure:

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

@@ -18,8 +18,8 @@ Authoritative mapping table plus side-by-side code examples showing how common b
 | **Cron / Scheduled tasks**              | `wireScheduler`                                                 | `pikku-cron`      |
 | **Module / Feature grouping**           | Tags + wiring files                                             | `pikku-concepts`  |
 | **Error handling**                      | Throw typed errors (`NotFoundError`, `ForbiddenError`)          | `pikku-concepts`  |
-| **Type-safe API client**                | `npx pikku all` generates clients                          | `pikku-concepts`  |
-| **Secrets / Config**                    | `wireSecret`, `wireVariable`, `services.variables`              | `pikku-config`    |
+| **Type-safe API client**                | `npx pikku all` generates clients                               | `pikku-concepts`  |
+| **Secrets / Config**                    | `defineSecret`, `defineVariable`, `services.variables`          | `pikku-config`    |
 
 ## Route Handler / Controller → pikkuFunc
 

package/skills/pikku-config/SKILL.md

@@ -2,8 +2,8 @@
 name: pikku-config
 description: >-
   Use when managing secrets, environment variables, config, or OAuth2 credentials in a Pikku app.
-  Covers wireSecret, wireVariable, wireOAuth2Credential, and typed config access. TRIGGER when:
-  code uses wireSecret/wireVariable/wireOAuth2Credential, user asks about env vars, secrets,
+  Covers defineSecret, defineVariable, defineCredential, and typed config access. TRIGGER when:
+  code uses defineSecret/defineVariable/defineCredential, user asks about env vars, secrets,
   config, OAuth2, or "how do I access environment variables". DO NOT TRIGGER when: user asks about
   API versioning/breaking changes (use pikku-versioning), service factories (use pikku-services),
   or auth middleware (use pikku-security).
@@ -16,7 +16,7 @@ installGroups: [core]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.
@@ -35,34 +35,53 @@ See `pikku-concepts` for the core mental model.
 
 ## Secrets & Variables
 
-### `wireSecret(config)`
+### `defineSecret(config)`
 
 Declare a secret with a Zod schema for type-safe access:
 
 ```typescript
-wireSecret({
+defineSecret({
   name: string, // Secret identifier
   schema: ZodSchema, // Shape and validation
 })
 ```
 
-### `wireVariable(config)`
+### `defineVariable(config)`
 
 Declare a variable (non-sensitive config) with a Zod schema:
 
 ```typescript
-wireVariable({
+defineVariable({
   name: string,
   schema: ZodSchema,
 })
 ```
 
-### Accessing in Functions
+### Accessing Secrets
+
+`secrets` is **not available inside functions, AI agents, workflows, permissions
+or any wire** — it is removed from their services type and throws at runtime if
+reached through a cast. Read it where you wire the app and hand the value to a
+service:
 
 ```typescript
-// Secrets — encrypted, sensitive values
-const config = await services.secrets.getSecret('SECRET_NAME')
+// services.ts — allowed
+const createSingletonServices = pikkuServices(async (config, { secrets }) => ({
+  stripe: new StripeService(await secrets.getSecret('STRIPE_CONFIG')),
+}))
+
+// functions/*.ts — ask the service, never the secret store
+export const charge = pikkuFunc({
+  func: async ({ stripe }, data) => stripe.charge(data.amount),
+})
+```
+
+Allowed: `pikkuServices`, `pikkuWireServices`, addon service factories,
+middleware. Everywhere else, the service you constructed is the interface.
+
+### Accessing Variables in Functions
 
+```typescript
 // Variables — plain-text configuration
 const flags = await services.variables.getVariableJSON('VARIABLE_NAME')
 
@@ -85,7 +104,7 @@ const createSingletonServices = pikkuServices(async (config) => ({
 
 ```typescript
 // Declare secrets with typed schemas
-wireSecret({
+defineSecret({
   name: 'STRIPE_CONFIG',
   schema: z.object({
     apiKey: z.string().startsWith('sk_'),
@@ -93,13 +112,13 @@ wireSecret({
   }),
 })
 
-// In your function — fully typed
+// In your services factory — fully typed
 const config = await secrets.getSecret('STRIPE_CONFIG')
 // config.apiKey       → string (autocompleted)
 // config.webhookSecret → string (autocompleted)
 
 // Declare variables
-wireVariable({
+defineVariable({
   name: 'FEATURE_FLAGS',
   schema: z.object({
     darkMode: z.boolean(),
@@ -113,33 +132,50 @@ const flags = await variables.getVariableJSON('FEATURE_FLAGS')
 // flags.maxUploadMB → number
 ```
 
-## OAuth2 Credentials
+## Credentials
 
-### `wireOAuth2Credential(config)`
+### `defineCredential(config)`
 
 ```typescript
-wireOAuth2Credential({
-  name: string,              // Credential identifier
-  displayName: string,       // Human-readable name
-  secretId: string,          // Secret holding { clientId, clientSecret }
-  tokenSecretId: string,     // Secret for token storage (auto-refreshed)
-  authorizationUrl: string,  // OAuth2 authorization endpoint
-  tokenUrl: string,          // OAuth2 token endpoint
-  scopes: string[],          // Required OAuth2 scopes
+defineCredential({
+  name: string,                  // Credential identifier
+  displayName: string,           // Human-readable name
+  type: 'wire' | 'singleton',    // Per-user ('wire') or platform-level ('singleton')
+  schema: ZodSchema,             // Shape of the stored credential
+  oauth2?: {                     // Omit entirely for a plain API key
+    appCredentialSecretId: string, // Secret holding { clientId, clientSecret }
+    tokenSecretId: string,         // Secret for token storage (auto-refreshed)
+    authorizationUrl: string,      // OAuth2 authorization endpoint
+    tokenUrl: string,              // OAuth2 token endpoint
+    scopes: string[],              // Required OAuth2 scopes
+  },
 })
 ```
 
 ### Usage
 
 ```typescript
-wireOAuth2Credential({
-  name: 'slackOAuth',
-  displayName: 'Slack OAuth',
-  secretId: 'SLACK_OAUTH_APP',
-  tokenSecretId: 'SLACK_OAUTH_TOKENS',
-  authorizationUrl: 'https://slack.com/oauth/v2/authorize',
-  tokenUrl: 'https://slack.com/api/oauth.v2.access',
-  scopes: ['chat:write', 'channels:read'],
+// Per-user API key — no oauth2 block
+defineCredential({
+  name: 'stripe',
+  displayName: 'Stripe API Key',
+  type: 'wire',
+  schema: z.object({ apiKey: z.string() }),
+})
+
+// Platform-level OAuth (singleton)
+defineCredential({
+  name: 'slack',
+  displayName: 'Slack',
+  type: 'singleton',
+  schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+  oauth2: {
+    appCredentialSecretId: 'SLACK_OAUTH_APP',
+    tokenSecretId: 'SLACK_OAUTH_TOKENS',
+    authorizationUrl: 'https://slack.com/oauth/v2/authorize',
+    tokenUrl: 'https://slack.com/api/oauth.v2.access',
+    scopes: ['chat:write', 'channels:read'],
+  },
 })
 
 // In your function — tokens refresh automatically
@@ -171,7 +207,7 @@ const apiKey = services.variables.get('API_KEY')
 
 ```typescript
 // schemas/config.ts
-wireSecret({
+defineSecret({
   name: 'DATABASE_CONFIG',
   schema: z.object({
     connectionString: z.string().url(),
@@ -179,7 +215,7 @@ wireSecret({
   }),
 })
 
-wireVariable({
+defineVariable({
   name: 'APP_CONFIG',
   schema: z.object({
     appName: z.string(),
@@ -188,20 +224,24 @@ wireVariable({
   }),
 })
 
-wireOAuth2Credential({
+defineCredential({
   name: 'githubOAuth',
   displayName: 'GitHub OAuth',
-  secretId: 'GITHUB_OAUTH_APP',
-  tokenSecretId: 'GITHUB_OAUTH_TOKENS',
-  authorizationUrl: 'https://github.com/login/oauth/authorize',
-  tokenUrl: 'https://github.com/login/oauth/access_token',
-  scopes: ['read:user', 'repo'],
+  type: 'wire',
+  schema: z.object({ accessToken: z.string(), refreshToken: z.string() }),
+  oauth2: {
+    appCredentialSecretId: 'GITHUB_OAUTH_APP',
+    tokenSecretId: 'GITHUB_OAUTH_TOKENS',
+    authorizationUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    scopes: ['read:user', 'repo'],
+  },
 })
 
 // functions/admin.functions.ts
 export const getAppStatus = pikkuSessionlessFunc({
   title: 'Get App Status',
-  func: async ({ variables, secrets }) => {
+  func: async ({ variables }) => {
     const appConfig = await variables.getVariableJSON('APP_CONFIG')
     return {
       appName: appConfig.appName,

package/skills/pikku-cron/SKILL.md

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -13,7 +13,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -14,7 +14,7 @@ installGroups: [fabric]
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -13,7 +13,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

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

@@ -14,7 +14,7 @@ description: >-
 
 Use this skill as an execution checklist, not reference material.
 
-1. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+1. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 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.

package/skills/pikku-fabric/SKILL.md

@@ -15,7 +15,7 @@ Use this skill as an execution checklist, not reference material.
    pikku fabric validate --json
    ```
    This prints every missing file, misconfigured field, and dependency gap with a `fixHint`. Address all `error` findings before proceeding — they block deploy. Resolve `warn` findings before testing — they cause runtime failures. `info` findings are best-practice gaps that are safe to defer.
-2. Discover before editing. Prefer OpenCode tools such as `pikku-meta` when available; otherwise run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
+2. Discover before editing. Run the relevant `pikku meta ... --json` command and inspect only the focused output you need.
 3. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, vendored packages, or broad build artifacts.
 4. Make the smallest source change that satisfies the task. Keep generated files generated, and avoid hand-editing SDKs, schema output, or typegen.
 5. Validate with the narrowest relevant command first, then run `pikku-verify` or `pikku all` when functions, wirings, schemas, or generated clients may have changed.
@@ -31,7 +31,7 @@ Always run project discovery first:
 yarn pikku meta context --json
 ```
 
-In OpenCode, call the `pikku-meta` tool before grepping or editing a Fabric app.
+Call the `pikku-meta` tool before grepping or editing a Fabric app.
 
 - Use `section: "context"` for the project map: functions, wires, workflows, capabilities, and source files.
 - Use `section: "clients"` before frontend/RPC work.
@@ -40,7 +40,7 @@ In OpenCode, call the `pikku-meta` tool before grepping or editing a Fabric app.
 
 Do not load every schema body by default; that wastes context and usually makes the model worse.
 
-For database work in OpenCode:
+For database work:
 
 - Use `pikku-db` for the actual attached Fabric database state: tables, columns, foreign keys, and applied migrations.
 - Use `pikku-meta` `section: "schemas"` for code-level JSON Schema contracts, not database introspection.
@@ -183,7 +183,7 @@ Links the repo to a Fabric project and declares its frontends:
 ```
 
 - `projectId`: written by `pikku fabric init` / `link`. Templates ship the
-  `__PROJECT_ID__` placeholder — that is *not* a link, and the CLI treats it as
+  `__PROJECT_ID__` placeholder — that is _not_ a link, and the CLI treats it as
   unlinked.
 - `production.domain`: optional custom domain. Production always maps to `main`;
   without a domain it lives on the platform `*.pikkufabric.app` hostnames.
@@ -290,7 +290,7 @@ The output card shows whether any breaking changes were detected.
 
 These apply in every Fabric app:
 
-- **No `process.env`** — use `variables.get('NAME')` and `secrets.getSecret('NAME')`. Declare with `wireVariable` / `wireSecret`.
+- **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 auth checks in function bodies** — use `permissions:` field on the function config with a `pikkuPermission` factory.
@@ -311,7 +311,7 @@ Fix every `error` and `warn` in the output before continuing. Then:
 1. **Replace the database layer**: swap PostgreSQL/MySQL queries for Kysely + libSQL. Convert schema to SQLite-compatible SQL migrations in `db/sqlite/`.
 2. **Replace route handlers with pikkuFuncs**: extract business logic into `pikkuFunc`/`pikkuSessionlessFunc`, add `wireHTTP` or `expose: true` for transport.
 3. **Replace DI/IoC with pikkuServices**: move service construction to `createSingletonServices` in `services.ts`.
-4. **Replace `process.env` calls** with `wireVariable`/`wireSecret` + `variables.get()`.
+4. **Replace `process.env` calls**: plain config becomes `defineVariable` + `variables.get()`, anything sensitive becomes `defineSecret` + `secrets.getSecret()`.
 5. **Add `pikku.config.json`** at project root with `srcDirectories`, `outDir`, and `clientFiles`.
 6. **Add `fabric.config.json`** at project root with `projectId`, `production.branch`, and `frontends`.
 7. **Run `pikku all`** — verify codegen succeeds and there are no type errors.