@pikku/skills 0.12.63 → 0.12.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.63",
+  "version": "0.12.66",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/skills/pikku-addon/SKILL.md

@@ -200,7 +200,10 @@ npx pikku new addon stripe --display-name Stripe --category Payments --dir addon
 ```
 
 **Handed an OpenAPI or Swagger spec?** Don't hand-write the functions —
-`pikku new addon <name> --openapi <spec>` generates one function per operation,
+`pikku new addon <name> --openapi <spec>` generates one function per operation
+(`<spec>` is a path, a URL, or a registry catalogue name such as
+`amazonaws.com:applicationcostprofiler`; inside an app,
+`pikku addons add <catalogue-name>` does the same and picks `--auth` for you),
 with its schemas, service and credential. Read `references/openapi.md`.
 
 This generates `package.json` (exports `.pikku/*` + `dist/`), `pikku.config.json` (`addon: true`), `tsconfig.json` (`#pikku` path mapping), `src/services.ts`, `src/functions/`, and `types/application-types.d.ts`. For the full file contents/exports you rarely hand-edit, read `references/addon-package-manifest.md`.
@@ -421,18 +424,27 @@ export default definePlugin({
   addons only; Studio enforces that). `layout: 'bare'` renders without the shell.
 - Titles are message keys in the addon's `messages/{locale}.json`, found by
   convention next to its `package.json`; there is no field for them.
+- `agent: 'name'` makes that agent answer in Studio's chat panel (a second tab
+  beside the general chat) while the screen is open. It resolves to
+  `agents/<name>.md` at the addon's package root: the agent's instructions,
+  which name the skills it follows (plain folders `skills/<name>/SKILL.md`).
+  `agent: 'studio:<name>'` instead picks an agent Studio ships; `pikku all` only
+  checks the format and looks up no file.
+  The file starts with frontmatter whose `title` and `description` are message
+  keys in `messages/en.json`. The name matches `/^[a-z][a-z0-9-]*$/`.
 - `scopes` only hide the screen. The addon's functions must enforce the same
   scopes.
 
 The inspector reads every field statically, so each must be a literal.
 `pikku all` fails on:
 
-| Code   | When                                                         |
-| ------ | ------------------------------------------------------------ |
-| PKU345 | a field is not a literal (variable, call, spread, bad value) |
-| PKU357 | two screens of the addon use the same path                   |
-| PKU358 | a title key is missing from `messages/en.json`               |
-| PKU359 | `nav.badge` names no function of the addon                   |
+| Code   | When                                                                                                 |
+| ------ | ---------------------------------------------------------------------------------------------------- |
+| PKU345 | a field is not a literal (variable, call, spread, bad value)                                         |
+| PKU357 | two screens of the addon use the same path                                                           |
+| PKU358 | a title or agent frontmatter key is missing from `messages/en.json`                                  |
+| PKU359 | `nav.badge` names no function of the addon                                                           |
+| PKU365 | `agent` is neither a name nor `studio:<name>`, or a name has no non-empty `agents/<name>.md`, or no frontmatter `title` and `description` |
 
 A key missing from another locale's catalog is a warning.
 

package/skills/pikku-addon/references/openapi.md

@@ -11,7 +11,8 @@
 - 6 — Check the spec against the real API
 - Then
 
-When you are handed an OpenAPI or Swagger spec — a file, or a URL to one — the
+When you are handed an OpenAPI or Swagger spec — a file, a URL to one, or the
+name of one in the registry's catalogue (`https://www.pikku.dev/openapis`) — the
 API it describes becomes an addon: one function per operation, each with its
 input and output schemas, behind one service that makes the HTTP calls. Say so
 before starting ("This is an OpenAPI spec — I'll turn it into an addon first"),
@@ -26,7 +27,23 @@ A JSON or YAML document with a top-level `openapi` key (3.x) or `swagger` key
 
 ## 1 — Look at the spec first
 
-`--openapi` takes a path or a URL. A spec published only to signed-in callers
+`--openapi` takes a path, a URL, or a catalogue name such as
+`amazonaws.com:applicationcostprofiler`. A name is anything that is neither a
+URL, a path, nor a `.json`/`.yaml` file; it is looked up in the registry
+(`--registry`, else `pikku.config.json`'s `registry`, else
+`https://api.pikkustudio.app`) and generated from the entry's spec URL. A name
+the registry does not know is refused before anything is written. On the
+website the page URL is a slug (`amazonaws-com-applicationcostprofiler`); the
+name to pass is the one the page's command shows, with its `.` and `:`.
+
+For a catalogue entry inside an app, the short form is
+`pikku addons add amazonaws.com:applicationcostprofiler`. It names the addon
+after the entry (`amazonaws-applicationcostprofiler`) and takes `--auth` from
+what the registry records: `none` for a public API, `user` for OAuth or a key
+each user brings, `shared` for a key the app holds, and `user` when the registry
+does not know. It prints the mode it picked; pass `--auth` to override it.
+
+A spec published only to signed-in callers
 takes the key the way the API reads it: `--openapi-header "NAME: value"`
 (repeatable), or in the URL's query string when the API reads it there
 (Dolibarr's explorer takes `?DOLAPIKEY=`). A 401 while fetching says which.
@@ -40,7 +57,7 @@ Keep a copy in `specs/` as the record of what the addon was generated from.
 ## 2 — Generate, from the app's root
 
 ```bash
-bunx --bun pikku new addon <name> --openapi <path-or-url>
+bunx --bun pikku new addon <name> --openapi <path-url-or-catalogue-name>
 ```
 
 One command. Inside an app it writes `packages/addon-<name>` as

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

@@ -197,7 +197,7 @@ function authMiddleware(req, res, next) {
 **Pikku:**
 
 ```typescript
-import { authBearer } from '@pikku/core/middleware'
+import { authBearer } from '#pikku/middleware'
 
 // One line - handles token extraction, JWT verification, session population
 addHTTPMiddleware('*', [authBearer({})])

package/skills/pikku-meta/references/versioning.md

@@ -137,11 +137,11 @@ the manifest alone. Fix the contract or bump the version, then run it again.
 `check` is a within-repo gate — "you changed a contract without bumping
 `version:`". `release` is a release question — "what does this build owe the
 clients of the last release, and how do we ship it?". The baseline is
-`surface.pikku.json`, the snapshot committed by the previous release.
+`pikku.surface.json`, the snapshot committed by the previous release.
 
 ```bash
 npx pikku release init                                   # first run: snapshot + CHANGELOG.md
-npx pikku release diff                                   # vs surface.pikku.json
+npx pikku release diff                                   # vs pikku.surface.json
 npx pikku release diff --against https://api.acme.com/surface.json  # vs any baseline
 npx pikku release diff --fail-on major                   # PR gate
 npx pikku release snapshot --out surface.json            # write a snapshot
@@ -162,7 +162,7 @@ writes it; it never commits, tags or pushes. Who does that is your call — you
 with plain git, or a platform with its own credentials.
 
 `prepare` runs on a checkout of `origin/staging` after `pikku all`. It diffs the
-surface against `surface.pikku.json`, reads the commits production does not have
+surface against `pikku.surface.json`, reads the commits production does not have
 yet, bumps `package.json`, prepends a `CHANGELOG.md` section and rewrites the
 snapshot. No commits since the last release means nothing to release. It
 refuses when `main` has commits `staging` lacks (merge `main` into `staging`
@@ -174,7 +174,7 @@ Shipping is then one commit on top of that trunk sha:
 
 ```bash
 npx pikku release prepare
-git add package.json CHANGELOG.md surface.pikku.json
+git add package.json CHANGELOG.md pikku.surface.json
 git commit -m "release: v0.4.0"
 git tag v0.4.0
 git push --atomic origin HEAD:staging HEAD:main v0.4.0

package/skills/pikku-middleware/SKILL.md

@@ -82,7 +82,7 @@ wireHTTP({
 Runs before everything else, across every wire type: HTTP, Queue, Channel, Trigger, Scheduler, Workflow, Agent, CLI, MCP. Use it for cross-cutting concerns (e.g. telemetry) that must wrap every invocation regardless of transport.
 
 ```typescript
-import { addGlobalMiddleware } from '@pikku/core/middleware'
+import { addGlobalMiddleware } from '#pikku/middleware'
 import { telemetryOuter, telemetryInner } from '@pikku/core/middleware'
 
 addGlobalMiddleware([telemetryOuter({ environmentId: env.STAGE_ID })]) // wraps the full call
@@ -95,7 +95,7 @@ addGlobalMiddleware([telemetryInner({ environmentId: env.STAGE_ID })]) // closes
 
 ```typescript
 import { addHTTPMiddleware } from '@pikku/core/http'
-import { cors, authBearer } from '@pikku/core/middleware'
+import { cors, authBearer } from '#pikku/middleware'
 
 // All routes
 addHTTPMiddleware('*', [

package/skills/pikku-react/references/client.md

@@ -239,11 +239,29 @@ pikku.fetch.setHeader('x-tenant', tenantId)
 `authHeaders.jwt` becomes `Authorization: Bearer …` and `authHeaders.apiKey`
 becomes `X-API-KEY`; setting a JWT takes precedence over an API key.
 
+## Generated client files
+
+Name any of these under `clientFiles` in `pikku.config.json` and `pikku all` writes them, with
+import paths computed from the config:
+
+- `typesFile` — `RPCInput<'name'>`, `RPCOutput<'name'>`, `FlattenedRPCMap` (and `AnalyticsEvent`
+  when `scaffold.analytics` is on). Use these instead of reaching into the functions package.
+- `envFile` — `apiUrl()`, `basePath()`, `appHref(path)`.
+- `rpcFile` — `rpc()`, a client for code outside React such as a route `beforeLoad`. It forwards
+  the request cookie during SSR (TanStack Start). Needs `envFile`.
+- `authClientFile` — the Better Auth client glue from `@pikku/better-auth/client`. Needs
+  `rpcFile`, `envFile` and a `getSession` function; `clientAuth` sets the login and home paths.
+
+In `vite.config.ts`, `pikkuVite()` from `@pikku/vite` adds `testIds()` and, with Better Auth, the
+dev cross-site session plugin. `pikku dev` runs every frontend that sets `dev.command`
+(`--frontend a,b`, `--no-frontends`) and creates `BETTER_AUTH_SECRET` in `.env` on first run.
+
 ## What NOT to do
 
 - Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`
   goes once at the app root, the instance flows through Context.
 - Don't call `usePikkuRPC()` outside a `<PikkuProvider>` — it throws.
+- Don't copy a `rpc.ts` or `env.ts` between apps — generate them with `rpcFile` and `envFile`.
 - Don't write a custom RPC client. The generated one already covers every
   exposed function with full types.
 - Don't hardcode user-facing strings. Every display string goes through an

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

@@ -44,7 +44,7 @@ permissions were removed in #972. Authorization lives on the function's own
 ### `pikkuChannelMiddleware(fn)`
 
 ```typescript
-import { pikkuChannelMiddleware } from '@pikku/core/middleware'
+import { pikkuChannelMiddleware } from '#pikku/middleware'
 
 const middleware = pikkuChannelMiddleware(async (services, event, next) => {
   // Transform or filter events before/after

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

@@ -98,7 +98,7 @@ Authorization is not a wiring concern — declare it on the function via `permis
 ### Middleware
 
 ```typescript
-import { cors, authBearer } from '@pikku/core/middleware'
+import { cors, authBearer } from '#pikku/middleware'
 
 // Global middleware
 addHTTPMiddleware('*', [
@@ -206,7 +206,7 @@ export const getBook = pikkuFunc({
 
 // wirings/books.http.ts — same defineHTTPRoutes/wireHTTPRoutes shape as the Route Groups example above
 import { addHTTPMiddleware } from '#pikku/middleware'
-import { cors, authBearer } from '@pikku/core/middleware'
+import { cors, authBearer } from '#pikku/middleware'
 
 addHTTPMiddleware('*', [cors(), authBearer()])
 ```