@pikku/skills 0.12.20 → 0.12.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/skills",
-  "version": "0.12.20",
+  "version": "0.12.21",
   "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-better-auth/SKILL.md

@@ -237,12 +237,12 @@ Banning is the one capability with a schema requirement, and it has its own
 small plugin:
 
 ```typescript
-import { ban } from '@pikku/better-auth'
+import { pikkuBan } from '@pikku/better-auth'
 
-betterAuth({ plugins: [ban()] })
+betterAuth({ plugins: [pikkuBan()] })
 ```
 
-`ban()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
+`pikkuBan()` adds `banned`, `banReason` and `banExpires` to `user` and refuses to
 create a session for a banned user, lapsing an expired ban as it goes. It makes
 no authorization decision — who may ban is decided by `admin:users:ban` — so it
 never needs to know about scopes or roles.
@@ -252,22 +252,28 @@ never needs to know about scopes or roles.
 Five, all imported from the package root and passed to `betterAuth({ plugins })`
 like any other. None is automatic — an app wires the ones it needs.
 
-| Plugin              | Plugin `id`        | Adds                                                                    | Use it when                                                   |
-| ------------------- | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
-| `ban()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
-| `actor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
-| `credentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
-| `delegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
-| `fabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+| Plugin                   | Plugin `id`        | Adds                                                                    | Use it when                                                   |
+| ------------------------ | ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `pikkuBan()`             | `pikku-ban`        | `user.banned/banReason/banExpires`                                      | You ban users (the schema + enforcement half of the above)    |
+| `pikkuActor()`           | `actor`            | `POST /sign-in/actor`, `user.actor`                                     | Scenarios or a dev switcher sign in as a persona              |
+| `pikkuCredentialOAuth()` | `credential-oauth` | `POST /credential-oauth/link`, `/credential-oauth/callback/:providerId` | An app links OAuth2 **API credentials** for a user            |
+| `pikkuDelegatedAuth()`   | `delegated-auth`   | `POST /sign-in/delegated`                                               | An imported upstream API is the system of record for identity |
+| `pikkuFabric()`          | `fabric`           | `POST /sign-in/fabric`                                                  | A Fabric-deployed app lets a control-plane operator in        |
+
+Every one carries a `pikku` prefix, because a `plugins: [...]` array mixes these
+with better-auth's own and a bare `actor()` next to `organization()` says
+nothing about where it came from. The unprefixed names — `ban`, `actor`,
+`credentialOAuth`, `delegatedAuth`, `fabric` — are still exported as deprecated
+aliases, so existing apps keep working.
 
 The plugin's `id` is what better-auth stores; the **export name** is what the
 inspector reads off your `plugins` array and what generated metadata is keyed
-by, so the two differ for `ban` and `delegatedAuth`.
+by, so the two differ for every one of them.
 
-#### `credentialOAuth()` — link API credentials, not identities
+#### `pikkuCredentialOAuth()` — link API credentials, not identities
 
 ```typescript
-credentialOAuth({
+pikkuCredentialOAuth({
   config: [
     {
       providerId: 'github',
@@ -308,10 +314,10 @@ by construction. Tokens land in better-auth's `account` table, so
 An undeclared `providerId` is a 404; an anonymous caller a 401; a refused
 singleton a 403 that leaves no platform user behind.
 
-#### `delegatedAuth()` — the upstream API is the identity provider
+#### `pikkuDelegatedAuth()` — the upstream API is the identity provider
 
 ```typescript
-delegatedAuth({
+pikkuDelegatedAuth({
   authenticate: async ({ email, password, apiKey }) => upstream.login(...),
   storeCredential: (userId, identity) =>
     credentialService.set('acme', identity.credential, userId),
@@ -338,10 +344,10 @@ a warning and the user still gets in.
 `storeCredential` failing, by contrast, **fails the sign-in**: every proxied
 call would be dead anyway.
 
-#### `fabric()` — control-plane operator sign-in
+#### `pikkuFabric()` — control-plane operator sign-in
 
 ```typescript
-fabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
+pikkuFabric({ publicKey: FABRIC_AUTH_PUBLIC_KEY, scopeService, logger })
 ```
 
 `POST /sign-in/fabric` verifies a short-lived RS256 token that the Fabric
@@ -468,9 +474,9 @@ someone" means **a particular kind of user** rather than one fixed admin.
 Register it explicitly — it is not automatic:
 
 ```typescript
-import { actor } from '@pikku/better-auth'
+import { pikkuActor } from '@pikku/better-auth'
 
-plugins: [actor({ secret: SCENARIO_ACTOR_SECRET })]
+plugins: [pikkuActor({ secret: SCENARIO_ACTOR_SECRET })]
 ```
 
 `POST ${basePath}/sign-in/actor` `{ email, secret, name? }` → 200 + the normal
@@ -585,7 +591,7 @@ await provisionPersonas(singletonServices, {
 ```
 
 It writes the same `banned` column the console's ban RPC writes (so it needs the
-`ban()` plugin wired, and says so if it isn't), revokes the account's sessions,
+`pikkuBan()` plugin wired, and says so if it isn't), revokes the account's sessions,
 and leaves the row, its grants and its history intact — provisioning lifts the
 ban again by itself if the persona comes back. Deleting is deliberately not
 offered: an actor row is referenced by whatever those scenarios did while it

package/skills/pikku-fabric/SKILL.md

@@ -129,8 +129,8 @@ a stage whose pages return 200 — the shell renders fine — while its first da
 read throws `no result` or a foreign-key violation on a row the seed was
 silently supplying.
 
-A Better Auth app has a second constraint: the plugins you enable (`ban()`,
-`actor()`, …) each declare columns, and `pikku db migrate` refuses to run while
+A Better Auth app has a second constraint: the plugins you enable (`pikkuBan()`,
+`pikkuActor()`, …) each declare columns, and `pikku db migrate` refuses to run while
 the applied schema is missing any of them. `pikku db generate` writes the
 migration that closes the gap.
 

package/skills/pikku-feature/SKILL.md

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