@pikku/skills 0.12.52 → 0.12.54

package/skills/pikku-permissions/SKILL.md

@@ -1,14 +1,24 @@
 ---
 name: pikku-permissions
 description: >-
-  Use when deciding WHO may call a function — resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes, and where ownership belongs versus where it does not.
-  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, or about to write an `if` in a function body that decides whether the caller is allowed.
-  DO NOT TRIGGER when: the question is how to sign someone in or seed a persona (that is pikku-auth), or how to shape a paginated list (that is pikku-list-query).
+  Use when deciding WHO may call a function: resource ownership, role gates, admin-only actions, or any "only their own rows" rule. Covers the `permissions` field, `pikkuPermission`, `pikkuAuth`, scopes and `defineScope`, `addGlobalPermission`, the three gates, `permissionsInBody`, and where ownership belongs versus where it does not.
+  TRIGGER when: writing or reviewing any function that touches a row a user owns, gating an action on a role, building the permissions half of a contract in build PHASE 2, about to write an `if` in a function body that decides whether the caller is allowed, or hitting `MissingScopeError`.
+  DO NOT TRIGGER when: the question is how a caller proves who they are, such as sign-in, sessions, tokens, API keys or seeding a persona (use pikku-auth), or how to shape a paginated list (use pikku-list-query).
 installGroups: [core]
 ---
 
 # Pikku Permissions
 
+## First: is the caller a machine with a token?
+
+Then this is NOT a permissions problem. Resolve the token in `addHTTPMiddleware('*')`
+middleware that calls `setSession`, make the function a `pikkuFunc`, and gate it with
+`scopes` (pikku-auth, `../pikku-auth/references/machine-auth.md`). A `permissions` check that verifies a
+bearer token and returns `true` is authentication wearing an authorization hat, and it
+leaves the function sessionless. The only exception is a bootstrap endpoint whose caller
+has no identity yet (a shared-secret registration, a login): it is sessionless and
+declares its gate here.
+
 ## The rule
 
 **Authorization goes in the `permissions` field. Never in the `func` body.**
@@ -107,11 +117,32 @@ gets straight through if the function itself is open.
 ## Scopes
 
 `scopes: ['admin:invoices:void']` is an AND gate checked BEFORE permissions and before
-input validation. Declare the tree once with `defineScope`; a function naming an
-undeclared scope fails codegen rather than gating on nothing. A grant satisfies a scope if
-it is that scope, an ancestor, or a wildcard — a session holding `admin` satisfies
-`admin:invoices:void`. Most apps need roles, not scopes; reach for these only when the
-plan asked for granular grants.
+input validation. A function naming an undeclared scope fails codegen rather than gating on
+nothing. A grant satisfies a scope if it is that scope, an ancestor, or a wildcard. Most
+apps need roles, not scopes; reach for these only when the plan asked for granular grants.
+The `defineScope` tree, grant matching and the sessionless restriction are in
+[references/scopes.md](references/scopes.md).
+
+## Global permissions
+
+`addGlobalPermission([isEmployee])` (from `#pikku/auth`) is an app-wide baseline every
+function must additionally pass. It is an independent AND gate: it can only narrow access,
+never grant what a function's own `permissions` would deny. Multiple calls accumulate and
+are AND'd.
+
+## The three gates
+
+All must pass, in this order:
+
+1. **Scopes** (`scopes`) — AND'd, checked before input validation, fails closed.
+2. **Global permissions** (`addGlobalPermission`) — AND'd together, a baseline that only narrows.
+3. **The function's own `permissions`** — OR'd groups of AND'd entries.
+
+They are independent: a broad global (e.g. `isEmployee`) can never satisfy an admin-only
+function's own requirement. Wire-, tag- and HTTP-route-level permissions
+(`addHTTPPermission`, `addTagPermission`, a `permissions` field on a wiring) no longer
+exist; tags are organizational only. Use tag/HTTP middleware for cross-cutting request
+handling, not authorization.
 
 ## The one sanctioned exception
 
@@ -122,5 +153,5 @@ the auditor the openness is deliberate. Anything expressible as a permission mus
 
 ## After changes
 
-`pikku all` — regenerates and typechecks the checkers. A permission whose signature is
-wrong fails here, not at runtime.
+`pikku all --tsc` — regenerates, then verifies the checker types. A permission whose
+signature is wrong fails here, not at runtime.

