@pikku/skills 0.12.52 → 0.12.55

package/skills/pikku-scenario/references/{persona-run.md → virtual-user-run.md}

@@ -1,7 +1,17 @@
-# Running a persona as a virtual user
+# Running a virtual user against a stage
 
-`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
+## Contents
+
+- [The shape of a run](#the-shape-of-a-run)
+- [The dispositions](#the-dispositions)
+- [The key](#the-key)
+- [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 virtual-user run <environment> <virtualUserId>` signs a declared virtual user in over the
+app's real auth and works the API in character, driven by a model. A virtual user
 while running **is** the virtual user — there is no second declaration for it.
 
 **It is not a test runner.** It asserts nothing, and a green run proves nothing:
@@ -10,33 +20,33 @@ not with this seed". Findings set exit code 1, so a run can gate a pipeline;
 giving up on a goal does not, because that is a user being a user.
 
 Everything it needs is already in the project — the catalogue is the function
-meta, the intents are the scenarios' own prose, the identity is the persona
+meta, the intents are the scenarios' own prose, the identity is the virtual user
 signing in, the scopes come from their declared roles. The only new input is
 which person to be.
 
-Declaring personas — persona versus actor, `definePersonas`, materialised
-actors — is in the skill itself, under **Personas and actors**. This is the
+Declaring virtual users — virtual user versus virtual user, `defineVirtualUsers`, materialised
+virtual users — is in the skill itself, under **Virtual users and virtual users**. This is the
 running half.
 
 ## The shape of a run
 
 ```bash
-SCENARIO_ACTOR_SECRET=… pikku persona run local shopper
-SCENARIO_ACTOR_SECRET=… pikku persona run local shopper -d careless --seed 42
-SCENARIO_ACTOR_SECRET=… pikku persona run staging auditor \
+pikku virtual-user run local shopper
+pikku virtual-user run local shopper -d careless --seed 42
+pikku virtual-user run staging auditor \
   --goals "reconcile the order totals" --steps 80 --out runs/auditor.json
 ```
 
 Both arguments are required positionals: the environment key from
-`environments`, then the persona id. A run needs a model — `--model`, or
+`environments`, then the virtual user id. A run needs a model — `--model`, or
 `scenarios.model` in `pikku.config.json` — and an AI provider in the
 environment (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or `LITELLM_PROXY_URL` +
 `LITELLM_API_KEY`).
 
 | Flag                   | Effect                                                                                                                                                |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--disposition` / `-d` | How they behave. Overrides the persona's own                                                                                                          |
-| `--goals`              | Comma-separated, in your words — run _alongside_ the persona's own and the ones derived from scenarios                                                |
+| `--disposition` / `-d` | How they behave. Overrides the virtual user's own                                                                                                     |
+| `--goals`              | Comma-separated, in your words — run _alongside_ the virtual user's own and the ones derived from scenarios                                           |
 | `--steps`              | Model turns before it stops (default 40)                                                                                                              |
 | `--mutations`          | Non-read calls before it stops                                                                                                                        |
 | `--duration`           | Wall clock before it stops, e.g. `30m`                                                                                                                |
@@ -50,9 +60,9 @@ environment (`OPENAI_BASE_URL` + `OPENAI_API_KEY`, or `LITELLM_PROXY_URL` +
 ## The dispositions
 
 A disposition is a bundle of instructions and mechanical dials (move weights,
-temperature, repeat and re-read rates). `tuning` on the persona adjusts those
+temperature, repeat and re-read rates). `tuning` on the virtual user adjusts those
 dials without replacing the character — a tuned `careless` user is still
-careless. Passing `--disposition` drops the persona's `tuning`, because you
+careless. Passing `--disposition` drops the virtual user's `tuning`, because you
 asked to run them differently rather than to bend their dials into another
 shape.
 
@@ -66,33 +76,29 @@ shape.
 | `adversarial` | Probing whether the boundaries are enforced. Inverted oracle — a 2xx from something it should not reach is the finding        |
 | `accountable` | Doing the job for real. The **only** disposition production accepts                                                           |
 
-## Credentials, and which one wins
+## The key
+
+A run signs one short-lived statement per virtual user and presents it to the
+app. The key comes from, in this order:
 
-Three variables, checked in this order. None of them belongs in
-`pikku.config.json`.
+1. **`VIRTUAL_USER_SIGNING_KEY`** in the environment — a deployed stage's
+   private key, held by whoever deploys it.
+2. **The file `pikku dev` wrote**, `.pikku-runtime/virtual-user/signing.key` —
+   so a local run needs nothing set.
 
-1. **`FABRIC_OPERATOR_TOKEN`** — what a deployed stage accepts. Asymmetric, and
-   it needs no account the target would not otherwise have, so it wins over the
-   other two when both are present.
-2. **`PIKKU_PERSONA_SECRETS`** — `id=secret,id=secret`, already-derived
-   per-persona credentials. Hand a run only the personas it should be able to
-   be; asking for one outside the list is refused by name rather than falling
-   through to the root. Mint them with `pikku persona secret [personas...]` —
-   naming none mints all.
-3. **`SCENARIO_ACTOR_SECRET`** — the root secret, which derives every persona's
-   credential and is therefore entitled to all of them. Only `pikku dev` serves
-   the endpoint it opens.
+Neither belongs in `pikku.config.json`. The app only ever holds the public half,
+`VIRTUAL_USER_VERIFY_KEY`.
 
 ## Production is opt-in, twice
 
-A persona's `environments` omitted means every configured environment **except**
+A virtual user's `environments` omitted means every configured environment **except**
 those flagged `production: true` — nothing reaches production by being
 forgotten. Naming one requires `disposition: 'accountable'`.
 
 That rule is checked twice on purpose: the inspector checks the declaration at
-build time, and sign-in re-checks the **effective** disposition — the persona's
+build time, and sign-in re-checks the **effective** disposition — the virtual user's
 own, or whatever `--disposition` replaced it with — before the run starts. So
-`--disposition adversarial` cannot point an accountable persona at production.
+`--disposition adversarial` cannot point an accountable virtual user at production.
 The build check trusts the file; the run check does not trust which artifact got
 deployed.
 
@@ -100,7 +106,7 @@ deployed.
 true` is a label a person wrote in `pikku.config.json`; nothing can tell from a
 url whether real customers are behind it. `--api-url` replaces the url and keeps
 the classification, so a non-production environment repointed at a production
