@pikku/skills 0.12.9 → 0.12.11

package/skills/pikku-build-app/references/multi-app.md

@@ -0,0 +1,117 @@
+# Adding a second frontend
+
+Read this when the split you recorded in Phase 2 is "separate apps" and you have
+reached the milestone that needs the second one. **Not before.** Cloning
+`apps/app` materialises a directory of copied screens; doing it during planning
+leaves `pikkufabric.config.json` pointing at an app nobody has designed yet.
+
+If the split is "one app with paths", you never need this file — add route
+segments under `/app` and give each audience its own entries in `useNavItems()`.
+
+## The clone
+
+```bash
+cp -R apps/app apps/admin
+rm -rf apps/admin/node_modules apps/admin/src/paraglide
+```
+
+`src/paraglide` is compiled from `messages/` by the Vite plugin on first run;
+copying it forward ships one app's compiled strings inside another.
+
+Then, in order:
+
+### 1. `apps/admin/package.json`
+
+- `name` → `@project/admin`
+- `dev` and `preview` ports → `7105`. Every frontend needs its own, or the second
+  one fails to bind and the dev runner looks like it hung.
+- the `--tsBuildInfoFile` path inside the **`tsc` script** → `admin-tsc.tsbuildinfo`.
+  In this template it is a CLI flag on that script (`tsc --noEmit --incremental
+  --tsBuildInfoFile node_modules/.cache/app-tsc.tsbuildinfo`), not a
+  `compilerOptions` entry — `tsconfig.json` needs no change. Left alone, the two
+  apps fight over one incremental cache and you get type errors that vanish on a
+  clean build: an hour of debugging for a one-word edit.
+
+### 2. `pikkufabric.config.json`
+
+This file is the source of truth for what apps exist, and it is read whether or
+not you ever deploy to Fabric.
+
+```json
+{
+  "projectId": "__PROJECT_ID__",
+  "frontends": {
+    "app": {
+      "cwd": "apps/app", "primary": true, "deploy": true, "kind": "ssr",
+      "dev": { "command": ["bun", "run", "dev"], "port": 7104, "healthPath": "/" },
+      "serves": "tenant",
+      "personas": ["visitor", "chidi"]
+    },
+    "admin": {
+      "cwd": "apps/admin", "primary": false, "deploy": true, "kind": "ssr",
+      "dev": { "command": ["bun", "run", "dev"], "port": 7105, "healthPath": "/" },
+      "serves": "owner",
+      "personas": ["amina", "bilal"]
+    }
+  }
+}
+```
+
+Two things to fix while you are in here, not just add:
+
+- **The shipped `app` entry may say `["yarn", "dev"]`** while the rest of the
+  project is driven with bun. Correct it. A frontend that starts under a package
+  manager the project does not use is a failure that only appears on someone
+  else's machine.
+- **`serves` and `personas` name real personas.** Every persona should appear
+  under exactly one frontend. A persona listed nowhere is a person with no way
+  in, and that is a design bug worth seeing now rather than at review.
+
+### 3. The dev runner
+
+`dev.mjs`, under the project's scripts directory, spawns `@project/app` **by
+name** and will silently never start your second app — the frontend simply is not
+there, with no error to explain it.
+
+Make it read the `frontends` map and spawn one child per entry, rather than
+adding a second hardcoded line. Two sources of truth for "which apps exist" is
+the drift this whole file is trying to avoid.
+
+### 4. `pikku.config.json` → `environments`
+
+`local.appUrl` points at one app. Add an environment per frontend (`local`,
+`local-admin`) so the browser scenario pass can drive either one. A browser
+scenario run against the wrong `appUrl` fails on a missing element and reads like
+a UI bug rather than a config one.
+
+### 5. Re-run `bun install`
+
+`apps/*` is already globbed in the root workspaces, so this just links the new
+one.
+
+## Sessions across two origins
+
+Better Auth lives once, at `/api/auth/*`, and every app proxies to it (see
+`vite.config.ts` — `/api/auth` keeps its prefix, everything else under `/api` is
+rewritten to the pikku dev server).
+
+- **In local dev, cookies are scoped by host and ignore the port**, so
+  `localhost:7104` and `localhost:7105` share a session. Convenient, and a trap:
+  the app boundary is invisible in dev and only the role check is doing work.
+  That is the correct design — but do not read a working dev session as evidence
+  the permission check exists. The refusal scenario is the evidence.
+- **In production on two subdomains**, the session cookie needs a parent domain
+  (`.example.com`) or each app gets its own login. Decide which, set it per the
+  `pikku-better-auth` skill, and record it in `knowledge/decisions/security/`.
+- **Never hardcode a host or port.** The API base resolves to same-origin `/api`.
+
+## Building the second app's screens
+
+Same rules as the first: pages in `apps/admin/src/pages/`, routes in
+`apps/admin/src/routes/`, the same generated hooks from
+`@project/functions-sdk/pikku/api.gen`, its own `useNavItems()`, its own
+`messages/` directory.
+
+A string used by both apps belongs to whichever app renders it. Duplicating it
+beats a shared bundle that couples the two apps together — the moment they share
+a string file, they share a release.