package/skills/pikku-permissions/references/scopes.md

@@ -0,0 +1,59 @@
+# Scopes
+
+Scopes answer "what was this session granted?" before permissions ask "may this user do
+this to this resource?". They are AND-ed: every scope listed must be held. Because they
+are checked first and fail closed, a scope can only ever narrow access.
+
+## Declaring the tree
+
+Declare the scope tree once with `defineScope`. The body is a no-op that tree-shakes
+away; the CLI reads the call by AST and generates a `ScopeId` union, so a function naming
+an undeclared scope fails the build.
+
+```typescript
+// src/scopes.ts
+import { defineScope } from '#pikku/scopes'
+
+defineScope({
+  admin: {
+    displayName: 'Administration',
+    description: 'Administrative access',
+    scopes: {
+      invoices: {
+        description: 'Invoice management',
+        scopes: {
+          create: { description: 'Create invoices' },
+          void: { description: 'Void invoices' },
+        },
+      },
+    },
+  },
+  billing: {},
+})
+```
+
+Every node is grantable, keyed by segment: the above yields `admin`, `admin:invoices`,
+`admin:invoices:create`, `admin:invoices:void` and `billing`. Scopes may be declared
+across more than one file; the declarations merge.
+
+## Using them
+
+```typescript
+export const voidInvoice = pikkuFunc({
+  scopes: ['admin:invoices:void'],
+  permissions: { owner: isInvoiceOwner },
+  func: async ({ kysely }, { invoiceId }) => { ... },
+})
+```
+
+A grant satisfies a required scope if it is the scope itself, an ancestor of it, or a
+wildcard at any level: a session holding `admin` satisfies `admin:invoices:void`, and so
+does `admin:*`. A missing scope throws `MissingScopeError` naming the first one that
+failed.
+
+## Not on sessionless functions
+
+`scopes` requires a session and is unavailable on `pikkuSessionlessFunc`: scopes fail
+closed, an anonymous caller holds none, and a sessionless function with scopes would
+reject every caller it exists to serve. Gate those with `permissions`, which receive the
+optional session and may pass anonymous.

package/skills/pikku-react/SKILL.md

@@ -7,8 +7,8 @@ description: >-
   the dev actor switcher. TRIGGER when: writing a React component that fetches or mutates backend
   data, wiring PikkuProvider, paginating, running or tracking a workflow from the client, or
   asking about useDevActors / DevActorSwitcher / quick login. DO NOT TRIGGER when: working on the
-  backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), or writing
-  user-facing copy (use pikku-i18n).
+  backend (use pikku-wiring), defining the workflow itself (use pikku-workflow), rendering fetched values such as
+  dates (use pikku-tailwind), or writing user-facing copy (use pikku-i18n).
 installGroups: [client]
 ---
 

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