-host is still treated as non-production, and an adversarial persona will happily
+host is still treated as non-production, and an adversarial virtual user will happily
 run against it. The flag is for a target that only exists at run time — a
 freshly provisioned sandbox. Point it anywhere else and the guard above is not
 protecting you.
@@ -108,8 +114,8 @@ protecting you.
 ## The role check happens before the first step
 
 A run reads its own roles back from the stage and compares them to what the
-persona declared. It refuses on a mismatch, before anything runs — findings
-from a persona whose roles drifted are about the seed, and reading them as
+virtual user declared. It refuses on a mismatch, before anything runs — findings
+from a virtual user whose roles drifted are about the seed, and reading them as
 product bugs is how a whole run gets thrown away. A stage that reports no roles
 warns and runs unverified. `--skip-role-check` is for a target whose auth
 reports roles somewhere pikku cannot read; findings from such a run may be seed
@@ -117,21 +123,20 @@ drift.
 
 ## The other subcommands
 
-| Command                              | What it answers                                                                            |
-| ------------------------------------ | ------------------------------------------------------------------------------------------ |
-| `pikku persona list`                 | Who is declared — who each one is, what they may do, what they want                        |
-| `pikku persona sync <environment>`   | Which personas that environment will provision, with which roles, and why any were skipped |
-| `pikku persona secret [personas...]` | Mint per-persona credentials from the root secret                                          |
+| Command                                 | What it answers                                                                                 |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `pikku virtual-user list`               | Who is declared — who each one is, what they may do, what they want                             |
+| `pikku virtual-user sync <environment>` | Which virtual users that environment will provision, with which roles, and why any were skipped |
 
 `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 virtual users to `provisionVirtualUsers` from `@pikku/better-auth`.
 
 ## What NOT to do
 
 - **Do not treat a clean run as a pass.** Nothing was asserted. Use scenarios
   for the things that must hold.
-- **Do not run a persona declared `runnable: false`**, or one whose `account`
+- **Do not run a virtual user declared `runnable: false`**, or one whose `account`
   names a provider. The first is someone who exists to be acted upon — running
   her races the scenario that bans her — and the second needs a human at a
   consent screen. Both are refused before sign-in rather than partway through.
@@ -144,5 +149,5 @@ pass the generated personas to `pikkuFabric` from `@pikku/better-auth`.
   ones the app marked as needing a human because they spend money.
 - **Do not read a finding from a run started with `--skip-role-check` as a
   product bug** until the roles are confirmed some other way.
-- **Do not expect `--goals` to replace the persona's goals.** They are appended;
+- **Do not expect `--goals` to replace the virtual user's goals.** They are appended;
   a run that replaces Susan's goals is not Susan.

package/skills/pikku-scenario/references/virtual-users.md

@@ -0,0 +1,114 @@
+# Virtual users and virtual users
+
+## Contents
+
+- [Declaring virtual users in TypeScript](#declaring-virtual-users-in-typescript)
+- [Virtual users that call a third-party API](#virtual-users-that-call-a-third-party-api)
+- [The same virtual users sign a human in](#the-same-virtual-users-sign-a-human-in)
+
+A **virtual user** is a person your product is for; an **virtual user** is one body that signs in as them. Every entry materialises exactly one virtual user, so `virtualUsers.<id>` exists for each declared virtual user and there is no second way to declare a login.
+
+- Two people of the same kind are two entries, not one virtual user with two logins — "you see yours, not theirs" is only testable with two customers.
+- Never write an email address: each is derived from the virtual user id and `scenarios.emailDomain`, and a hand-written one signs in as somebody who was never created.
+- `roles` is typechecked against `defineSystemRole`; an undeclared role is a build error.
+- A person who is only ever acted _upon_ — the account an admin bans — sets `runnable: false`: declared and seeded, never signed in, because a run as them would race the scenario that acts on them.
+- A virtual user holds only what is true of that kind of person for the app's whole lifetime (`name`, `jobTitle`, `description`, `personality`, `roles`, `goals`, `disposition`). What someone is trying to get done, and the circumstances they are doing it in, belong to the **scenario**, not to them.
+
+## Declaring virtual users in TypeScript
+
+There may be **one `defineVirtualUsers` call in the whole codebase** — one place to
+read the set from, one place to add to it. A second anywhere, including in the
+same file, is a critical. Generated files are exempt and never claim the slot.
+
+> [!WARNING]
+> The declaration is **read from source, never evaluated** — the CLI writes it
+> to JSON that a deployed stage carries without the app. So every value has to
+> be statically knowable, and a value that is not comes out as `undefined`
+> rather than as an error. Only `name` is checked, so a computed `personality`,
+> `jobTitle` or `description` is dropped in silence and the virtual user runs with a
+> blank temperament.
+
+What that admits and what it does not:
+
+```typescript
+personality: 'Wound up and short with it.' // read
+personality: `Wound up and short with it.
+  Says what she wants in a few blunt words.` // read — no ${} in it
+personality: 'Wound up. ' + 'Short with it.' // dropped, silently
+personality: TEMPERAMENTS.impatient // dropped, silently
+```
+
+A no-substitution template literal is a string literal as far as the reader is
+concerned, so it is the way to write a long personality across several lines —
+not a concatenation, and not a `prettier-ignore`d single line. Its newlines and
+leading indentation are kept verbatim and reach the model that way, which is
+harmless but worth knowing before you align it to the surrounding code.
+
+One more thing worth knowing before writing a rich virtual user: **`virtualUser.converse`
+builds its prompt from `name`, `jobTitle`, `personality` and the scenario's
+`task` only.** Fields like `disposition`, `goals` and `roles` are read and
+stored, and the console shows them, but they do not reach the conversing
+virtual user's instructions. Anything that must shape how someone talks belongs in
+`personality` or in the task.
+
+A project that never declares a virtual user keeps working: a scenario that names no virtual user needs none.
+
+- `environments.<name>.apiUrl` is required. `signInPath` defaults to `/auth/sign-in/virtual-user`, `rpcPath` to `/rpc`.
+- **The signing key never goes in `pikku.config.json`.** `pikku dev` creates one under `.pikku-runtime/virtual-user/`; a deployed stage's deployer holds `VIRTUAL_USER_SIGNING_KEY`. `pikku scenario run` throws without a key.
+
+## Virtual users that call a third-party API
+
+An addon generated from an upstream API (Dolibarr, a CRM, a calendar) calls it
+with the signed-in user's own credential. A virtual user has none until one is stored
+for it, so every step that reaches the addon fails with `No <X> session`. Give
+the `virtualUser` plugin a `credentials` option, and each virtual user carries its upstream
+credential into every session:
+
+- `names: ['dolibarr']` — the credentials to carry
+- `store: (name, value, userId) => credentialService.set(name, value, userId)`
+- `remove: (name, userId) => credentialService.delete(name, userId)`
+
+At each virtual user sign-in the plugin reads `VIRTUAL_USER_CREDENTIAL_<VIRTUAL_USER>_<NAME>` —
+`dan` + `dolibarr` is `VIRTUAL_USER_CREDENTIAL_DAN_DOLIBARR` — and stores it with
+`credentialService.set` for that virtual user. A bare value is stored as `{ token }`
+(what a delegated or bearer credential holds); a JSON object is stored as-is,
+e.g. `{"apiKey":"…"}` for an API-key credential. Unset means the virtual user has no
+upstream credential: `remove` drops one stored at an earlier sign-in.
+
+- **Values live in `.env` (or CI secrets), never in `virtual-users.ts` or code.**
+  Use a dedicated upstream test account per virtual user, not a real person's.
+- `read` defaults to `process.env`; a Worker passes `(key) => variables.get(key)`.
+- A malformed JSON value refuses the sign-in with a 500 that names the variable.
+- A delegated token expires upstream like any other; re-signing the virtual user
+  in re-stores whatever the variable holds now.
+
+## The same virtual users sign a human in
+
+Declared virtual users are not only for automated runs. `signInPath` is Better Auth's
+`virtualUser` plugin (see `pikku-auth`, a separate install), which any caller can post to — so the
+frontend can sign in as the **same** list, and an
+app can be reviewed as each kind of user without anyone knowing a seed password.
+
+It holds no credential. A client app that wants one-click sign-in posts only a
+virtual user id to `/auth/sign-in/switch-virtual-user` itself; the server
+resolves the address. One server piece serves both, in the auth config:
+
+```ts snippet:virtualUserSignIn
+
+```
+
+It is always open under `pikku dev`. A deployed stage needs virtual user
+sign-in opted in and an explicit `virtualUserSignIn.allowed`; production never
+has the opt-in, so it lists nobody and refuses every virtual user sign-in.
+
+If the list is empty, it is one of two things, and neither errors:
+
+- **The gate is closed.** On a deployed stage that is the gate doing its job —
+  check the opt-in. Locally, check the virtual users declare an `email` (via
+  `scenarios.emailDomain`) and are not `runnable: false`.
+- **`virtualUserSignIn` is missing, or the frontend calls another API.** A dev
+  proxy (`VITE_API_PROXY`, default `http://localhost:3000`) that points at
+  another project's API lists that project's virtual users, or none.
+
+When the list has virtual users but a sign-in 404s, that virtual user has no `email`
+or is `runnable: false`.

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 `cloud-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-wire-service.md

@@ -1,6 +1,6 @@
 # Audit Wire Service
 
-`createInvocationAudit` creates a per-request `InvocationAuditLog` that buffers audit events in memory and flushes them as a batch when the function-runner calls `closeWireServices` at the end of the request. If `singletonServices.audit` is not configured (local dev without Fabric), it returns a no-op `DisabledInvocationAudit` — no crash, events are silently dropped.
+`createInvocationAudit` creates a per-request `InvocationAuditLog` that buffers audit events in memory and flushes them as a batch when the function-runner calls `closeWireServices` at the end of the request. If `singletonServices.audit` is not configured (local dev without a hosting platform), it returns a no-op `DisabledInvocationAudit` — no crash, events are silently dropped.
 
 Pair with `createAuditedKysely` to auto-capture every Kysely query as an audit event.
 
@@ -38,4 +38,4 @@ const deleteUser = pikkuFunc({
 
 `closeWireServices` (called automatically by the function-runner) invokes `audit.close()` → `singletonServices.audit.write(batch)` → platform-specific flush (e.g. CF Queue, libsql INSERT). No manual flushing needed.
 
-> **Fabric note:** Fabric provisions the audit queue and consumer worker automatically. The audit table schema is in `db/sqlite/0003-audit.sql` (starter-template). Run `pikku fabric validate` to confirm the migration is in place.
+> **Note:** a hosting platform may provision the audit queue and consumer worker for you. The audit table schema is in `db/sqlite/0003-audit.sql` (starter-template). Run `pikku validate` to confirm the migration is in place.

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

@@ -1,5 +1,14 @@
 # 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
 
@@ -178,7 +187,7 @@ type AuditEvent = {
 
 `auditLog.write()` takes `Omit<AuditEvent, 'occurredAt'>` — you only supply `type`, `source`, and `metadata` (and `userIdentity` if overriding the session default).
 
-`userIdentity` is filled from the wire's session plus its `pikkuUserId`, and is left off entirely when all three are absent — which is what makes a cron or system invocation land with a null actor rather than an empty object.
+`userIdentity` is filled from the wire's session plus its `pikkuUserId`, and is left off entirely when all three are absent — which is what makes a cron or system invocation land with a null virtual user rather than an empty object.
 
 ## Do / Don't
 

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`.
 
@@ -203,7 +210,7 @@ what makes the split real.
 
 ### Audit Wire Service
 
-`createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and Fabric notes, read `references/audit-wire-service.md`.
+`createInvocationAudit` + `createAuditedKysely` add per-request audit buffering that flushes on request close (no-op if `audit` is unconfigured). For the full pattern, no-op behavior, custom-event usage, and hosting notes, read `references/audit-wire-service.md`.
 
 ### Built-in Services