package/skills/pikku-build-app/references/ship.md

@@ -0,0 +1,98 @@
+# Shipping, and staying Fabric-ready
+
+Read this when the milestones are built and the scenarios are green — it is
+the last phase, and nothing in it is needed before then.
+
+## Ship it — open source, no platform
+
+`pikku deploy` builds and ships without any hosted service:
+
+```sh
+bunx --bun pikku deploy plan  --provider standalone --runtime bun
+bunx --bun pikku deploy apply --provider standalone --runtime bun
+```
+
+`standalone` comes from the installed `@pikku/deploy-standalone` adapter: it
+bundles the project into a single unit and emits either a `bundle.js` you run
+with Node, or a self-contained executable compiled with `bun build --compile`.
+`cloudflare` (the default) and `aws` are the other providers — read the
+`pikku-deploy-cloudflare` skill before using it, as it ships the handler
+factories the deploy codegen expects, and hand-rolling an `ExportedHandler` is
+how a worker deploy fails at runtime instead of at build.
+
+Always run `plan` before `apply`, and read it. It names what will be created,
+updated and deleted — the deletions are the reason to look.
+
+The frontends build independently (`bun run build` at the root builds every
+workspace). Serve each behind its own hostname, and put the API behind `/api` on
+**all of them**, mirroring the Vite proxy from the multi-app reference: `/api/auth/*` keeps its
+prefix, everything else under `/api/*` reaches the pikku server unprefixed. Get
+this wrong and sign-in fails on one app only, which is a miserable thing to debug.
+
+Before shipping, run the full gate:
+
+```sh
+bunx --bun pikku all --tsc-summary --fail-on-warn
+bunx --bun pikku validate
+bunx --bun pikku knowledge validate
+bunx --bun pikku scenario run local --spawn --coverage
+bunx --bun pikku scenario run local --spawn --run browser
+bun run build                     # every frontend workspace, type-checked
+```
+
+Keep `--coverage` on the release run even though you have been reading it per
+milestone (§7a). Each of those readings only covered the functions that
+milestone added; this is the first time the whole surface is measured at once,
+and it is where a function orphaned by a later refactor shows up.
+
+**The last two lines are not optional, and one of them is easy to talk yourself
+out of.** The server-side pass proves the functions; it renders nothing. The
+pages are client-rendered, so a component that throws still returns HTTP 200
+with an empty shell — the same trap §6 warns about, and the release gate is
+exactly where it gets shipped past. Run the browser pass, and run it **for every
+environment in `pikkufabric.config.json`**, not just the first:
+
+```sh
+bunx --bun pikku scenario run local-admin --spawn --run browser
+```
+
+`bun run build` is what type-checks each frontend (each app's `tsc` script runs
+`--noEmit`). `pikku all --tsc-summary` covers the functions package; it does not
+reach into the apps, so a broken screen passes every pikku command and fails on
+the deploy.
+
+`pikku all --security --fail-on-error` additionally runs the data-classification
+lint over function return types, catching a `Pii`/`Secret` field that leaks
+through an exposed function. Expensive, so run it before a release rather than on
+every save — but run it.
+
+## Staying Fabric-ready
+
+Everything above is open source. This is the contract that keeps
+`pikku fabric init` a one-command import later, instead of a migration.
+
+- **`pikkufabric.config.json` describes reality.** Every app has an entry with
+  the right `cwd`, `port`, `kind` and `dev.command`; exactly one is `primary`;
+  `serves` and `personas` name real personas from the personas section. Leave `projectId` as
+  `__PROJECT_ID__` — that placeholder means "unlinked", and `fabric init` writes
+  the real one. Do not invent a value to make it look configured.
+- **One `definePersonas` call**, every persona reachable through exactly one
+  frontend. Fabric materialises these as its virtual users; a persona nobody
+  serves imports as a person with no way in.
+- **`knowledge/` passes `validate`, with every milestone at `built`.** This is
+  the part Fabric itself reads and continues from.
+- **Every milestone has a passing scenario**, including its refusals.
+- **Permissions live in the `permissions` field**, not in function bodies and not
+  in the frontends. A check hidden in a component does not survive a new client.
+- **Nothing hardcodes a host, a port, or a `process.env` read inside a
+  function.** Secrets go through `defineSecret` and the injected `secrets`
+  service. This is the single most common reason a working local project fails
+  its first deploy — on any platform.
+- **Generated files stay generated.** No hand edits to `.pikku/`, `*.gen.*`, or
+  the SDK.
+- **`pikku validate` is clean**, and `pikku all` has no critical diagnostics.
+
+What you deliberately do NOT do: run any `pikku fabric` subcommand, add a card,
+or link a project. None of it is needed to build, test, critique, or deploy — it
+is needed the day the user wants Fabric to host and build it, and on that day, if
+this section holds, that day is one command long.