@@ -259,9 +259,7 @@ const { actors, signInAs, pendingId, isPending, error } = useDevActors({
 ```
 
 - **It is UI-free**, so render it however you like. For the default rendering use
-  `<DevActorSwitcher />` from `@pikku/mantine/dev` — a separate entry point from
-  `@pikku/mantine/core`, whose contract is "drop-in alias for `@mantine/core`"
-  and so must not export components Mantine has no counterpart for.
+  the starter template's `<DevActorSwitcher />` (`components/dev/DevActorSwitcher.tsx`).
 - **No credential reaches the bundle.** It lists from `/auth/sign-in/personas`
   and `signInAs(id)` posts only the persona id to `/auth/sign-in/persona`. The
   server decides who is offered and who may sign in, and offers nobody in
@@ -276,37 +274,6 @@ const { actors, signInAs, pendingId, isPending, error } = useDevActors({
 Do not hand-write the list-and-sign-in pair per app; that copy-paste is exactly
 what this replaced.
 
-### Linking from a Mantine element: `renderRoot`, not `component`
-
-Handing TanStack's `Link` to a Mantine element as `component={Link}` compiles,
-renders, and navigates — and silently unties the type. Mantine's polymorphic
-`component` prop widens the router generic to `AnyRouter`, so `to` and
-`params` stop being checked against your actual routes. Renaming a route then
-breaks the running app instead of the build, which is the one thing the typed
-router exists to prevent.
-
-Wrap the typed `Link` once and reach it through `renderRoot`, which passes the
-props through without re-typing the element:
-
-```tsx
-// components/links.tsx — one wrapper the whole app links through
-import { Link } from '@tanstack/react-router'
-
-export const AssessmentLink = (props: { assessmentId: string; children: React.ReactNode }) => (
-  <Link to="/assessments/$assessmentId" params={{ assessmentId: props.assessmentId }}>
-    {props.children}
-  </Link>
-)
-```
-
-```tsx
-<Button renderRoot={(p) => <AssessmentLink assessmentId={id} {...p} />}>
-  Open
-</Button>
-```
-
-The wrapper is where `to` and `params` are checked, and it is checked once.
-
 ## What NOT to do
 
 - Don't instantiate `PikkuFetch`/`PikkuRPC` inside a component — `createPikku`

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

@@ -1,5 +1,16 @@
 # Pikku React Query Hooks
 
+## Contents
+
+- [Discover what's available on the client](#discover-whats-available-on-the-client)
+- [Setup (once per app)](#setup-once-per-app)
+- [TanStack Start (SSR)](#tanstack-start-ssr)
+- [The hooks](#the-hooks)
+- [Workflow hooks](#workflow-hooks)
+- [Calling RPCs without React Query](#calling-rpcs-without-react-query)
+- [Common patterns](#common-patterns)
+- [What NOT to do](#what-not-to-do)
+
 
 ## Discover what's available on the client
 

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

@@ -1,5 +1,16 @@
 # Pikku Workflows — Client Hooks
 
+## Contents
+
+- [Discover what workflows exist](#discover-what-workflows-exist)
+- [Setup](#setup)
+- [useRunWorkflow(name, options?) — run and wait](#userunworkflowname-options--run-and-wait)
+- [useStartWorkflow(name, options?) — fire-and-poll](#usestartworkflowname-options--fire-and-poll)
+- [useWorkflowStatus(workflowName, runId, options?) — observe](#useworkflowstatusworkflowname-runid-options--observe)
+- [Putting it together — start + observe](#putting-it-together--start--observe)
+- [Backend: streaming richer progress](#backend-streaming-richer-progress)
+- [What NOT to do](#what-not-to-do)
+
 
 ## Discover what workflows exist
 

package/skills/pikku-realtime/SKILL.md

@@ -1,9 +1,15 @@
 ---
 name: pikku-realtime
 description: >-
-  Use when making ANY view live/realtime in a Pikku app — a board, shared list, dashboard, ticker, bidding room, live count — or when adding two-way chat/presence. Covers the DEFAULT event-hub SSE path and the two-way WebSocket channel.
-  TRIGGER when: the user wants live updates, realtime, "update without refresh", a live board/feed/ticker/room, presence, or chat; or when data that MORE THAN ONE signed-in user can change should reflect others
-  DO NOT TRIGGER when: a plain one-shot query/refetch is fine (data only one user changes, or a manual refresh is acceptable), or for background jobs (see `pikku-wiring`'s scheduler and queue references, or `pikku-workflow`).
+  Use when making a view live in a Pikku app — a board, shared list, dashboard, ticker, bidding
+  room, live count — or when adding two-way chat or presence. Covers the default event-hub SSE path
+  (`eventHub.publish` on the backend, `PikkuRealtime.subscribeToTopic` on the client) and the
+  two-way WebSocket channel. TRIGGER when: the user wants live updates, realtime, "update without
+  refresh", a live board/feed/ticker/room, presence or chat, or data that more than one signed-in
+  user can change should reflect to others. DO NOT TRIGGER when: a one-shot query/refetch is enough
+  (data only one user changes, or a manual refresh is acceptable), for background jobs (use
+  pikku-workflow, or pikku-wiring's queue and scheduler references), or for the full wiring
+  reference of channels, SSE routes and the `/events` scaffold (use pikku-wiring).
 installGroups: [core, client]
 ---
 

package/skills/pikku-report/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: pikku-report
 description: >-
-  Use when pikku itself cost you time — wrong generated types, a check that passes when it
-  should not, output that is quietly wrong, a skill that misled you — or when the user asks you
-  to report a framework bug or file a finding. Owns `pikku fabric report` (a finding is about
-  pikku, not the app), the product-vs-harness kinds, the workaround-first ladder, and asking the
-  user at hand-over whether to send what was filed. TRIGGER when: the framework fought you,
-  codegen produced something broken, a skill told you to run something that does not exist, the
-  user says "report this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug is in the app you are building (fix it
-  there), or you are tempted to patch pikku's source (never do that from an app).
+  Use when pikku itself cost you time — wrong generated types, a check that passes when it should
+  not, output that is quietly wrong, a skill that misled you — or when the user asks you to report
+  a framework bug or file a finding. Owns `pikku fabric report` (a finding is about pikku, not the
+  app), the product-vs-harness kinds, the workaround-first ladder, and asking the user at hand-over
+  whether to send what was filed. TRIGGER when: the framework fought you, codegen produced
+  something broken, a skill told you to run something that does not exist, the user says "report
+  this to pikku" / "file a finding", or you are handing over a build. DO NOT TRIGGER when: the bug
+  is in the app you are building (fix it there), you are debugging a deployed stage (use
+  pikku-fabric), or you are tempted to patch pikku's source (never do that from an app).
 installGroups: [core]
 ---
 
@@ -61,7 +62,7 @@ baseline noise that was already failing before you started.
 - `--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
+  section>"`. This is the most useful kind to file, because it is fixable
   immediately — so file it even when the cost was small.
 
 ## The command

package/skills/pikku-scenario/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   expectEventually / expectError / expectService / expectScore, declared steps via
   pikkuScenarioStep (browser steps driven by @pikku/playwright) written as intent rather than
   clicks, personas / actors / environments in pikku.config.json, SCENARIO_ACTOR_SECRET, the
-  `pikku scenario list|run` and `pikku persona run|list|sync|secret` commands, and live coverage
+  `pikku scenario` and `pikku persona` commands, and live coverage
   via `pikku dev --coverage`. TRIGGER when: user asks about scenarios, testing a Pikku function,
   coverage, e2e flows, browser/UI e2e, health checks, personas, virtual users, or adversarial
   runs against a stage. DO NOT TRIGGER when: user asks about running an existing suite (use
@@ -20,19 +20,15 @@ installGroups: [core]
 
 ## Agent Operating Procedure
 
-Use this skill as an execution checklist, not reference material.
-
 1. Discover before editing: `pikku scenario list` for what exists, `pikku info functions --verbose` for what a scenario can call.
-2. Identify the source files that own the behavior. Do not start by reading generated output, `.pikku`, `node_modules`, or build artifacts.
-3. Make the smallest source change that satisfies the task. Keep generated files generated.
-4. Validate with the narrowest relevant command first, then `pikku all --tsc` when functions, wirings or schemas may have changed.
-5. If validation fails, fix the source cause and rerun. Do not paper over generated errors by editing generated files.
+2. Edit source files only; never generated output or `.pikku`.
+3. Validate with the narrowest relevant command first, then `pikku all --tsc` when functions, wirings or schemas may have changed. If it fails, fix the source cause and rerun.
 
 **`pikku tests` does not exist.** It was removed in #865 — scenarios own coverage now. Any reference you find to it is stale.
 
 ## Pick the reference
 
-This skill covers writing and running scenarios end to end. Four topics are one level down, and
+This skill covers writing and running scenarios end to end. Five topics are one level down, and
 each says when to open it:
 
 | Read                        | For                                                                                                          |
@@ -186,12 +182,6 @@ Hooks are scenario-only. A `before`/`after` on a `pikkuWorkflowFunc` never runs
 
 ### Grouping scenarios (`pikkuFeature`)
 
-A feature is also cited by a page of the user guide: `pikku scenario guide`
-fills each cited block with the feature's recordings and screenshots, and
-nothing else (see **pikku-guide**). A scenario's `title` captions its recording
-and a screenshot's `name` captions the still, so write both as copy a user would
-read. Mark plumbing features `document: false`.
-
 `pikkuFeature` groups scenarios the way gherkin's `Feature:` groups `Scenario:`. Scenarios are referenced by **imported identifier**, so a renamed or deleted scenario is a compile error rather than a silent skip:
 
 ```typescript
@@ -229,6 +219,12 @@ export const credentialFeature = pikkuFeature({
 
 The **feature is the run unit**: `--flows` on a scenario whose every feature entry carries `data` errors and names the features containing it, because the feature is what supplies that data. Use `--features` for those. A scenario referenced bare anywhere, or in no feature at all, still runs standalone.
 
+A feature is also cited by a page of the user guide: `pikku scenario guide`
+fills each cited block with the feature's recordings and screenshots, and
+nothing else (see **pikku-guide**). A scenario's `title` captions its recording
+and a screenshot's `name` captions the still, so write both as copy a user would
+read. Mark plumbing features `document: false`.
+
 ## Steps
 
 `scenario.do` can only name an RPC. A **step** — `pikkuScenarioStep` — is a named, typed unit of
@@ -289,7 +285,7 @@ scenario actor per person, and seeds a user row each:
 - `scenarios.emailDomain` is the mail domain actor addresses are built on.
 - `scenarios.browserDriver` is the package driving `browser` bindings.
 - `scenarios.model` is the model a persona thinks with (`actor.converse`, `pikku virtual-user run`).
-- `environments.<name>` are the targets a run can point at. The key is the required positional of `pikku scenario run`; `apiUrl` is required and `signInPath`/`rpcPath`/`sessionPath` have defaults.
+- `environments.<name>` are the targets a run can point at. The key is the required positional of `pikku scenario run`; `apiUrl` is required; `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`, and `sessionPath` has a default too.
 
 **`references/personas.md`** covers the parts that bite: one entry is one
 person and one actor, emails are derived and never written, `runnable: false`
@@ -297,7 +293,6 @@ for someone only acted upon, `definePersonas` being read from source rather
 than evaluated, and the same actor list powering a human "Sign in as …"
 switcher.
 
-- `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/actor`, `rpcPath` to `/rpc`.
 - **`SCENARIO_ACTOR_SECRET` is an environment variable and never goes in `pikku.config.json`.** It signs actors in. `pikku scenario run` throws without it; a server auto-building actors warns and runs without them.
 
 ## Running
@@ -351,7 +346,6 @@ and where a plain unit test is still the right tool.
 
 | Smell                                               | Why it's wrong                                                                                                                                   |
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `pikku tests …`                                     | Removed in #865. Use `pikku scenario`.                                                                                                           |
 | `.feature` files / Gherkin for function tests       | Scenarios are TypeScript, not Gherkin. The in-process cucumber function world was deleted.                                                       |
 | `scenario.do(...)` with no `{ actor }`              | Throws. Every step runs as somebody.                                                                                                             |
 | A scenario per function                             | Scenarios are user flows. One flow covers many functions; that is the point.                                                                     |

package/skills/pikku-scenario/references/persona-run.md

@@ -1,5 +1,15 @@
 # Running a persona as a virtual user
 
+## Contents
+
+- [The shape of a run](#the-shape-of-a-run)
+- [The dispositions](#the-dispositions)
+- [Credentials, and which one wins](#credentials-and-which-one-wins)
+- [Production is opt-in, twice](#production-is-opt-in-twice)
+- [The role check happens before the first step](#the-role-check-happens-before-the-first-step)
+- [The other subcommands](#the-other-subcommands)
+- [What NOT to do](#what-not-to-do)
+
 `pikku persona run <environment> <persona>` signs a declared persona in over the
 app's real auth and works the API in character, driven by a model. A persona
 while running **is** the virtual user — there is no second declaration for it.
@@ -125,7 +135,7 @@ drift.
 
 `sync` **reports**; it does not provision. The CLI has no connection to a
 deployed environment's database, so the provisioning happens in the deployment —
-pass the generated personas to `pikkuFabric` from `@pikku/better-auth`.
+pass the generated personas to `provisionPersonas` from `@pikku/better-auth`.
 
 ## What NOT to do
 

package/skills/pikku-scenario/references/personas.md

@@ -1,5 +1,11 @@
 # Personas and actors
 
+## Contents
+
+- [Declaring personas in TypeScript](#declaring-personas-in-typescript)
+- [Actors that call a third-party API](#actors-that-call-a-third-party-api)
+- [The same actors sign a human in](#the-same-actors-sign-a-human-in)
+
 A **persona** is a person your product is for; an **actor** is one body that signs in as them. Every entry materialises exactly one actor, so `actors.<id>` exists for each declared persona and there is no second way to declare a login.
 
 - Two people of the same kind are two entries, not one persona with two logins — "you see yours, not theirs" is only testable with two customers.
@@ -96,7 +102,7 @@ sign-in opted in **and** its `devSwitcher` feature flag on; production never
 has the opt-in, so it lists nobody and refuses every persona sign-in.
 
 Do not hand-roll the switcher: `useDevActors()` (`pikku-react`, a separate install) is the logic and
-`<DevActorSwitcher />` from `@pikku/mantine/dev` is a ready rendering of it.
+the starter template's `<DevActorSwitcher />` is a ready rendering of it.
 `pikku fabric validate` **requires** any frontend with a login screen to ship
 one — without it a reviewer is locked out of their own sandbox.
 When the switcher is missing, it is one of three things, and none of them

package/skills/pikku-seo/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: pikku-seo
 description: >-
-  On-page SEO rules for the app's PUBLIC pages: per-route head() titles and meta descriptions, Open Graph tags, one-h1 heading hierarchy, semantic/crawlable markup, JSON-LD on the landing page, and noindex for the logged-in area.
+  On-page SEO rules for the app's PUBLIC pages: per-route head() titles and meta descriptions, Open Graph tags, crawlable links and URLs, JSON-LD on the landing page, and noindex for the logged-in area.
   TRIGGER when: building or reworking any public page (landing, pricing, about, blog/content pages), writing page titles or meta tags, or the user asks about SEO / Google / discoverability / social sharing previews.
-  DO NOT TRIGGER when: working on logged-in /app screens (they are noindexed — only the one robots rule below applies), backend functions, database, or deployment.
+  DO NOT TRIGGER when: the task is accessibility, including heading order, landmarks or alt text (use pikku-a11y), or working on logged-in /app screens (they are noindexed — only the one robots rule below applies), backend functions, database, or deployment.
 installGroups: [client]
 ---
 
@@ -38,19 +38,20 @@ export const Route = createFileRoute('/pricing')({
 })
 ```
 
-`head()` strings are plain strings (they do not go through the Mantine i18n
+`head()` strings are plain strings (they do not go through the component i18n
 gate) — write real copy for THIS app, in the app's voice.
 
 - **Title**: unique per page, 50–60 characters, the page's primary topic first,
-  brand at the end (`Topic — AppName`). The template's `__APP_TITLE__` default
-  must never survive the rebrand, on any page.
+  brand at the end (`Topic — AppName`). The template's `__APP_TITLE__` placeholder
+  (in `src/app-meta.ts` and `messages/en.json`) is filled with the app title at scaffold time
+  by `fabric-new-app`; it must never survive in any page's title.
 - **Description**: unique per page, 150–160 characters, states the concrete
   value of the page in plain language — a reason to click, not a keyword list.
 - **Dynamic public pages** (e.g. a public detail page) build both from loader
   data: `head: ({ loaderData }) => ({ meta: [{ title: `${loaderData.name} — AppName` }, ...] })`.
 - **Never invent URLs**: the deployed domain is unknown at build time, so do
   NOT emit `canonical`, `og:url`, or `og:image` pointing at a made-up domain —
-  omit them (same principle as the `/api` serverUrl rule). `og:image` only if a
+  omit them. `og:image` only if a
   real asset exists in the app.
 
 ## Logged-in area = noindex
@@ -64,24 +65,19 @@ head: () => ({ meta: [{ name: 'robots', content: 'noindex' }] })
 Never noindex a public page, and never put per-page SEO effort into `/app`
 screens — they are invisible to crawlers by design.
 
-## Headings — exactly one h1 per page
+## Headings, landmarks, alt text
 
-- Every page has EXACTLY ONE h1 (`<Title order={1}>` in Mantine, `<h1>` in
-  Tailwind) and it names the page's primary topic — aligned with the title tag,
-  not identical boilerplate.
-- Logical hierarchy below it: h1 → h2 → h3, no skipped levels, headings
-  describe the content under them. Never pick a heading level for its font
-  size — set the size on the correct level (`<Title order={2} fz="xs">`).
+Owned by `pikku-a11y` and apply app-wide; follow it. SEO addition only: the
+public page's h1 names its primary topic, aligned with the title tag (not
+identical boilerplate).
 
 ## Crawlable, semantic markup
 
-- Landmarks on public pages: `<nav>`, `<main>`, `<footer>` (Mantine: `component="nav"` etc.).
 - Navigation between public pages uses real links (`<Link>`/`<a href>`) with
   descriptive anchor text — crawlers follow hrefs; a `div onClick` navigation
   is invisible to them. No public page may be orphaned: every public page is
   reachable by link from the landing page (directly or via nav/footer).
-- Every meaningful `<img>` has alt text describing the image; decorative images
-  get `alt=""`. Prefer descriptive file names for real assets.
+- Prefer descriptive file names for real assets (alt text: see `pikku-a11y`).
 - Readable URLs: public routes are lowercase, hyphen-separated, and named for
   their content (`/pricing`, `/how-it-works`) — never `/page2` or query-param
   navigation.

package/skills/pikku-service-backends/SKILL.md

@@ -16,16 +16,6 @@ installGroups: [core]
 
 # Pikku Service Backends
 
-## Agent Operating Procedure
-
-Use this skill as an execution checklist, not reference material.
-
-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 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.
-
 Constructor shapes and method signatures come from `pikku doc` — run
 `pikku doc --ai` for the installed surface. This skill is the part the compiler
 cannot tell you: which backend implements which interface, and what changes when

package/skills/pikku-service-backends/references/aws.md

@@ -1,5 +1,11 @@
 # AWS (`@pikku/aws-services`)
 
+## Contents
+
+- [`S3Content` — ContentService](#s3content-contentservice)
+- [`SQSQueueService` — QueueService](#sqsqueueservice-queueservice)
+- [`AWSSecrets` — SecretService](#awssecrets-secretservice)
+
 ```bash
 yarn add @pikku/aws-services
 ```

package/skills/pikku-service-backends/references/mongodb.md

@@ -1,5 +1,12 @@
 # MongoDB (`@pikku/mongodb`)
 
+## Contents
+
+- [`PikkuMongoDB` — connection wrapper](#pikkumongodb-connection-wrapper)
+- [Available services](#available-services)
+- [`MongoDBSecretService`](#mongodbsecretservice)
+- [Full setup](#full-setup)
+
 ```bash
 yarn add @pikku/mongodb
 ```

package/skills/pikku-service-backends/references/redis.md

@@ -1,5 +1,11 @@
 # Redis (`@pikku/redis`)
 
+## Contents
+
+- [`RedisSecretService`](#redissecretservice)
+- [`RedisLeaseService`](#redisleaseservice)
+- [Full setup](#full-setup)
+
 ```bash
 yarn add @pikku/redis
 ```

package/skills/pikku-services/references/audit.md

@@ -1,5 +1,15 @@
 # Pikku Audit
 
+## Contents
+
+- [Mental model — two layers](#mental-model-two-layers)
+- [Wiring (services.ts)](#wiring-servicests)
+- [Recording events — explicit domain events (default)](#recording-events-explicit-domain-events-default)
+- [Recording events — automatic query capture (optional)](#recording-events-automatic-query-capture-optional)
+- [Sinks](#sinks)
+- [AuditEvent shape](#auditevent-shape)
+- [Do / Don't](#do-dont)
+
 
 ## Mental model — two layers
 

package/skills/pikku-services/references/config.md

@@ -1,5 +1,11 @@
 # Pikku Config, Secrets & OAuth2
 
+## Contents
+
+- [Before You Start](#before-you-start)
+- [Secrets & Variables](#secrets-variables)
+- [Credentials](#credentials)
+
 
 ## Before You Start
 

package/skills/pikku-services/references/services.md

@@ -1,5 +1,12 @@
 # Pikku Services (Dependency Injection)
 
+## Contents
+
+- [Before You Start](#before-you-start)
+- [API Reference](#api-reference)
+- [Usage Patterns](#usage-patterns)
+- [Complete Example](#complete-example)
+
 ## Before You Start
 
 ```bash
@@ -75,7 +82,7 @@ export const lifecycle = pikkuServerLifecycle<SingletonServices>({
 })
 ```
 
-Every hook is optional. Order is `beforeStart` → server starts → `afterStart`, then on SIGINT `beforeStop` → services stopped → server stopped → `afterStop`.
+Every hook is optional. Order is `beforeStart` → server starts → `afterStart`, then on SIGINT or SIGTERM `beforeStop` → services stopped → server stopped → `afterStop`. A repeat signal while this runs is ignored, so the sequence always finishes.
 
 **`afterStop` runs after the singleton services have been stopped.** It still receives the services object, but the services inside it are shut down — using one there is a use-after-close bug. Anything that needs a live service goes in `beforeStop`.