package/skills/pikku-build-app/references/theming.md

@@ -0,0 +1,70 @@
+# Authoring the theme
+
+Read this at the design step, once you have a direction to turn into a theme —
+whether the user described one in words, handed you a reference, or ran their own
+design step whose output you are implementing.
+
+Nothing in the open-source toolchain authors a theme for you. Fabric has the
+`fabric-theme` tool; without it, hand-authoring is the route, and it is a small
+job done in JSON.
+
+## Where the look lives
+
+```
+packages/mantine-theme/
+  themes/
+    default.json     # "Neutral" — the shipped scaffold
+    index.ts         # registers each theme JSON by id
+  active.json        # { "id": "default" } — which one is live
+  index.ts
+```
+
+Each theme JSON has two halves — `brand` (colours, fonts) and `structure`
+(radius, shadows, spacing, per-component `defaultProps`). To give the product an
+identity, add `themes/<name>.json`, register it in `themes/index.ts`, and point
+`active.json` at its id.
+
+`themes/index.ts` carries a `Generated by the fabric-theme tool — do not edit by
+hand` banner. **That instruction is about Fabric's generator, not about you.**
+Without that tool, hand-authoring is the only route, and the file is a three-line
+registry. Edit it, and replace the banner with a line saying the themes here are
+hand-authored — otherwise the next agent reads the warning and leaves the app on
+Neutral.
+
+Turning §1's answer into a theme:
+
+- **Colour before anything else.** `brand.colors.primary` plus
+  `structure.primaryShade` and `autoContrast` carry most of the identity;
+  `@mantine/colors-generator` (already a dependency) expands one hex into a full
+  scale.
+- **Fonts are the other half of the register**, and the half people skip. A serif
+  heading font against a neutral body is a different product from the system
+  stack, and it is one field.
+- **`structure.radius` and `structure.shadows` set the temperature.** Sharp
+  corners and flat surfaces read technical; large radii and soft shadows read
+  consumer. Neutral's `md: 10px` is the middle of the road on purpose.
+- **`structure.components` defaultProps is where a design decision becomes
+  automatic** — `Card` with `withBorder` everywhere, `NavLink` as `light`. Put
+  the repeated decision here rather than on every instance.
+- **`defaultColorScheme` and `darkColors` are a real choice**, not a toggle to
+  leave alone. A tool people live in all day is often better dark by default.
+
+Then **write the direction into `knowledge/decisions/design/`** — the words the
+user gave you, what you chose, and what it rules out. The JSON records what the
+theme is; only the note records why.
+
+**Set the theme once, don't hardcode colours per component.** A screen full of
+inline `color="blue"` and one-off hex values is why apps look templated. Change
+the theme, not the components — and keep it theme-aware for light and dark.
+
+With two apps, **share the theme package and vary the register, not the
+palette.** A back-office can be denser and more tabular; a customer-facing app
+can be roomier and warmer — that is `structure` and layout, not a second `brand`.
+Two unrelated colour schemes read as two products from two companies.
+
+
+## If the user gave you no direction
+
+Neutral is a legitimate answer for an internal tool. But say so out loud when you
+hand the work over — an unremarked default reads as a choice, and the user will
+assume someone decided.

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

@@ -0,0 +1,239 @@
+---
+name: pikku-build-platform
+description: >-
+  Build an app that exercises every Pikku surface — workflows, schedules, queues, an AI agent,
+  realtime, MCP, multiple locales, contract versioning and scenario coverage — on top of the full
+  pikku-build-app workflow. For proving what the platform does, not for shipping the smallest
+  thing that works. TRIGGER when: the user picked "Platform", asked for a showcase or reference
+  app, or asked to demonstrate what Pikku can do. DO NOT TRIGGER when: the user wants a product
+  built (use pikku-build-app), something quick (use pikku-build-quick), or one specific surface
+  wired into an existing app — a single workflow, cron job or agent (use that surface's own skill,
+  e.g. pikku-workflow, pikku-cron, pikku-agent).
+installGroups: [core]
+---
+
+# Build a platform showcase on Pikku
+
+**This skill is a delta. `pikku-build-app` is the base — read it and follow it in
+full.** Everything there applies: knowledge base first, personas and roles,
+milestones planned then built one at a time, scenarios, design pass, deploy
+gates, Fabric-readiness. This file adds the surfaces that turn an app into a
+demonstration of the platform, and says where each one slots into that workflow.
+
+Read `pikku-build-app` now, then come back. Do not blend the two into one plan —
+the phases below hang off its phases by number.
+
+## What "platform" means here
+
+Breadth is the deliverable. A showcase that does one thing beautifully has
+failed; a showcase where every surface is a stub has also failed. The bar for
+each surface below: **it does something the app genuinely needs, and a scenario
+proves it.** A cron job that logs "tick" is not a schedule — it is a comment.
+
+Budget the extra surfaces at one milestone each. They are not free, and a
+half-wired workflow engine is worse than no workflow engine.
+
+## Choosing surfaces — during `pikku-build-app` §5 (planning)
+
+When you plan milestones, each surface below becomes its own milestone note in
+`knowledge/milestones/`, ordered after the spine it depends on.
+
+**Five are required, and if the domain does not motivate them you chose the
+wrong domain:** workflows, schedules, queues, an AI agent, and realtime. They are
+what "platform" means here, and a showcase missing one of them is a showcase of
+something else. Pick a domain that needs all five — that choice is yours to make
+at §1, and it is much cheaper than contriving a use later.
+
+The rest — MCP, triggers and webhooks, extra locales, contract versioning,
+addons — are chosen on merit. Write the motivation into the note. If you cannot
+name what one of *those* is for in this app, drop it and say why in
+`knowledge/decisions/`: a documented omission is a stronger showcase than a
+contrived inclusion.
+
+What is never acceptable is a required surface present as a stub. A cron job
+that logs `tick` does not become a schedule by existing, and it is worse than
+the documented omission because it claims to be finished.
+
+Most surfaces are switched on by the CLI rather than hand-wired:
+
+```sh
+bunx --bun pikku enable workflow      # workflow workers
+bunx --bun pikku enable agent         # public agent endpoints
+bunx --bun pikku enable events        # realtime events channel + SSE stream
+bunx --bun pikku enable remote-rpc    # internal RPC queue worker + HTTP endpoint
+bunx --bun pikku enable webhook       # outgoing webhook delivery queue worker
+bunx --bun pikku enable scenarios     # scenario instrumentation
+bunx --bun pikku enable console       # console functions
+bunx --bun pikku enable rpc           # public RPC endpoint
+```
+
+Each scaffolds a `*.gen.ts` and wires it. Run the enable, then `pikku all`, then
+write the function — not the other way round.
+
+## The surfaces
+
+Each has an installed skill that is authoritative on its API. Read it before
+writing the wiring; this section says what the surface is *for* and how to prove
+it, not how to call it.
+
+### Workflows — `pikku-workflow`
+
+The one that most changes how an app is built. A workflow is a durable,
+resumable, multi-step process — approval chains, onboarding, anything that waits
+on a human or a timer and must survive a restart.
+
+- **Motivation test:** is there a process here with more than one step and a
+  gap in the middle? If every operation completes in one request, you do not need
+  workflows and forcing one is noise.
+- **Prove it:** a scenario that starts the workflow, advances it as a second
+  persona, and asserts the end state. `pikku-workflows-client` covers driving it
+  from the UI.
+- Three workflows ship with the template. Read them before writing yours.
+
+### Schedules — `pikku-schedule` / `pikku-cron`
+
+Recurring work: a nightly rollup, a reminder sweep, an expiry pass.
+
+- **Motivation test:** something in the domain becomes true with the passage of
+  time rather than a user action. Rent falls due. A trial ends. A report is
+  monthly.
+- **Prove it:** invoke the scheduled function directly in a scenario and assert
+  its effect. Do not test by waiting.
+
+### Queues — `pikku-queue`
+
+Work that must happen but not now, and may retry: email fan-out, image
+processing, third-party calls that fail.
+
+- **Motivation test:** an operation the user should not wait for, or one that
+  fails in ways worth retrying.
+- **Prove it:** enqueue in one scenario step, assert the effect in a `then`.
+
+### An AI agent — `pikku-agent`, `pikku-ai-vercel`
+
+The template ships agent wiring and `@ai-sdk/openai`. An agent that answers
+questions over the app's own data is the showcase; a general chatbot is not.
+
+- **Give it real tools** — your own exposed RPCs, so it answers from the
+  database rather than from the model. `pikku all --strict-meta` fails a tool
+  with no description, which is the quality gate here: an undescribed tool is
+  offered to the model under its bare name and it will misuse it.
+- **Gate it.** `getAgentThreads` ships exposed and sessionless — PKU574 flags it.
+  Deciding who may reach the agent is part of building it.
+- **Prove it** with a scenario that asks something only the database knows.
+- Needs a model key. Read it through the injected `secrets` service with a
+  matching `defineSecret`, never `process.env`, or deploy has nothing to
+  provision (PKU951).
+
+### Realtime and events — `pikku-realtime`, `pikku-websocket`
+
+`pikku enable events` gives a realtime channel plus an SSE stream, and the
+generated typed client.
+
+- **Motivation test:** two people looking at the same thing at the same time, or
+  a long operation whose progress matters.
+- **Prove it:** a browser scenario is the only honest proof — assert the second
+  persona's screen changed without a reload.
+
+### MCP — `pikku-mcp`
+
+Exposes functions as Model Context Protocol tools, so an outside agent can drive
+the app. Cheap once functions exist, and a genuine differentiator to show.
+
+### Triggers and webhooks — `pikku-trigger`, `pikku enable webhook`
+
+Inbound triggers and outgoing webhook delivery. This is where `wireHTTP` is
+correct rather than a smell: a third-party caller needs a real REST shape.
+
+### Locales — `pikku-i18n`, `pikku-paraglide`
+
+`pikku-build-app` already requires every string to be a key. **Here, ship three
+locales, and make one of them RTL** (`pikku-rtl`). Two LTR locales prove the
+plumbing; an RTL one proves the layout, and it will find real bugs — mirrored
+icons, hardcoded `marginLeft`, a nav that opens on the wrong side.
+
+Adding a language means adding a locale file. If it means touching components,
+that is the finding.
+
+### Emails — `pikku-emails`
+
+Templates in `emails/`, rendered and sent through the injected `email` service,
+localised like every other string. The base workflow asks for one; **a showcase
+sends three** — a welcome, a transactional confirmation, and one sent from a
+schedule or queue rather than a request, because that is the interesting path.
+
+### Contract versioning — `pikku-versioning`
+
+```sh
+bunx --bun pikku versions init
+```
+
+The CLI suggests this on every run of a project without it. Versioning a function
+contract, then changing it, is a short milestone that shows something no
+scaffold demonstrates on its own. `pikku semver` derives the release version by
+comparing this build's surface against a deployed one.
+
+### Addons — `pikku-addon`
+
+`pikku new addon` scaffolds a publishable addon package. Worth one milestone if
+the domain has a piece that genuinely belongs to no single app.
+
+## Coverage — where the bar is higher than the base workflow
+
+`pikku-build-app` §7a already has the mechanics and the per-milestone habit:
+run the server instrumented, run the scenarios against it, read
+`coverage/scenario-coverage.json`, and triage every gap as a missing scenario, a
+function that should not exist, or a documented deferral. Do all of that here.
+
+Two things change in a showcase:
+
+- **Every surface you enabled has to appear in the coverage, not just every
+  function.** A workflow, a schedule, a queue worker and an agent each run on
+  their own path; a green scenario suite that never advances the workflow past
+  step one is the difference between "the platform does workflows" and "there is
+  a workflow file in this repo". Check the surfaces by name, because a coverage
+  percentage in the nineties hides an entire unexercised surface comfortably.
+- **The number is part of the deliverable.** A showcase is read as evidence, so
+  publish the figure alongside it. An unreported number invites the reader to
+  assume the worst, and in a demo repo they are usually right to.
+
+## The full gate
+
+Everything in `pikku-build-app` §9, plus the checks a showcase should be able to
+survive:
+
+```sh
+bunx --bun pikku all --tsc-summary --fail-on-warn --strict-meta
+bunx --bun pikku all --security --fail-on-error
+bunx --bun pikku validate
+bunx --bun pikku knowledge validate
+bunx --bun pikku audit
+bunx --bun pikku scenario run local --spawn --coverage
+bunx --bun pikku scenario run local --spawn --run browser
+```
+
+- `--strict-meta` fails an agent tool with no description.
+- `--security` runs the data-classification lint over function return types,
+  catching a `Pii`/`Secret` field leaking through an exposed function. Expensive;
+  worth it here.
+- `pikku audit` reports dependency advisories (`--outdated` adds available
+  updates) into `.pikku/audit.json`.
+
+## Deploy
+
+`pikku-build-app` §9 covers the open-source paths (`--provider standalone`,
+`cloudflare`, `aws`). One thing specific to this mode: **the extra surfaces are
+extra deploy units.** Workflow workers, queue workers, schedules and the events
+channel each appear in `pikku deploy plan` as their own entries. Read the plan
+before applying — that list is also the clearest inventory of what you actually
+built.
+
+## Reference
+
+- Base workflow: `pikku-build-app` — read it first, follow it in full
+- Per-surface skills: `pikku-workflow`, `pikku-schedule`, `pikku-cron`,
+  `pikku-queue`, `pikku-agent`, `pikku-ai-vercel`, `pikku-realtime`,
+  `pikku-websocket`, `pikku-mcp`, `pikku-trigger`, `pikku-i18n`, `pikku-rtl`,
+  `pikku-emails`, `pikku-versioning`, `pikku-addon`, `pikku-security`,
+  `pikku-audit`
+- Every feature, end to end: https://pikkufabric.com/llm-all-features.txt