@pikku/skills 0.12.37 → 0.12.39

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

@@ -0,0 +1,119 @@
+# An app on top of an OpenAPI spec
+
+The spec becomes an addon first — the `pikku-addon` skill's
+`references/openapi.md` covers generating, verifying and checking it against
+the real API. This reference is the decision that shapes the app around it:
+**whose credentials reach the upstream**, and what the person signs in with.
+
+## Pick the auth mode
+
+| The upstream…                                                            | Mode              | Command                       | Who signs in, and how                                   |
+| ------------------------------------------------------------------------ | ----------------- | ----------------------------- | ------------------------------------------------------- |
+| Is where the users already have accounts, and has a login endpoint      | Delegated         | `--auth-config <file>`        | Users sign in with their upstream login; no new account |
+| Takes a per-user API key, bearer token or basic auth                     | Per-user key      | (the default)                 | App account, then a Connect screen for the key          |
+| Uses OAuth2                                                              | Per-user OAuth    | (the default)                 | App account, then Connect via the OAuth consent         |
+| Is used on everyone's behalf with one key the business owns              | Shared secret     | `--auth shared`               | App account only; the key is a secret                   |
+| Takes no auth                                                            | None              | `--auth none`                 | App account only                                        |
+
+Per-user is the default because the upstream then enforces each person's own
+permissions. A shared secret acts with one identity for everyone, so the
+install exposes only its reads; widen that deliberately, never by default.
+
+The mode comes from the spec's `securitySchemes` unless a flag overrides it.
+Many real specs describe auth only in prose. The generator then refuses rather
+than guessing. Read the API's docs and pass the flag that is true.
+
+**Delegated is the right call whenever the upstream is the system of record for
+who the users are** — an ERP, a CRM, a helpdesk the whole team already logs in
+to. The app then has no separate sign-up, the upstream token is stored per user
+at sign-in, and every call acts as that user.
+
+## The auth-config file
+
+JSON, passed with `--auth-config`. Every field is optional except where noted.
+
+```json
+{
+  "headerName": "DOLAPIKEY",
+  "headerFormat": "raw",
+  "extraHeaders": { "Origin": "https://tenant.example.com" },
+  "delegated": {
+    "loginPath": "/login",
+    "loginMethod": "post",
+    "credentials": ["login", "password"],
+    "fields": { "login": "login", "password": "password" },
+    "encoding": "json",
+    "tokenPath": "success.token",
+    "expiresAtPath": "success.expires",
+    "identity": { "path": "/users/info", "method": "get" },
+    "claims": {
+      "source": "identity",
+      "externalId": "id",
+      "email": "email",
+      "name": ["firstname", "lastname"],
+      "role": "admin",
+      "tenantId": "entity"
+    },
+    "emailTemplate": "{login}@{host}",
+    "roles": { "1": "dolibarr-admin" }
+  }
+}
+```
+
+Top level — how every call authenticates:
+
+| Field          | Meaning                                                                                              |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `headerName`   | The header the API reads the token or key from. Setting it alone means a per-user API key            |
+| `headerFormat` | `raw` sends the bare value, `bearer` prefixes `Bearer `. Default: bearer for `Authorization`, else raw |
+| `extraHeaders` | Static headers on every request, login included — for upstreams that route on a header               |
+| `delegated`    | Present when users sign in with their upstream login                                                 |
+
+`delegated`:
+
+| Field            | Meaning                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| `loginPath`      | Required. The spec-relative login operation                                                               |
+| `loginMethod`    | Default `post`                                                                                            |
+| `credentials`    | What the sign-in form collects: `login` (a username or email), `email`, `password`, `apiKey`. Default `["email","password"]` |
+| `fields`         | The upstream's name for each credential, e.g. `{ "login": "username" }`                                  |
+| `encoding`       | `json`, `form` or `query` — how the login fields travel. Default `json`                                   |
+| `apiKeyHeader`   | The header an `apiKey` credential is sent in. Default `x-api-key`                                         |
+| `tokenPath`      | Required. Dot-path to the token in the login response                                                     |
+| `expiresAtPath`  | Dot-path to an epoch-seconds expiry. Defaults to the JWT's `exp` when claims come from the JWT            |
+| `identity`       | An operation that returns the signed-in user, called with the new token — for logins that return only a token |
+| `claims.source`  | `jwt`, `response` or `identity`. Default `identity` when `identity` is set, else `response`               |
+| `claims.*`       | Dot-paths to `externalId`, `email`, `name` (one path or several joined with a space), `role`, `tenantId`  |
+| `emailTemplate`  | Builds an email for an upstream user who has none: `{login}`, `{externalId}`, `{host}`. Such an address never claims an existing user |
+| `roles`          | Maps the raw `claims.role` value onto an app role; an unmapped value gets no role                          |
+
+Check it before building on it: start `pikku dev`, sign in once with
+`POST /api/auth/sign-in/delegated` as a real upstream user, and call an exposed
+operation with the session. A wrong password must be refused. Keep real
+credentials in the environment, never in the config or a test.
+
+What the install wires for delegated mode — `pikkuDelegatedAuth` in
+`src/auth.ts`, the token stored per user, actors carrying it into scenarios — is
+in the `pikku-auth` skill's `references/better-auth.md`.
+
+## The screens
+
+**If the app has a UI, build the sign-in or connect screen that matches the chosen auth mode (Sign in with <X> for delegated, a Connect <X> screen for per-user keys/OAuth, nothing for a shared secret), labelling fields in the upstream's terms (e.g. 'Dolibarr login', not 'Email').**
+
+- **Delegated** — the sign-in page posts to `POST /api/auth/sign-in/delegated`
+  with the fields named in `credentials` (`login` or `username`, `password`).
+  It replaces email sign-up; there is no "create account".
+- **Per-user key or OAuth** — a Connect screen after sign-in, and wherever a
+  call fails with `missing_credential`.
+- A `credential_rejected` error (`CredentialRejectedError`, 403) means the
+  upstream refused the stored token: show the sign-in again (`reauth:
+  'sign-in'`) or the Connect screen (`reauth: 'connect'`), not a generic error.
+
+## Scenarios
+
+A persona that signs in through the upstream needs an upstream credential to
+act with. The install adds `credentials` to `pikkuActor` in `src/auth.ts`, and
+at sign-in each actor stores `ACTOR_CREDENTIAL_<PERSONA>_<NAME>` from the
+environment (e.g. `ACTOR_CREDENTIAL_SALES_REP_DOLIBARR`). Without it every
+scenario step that reaches the upstream fails with `missing_credential`. The
+`pikku-scenario` skill's `references/personas.md` has the details.

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

@@ -16,6 +16,10 @@ 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.
 
+Each surface lands with its console link, filtered by the person's level
+(SKILL.md, "Who you are talking to"): a non-technical person sees the workflow
+or agent page, never the queue, scheduler or wire pages behind it.
+
 Budget the extra surfaces at one milestone each. They are not free, and a
 half-wired workflow engine is worse than no workflow engine.
 

package/skills/pikku-build/references/quick.md

@@ -223,9 +223,10 @@ bunx --bun pikku scenario run local --spawn
 
 ## 6. Hand it over honestly
 
-Tell the user, in one short paragraph: what runs, what it is seeded with, and
-that this is a quick build — no knowledge base, no milestones, no design pass,
-access control clicked-through rather than proven.
+Tell the user, in one short paragraph and at their level (SKILL.md, "Who you
+are talking to"), with console links rather than descriptions: what runs, what
+it is seeded with, and that this is a quick build — no knowledge base, no
+milestones, no design pass, access control clicked-through rather than proven.
 
 **Upgrading to a real build is additive, not a rewrite.** If they want it, switch
 to `references/app.md` and do this, in order:

package/skills/pikku-knowledge/SKILL.md

@@ -3,16 +3,15 @@ name: pikku-knowledge
 description: >-
   Use when writing, reading, reorganising or validating a project's knowledge/ directory — the
   notes that say what the app is, in the language its users use. Covers the Open Knowledge Format
-  note (path-as-identity markdown, YAML frontmatter, only `type` required), the sections of the
-  app-project profile (slices, entities, decisions, questions, wishlist) and the one question each
-  answers, slice status/entities/gherkin rules, the `resource:` URI scheme tying a note to the
-  code it is about, the shapes that are NOT a knowledge base, and the `pikku knowledge
-  validate|index` commands. TRIGGER when: user asks to write down a decision, requirement, entity
-  or open question; asks what the app does or is; asks about knowledge/, notes, slices,
-  an index.md, or a diagram, callout or decision block; or hands over a product
-  brief to record. DO NOT TRIGGER when: user asks what
-  functions, routes, tables or permissions exist (that is `pikku meta` / `pikku info`, never a
-  note), or to write a scenario test (use pikku-scenario).
+  note (path-as-identity markdown, YAML frontmatter, only `type` required), the app-project
+  profile's sections (milestones, entities, decisions, questions, wishlist) and what each answers,
+  milestone status/entities/gherkin rules, the `resource:` URI scheme tying a note to its code,
+  what is NOT a knowledge base, and `pikku knowledge validate|index`. TRIGGER when: user asks to
+  write down a decision, requirement, entity or open question; asks what the app does or is; asks
+  about knowledge/, notes, milestones, an index.md, or a diagram, callout or decision block; or
+  hands over a product brief to record. DO NOT TRIGGER when: user asks what functions, routes,
+  tables or permissions exist (that is `pikku meta` / `pikku info`, never a note), or to write a
+  scenario test (use pikku-scenario).
 installGroups: [core]
 agent:
   tools: read, write, edit, bash, grep
@@ -76,7 +75,7 @@ Frontmatter fields:
 
 | Field         | Meaning                                                                                                                 |
 | ------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `type`        | **The only required field.** `slice` — or `milestone`, when the project's own `knowledge/index.md` names the section that way; `validate` accepts both, so follow the scaffold rather than this list. Then `entity`, `decision`, `note`, `overview`. Lowercase — gates compare it literally. |
+| `type`        | **The only required field.** One of `milestone`, `entity`, `decision`, `note`, `overview`. Lowercase — every gate compares it literally, and `milestone` is the exact string `readMilestones` filters on, so a near-miss is a note no command can see. |
 | `title`       | What to call the note in a listing. Falls back to the first heading, then the filename.                                 |
 | `description` | One line, used as the note's subtitle in a section index.                                                               |
 | `resource`    | Comma-separated `<kind>:<id>` URIs — the code this note is about. See below.                                            |
@@ -92,9 +91,9 @@ Plain markdown links between notes — `[revocation](../decisions/revocation-end
 ```
 knowledge/
   index.md                                  # type: overview — the map
-  slices/
+  milestones/
     index.md
-    01-the-daily-entry.md                   # type: slice
+    01-the-daily-entry.md                   # type: milestone
   entities/
     index.md
     entry.md                                # type: entity
@@ -116,7 +115,7 @@ Each section answers exactly one question, which is what lets a reader find a no
 
 | Section               | The question it answers                                            |
 | --------------------- | ------------------------------------------------------------------ |
-| `slices/`             | What is one buildable piece of this app, and what proves it works? |
+| `milestones/`         | What is one buildable piece of this app, and what proves it works? |
 | `entities/`           | What is this thing, in the words users use for it?                 |
 | `decisions/`          | What was chosen, and what does that rule out?                      |
 | `decisions/security/` | Who may do what?                                                   |
@@ -125,13 +124,13 @@ Each section answers exactly one question, which is what lets a reader find a no
 
 **Create a section the turn you have a note for it** — never a scaffold of empty directories, and never a section without its own `index.md`. A section index says in one line what belongs in it; that sentence is the reason the file exists, so `pikku knowledge index` writes only the note listing and leaves your prose alone.
 
-## Slices
+## Milestones
 
-A slice is the one note type that is a piece of _work_ rather than a fact, so it alone carries state and size:
+A milestone is the one note type that is a piece of _work_ rather than a fact, so it alone carries state and size. It lives in `knowledge/milestones/` and nowhere else: `readMilestones` matches on that directory literally, so the same note under another section is invisible to every gate and command below.
 
 ````markdown
 ---
-type: slice
+type: milestone
 title: The daily entry
 description: An owner writes one entry per day, and sees it on the day.
 status: proposed
@@ -151,9 +150,9 @@ And writing again replaces it rather than adding a second
 ```
 ````
 
-- **`status`** is `designing` → `proposed` → `dispatched` → `built`. Nothing else. Every gate compares it literally. `designing` sits BEFORE `proposed`: the slice is written down but must not be built yet, because whoever is being shown its looks has not picked one. Only `proposed` is dispatchable, so the two cannot be one status without a slice being built out from under the person still choosing.
+- **`status`** is `proposed` → `dispatched` → `built`. Nothing else — `MILESTONE_STATUSES` is those three, and every gate compares them literally, so an invented status fails `validate` rather than degrading. Only `proposed` is dispatchable. A profile may add one of its own ahead of `proposed` for work that is written down but must not be built yet; that is the profile's to define and validate, not core's.
 - **`statusAt:` and `attempts:` are bookkeeping, not content — never hand-edit them.** A loop driving this base writes both. `statusAt:` is stamped by whatever moved the status, and is what makes "how long has this been building?" answerable; the file's mtime is not the transition time, because a note is edited after dispatch for all sorts of reasons. `attempts:` is `seat@hash` entries recording which seat has already tried to move this note forward, against the content it was trying to move — it is the loop's only brake, and clearing it by hand hands back a budget that exists to stop a note nothing can satisfy being rewritten forever. Rewriting the note's real content refunds that budget on its own, which is the point: an answer that changes the note is what unsticks it.
-- **`entities`** lists what the slice touches, **at most three**. Past three it is not one buildable piece — split it.
+- **`entities`** lists what the milestone touches, **at most three**. Past three it is not one buildable piece — split it.
 - **The scenario is a fenced `gherkin` block, in the third person.** `Given 'owner' has no entry` — never `Given I have no entry`. A quoted word _means a persona_, which is what lets a reader (and a test) tell who is acting. First person hides that, so it is rejected. The console draws the keywords as a column and each quoted persona as a chip, so a first-person scenario is visibly a block with no personas in it.
 
 ## Showing it
@@ -231,7 +230,7 @@ These are all things that exist somewhere better, so a note is always the copy t
 | Do not write                        | Because it lives in                                        |
 | ----------------------------------- | ---------------------------------------------------------- |
 | a `personas/` section               | `definePersonas()` in the project's own code               |
-| a `scenarios/` section              | the gherkin block inside the slice it belongs to           |
+| a `scenarios/` section              | the gherkin block inside the milestone it belongs to       |
 | a `permissions/` section            | a decision note under `decisions/security/`                |
 | a list of tables, columns or routes | `pikku meta` — the generated schema _is_ the schema        |
 | a changelog                         | `CHANGELOG.md` at the repo root                            |
@@ -250,7 +249,7 @@ pikku knowledge index           # refresh every index.md
 pikku knowledge index --check   # report stale indexes without writing (CI gate)
 ```
 
-`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, slices with a bad or missing `status`, slices over three entities, slices with no gherkin block or a first-person one, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
+`validate` reports: notes with no `type`, a missing `knowledge/index.md`, a section with no `index.md`, notes flat at the root, sections that duplicate what the project already declares, milestones with a bad or missing `status`, milestones over three entities, milestones with no gherkin block or a first-person one, `decision` fences that state no `chosen:` or rule nothing out, and every `resource:` that no longer resolves. Errors fail the command; warnings do not.
 
 `index` rewrites only the block between `<!-- pikku:knowledge-index -->` markers, creating a scaffolded `index.md` for a section that has none. It is idempotent — running it twice changes nothing.
 
@@ -312,4 +311,4 @@ The exception, and it is narrow: bookkeeping the loop owns. `statusAt:` and `att
 
 OKF permits frontmatter fields a reader does not know, and the parser ignores them rather than failing. That is the extension point: a tool layered on Pikku can add its own sections and fields on top of everything above without forking the format.
 
-Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — and a `design:` field on a slice pointing at the design options it was built from. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.
+Fabric is the one that exists. It adds `decisions/design/` — rules about how the app looks and behaves — a `screens/` section, and a `design:` field on a milestone pointing at the design options it was built from. Both are Fabric's to validate; `pikku knowledge validate` passes them through untouched. Everything else in this skill is the same in both.

package/skills/pikku-scenario/SKILL.md

@@ -35,13 +35,13 @@ Use this skill as an execution checklist, not reference material.
 This skill covers writing and running scenarios end to end. Four topics are one level down, and
 each says when to open it:
 
-| Read                        | For                                                                       |
-| --------------------------- | ------------------------------------------------------------------------- |
-| `references/steps.md`       | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given |
-| `references/browser.md`     | Browser bindings, and locating by message key in a translated app         |
-| `references/personas.md`    | Personas vs actors, `definePersonas`, and the human "Sign in as …" switcher |
-| `references/coverage.md`    | Live coverage, filling it, and unit tests for pure logic                  |
-| `references/persona-run.md` | Running a persona as a model-driven virtual user against a stage          |
+| Read                        | For                                                                                                          |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `references/steps.md`       | Authoring a `pikkuScenarioStep` — intent, witnesses, what a step is given                                    |
+| `references/browser.md`     | Browser bindings, and locating by message key in a translated app                                            |
+| `references/personas.md`    | Personas vs actors, `definePersonas`, upstream credentials for actors, and the human "Sign in as …" switcher |
+| `references/coverage.md`    | Live coverage, filling it, and unit tests for pure logic                                                     |
+| `references/persona-run.md` | Running a persona as a model-driven virtual user against a stage                                             |
 
 ## What a scenario is
 
@@ -245,7 +245,7 @@ suite survives its first redesign:
   through the actor.
 - **Steps describe intent, not actions** — `buys the £5 strawberry milkshake`, never
   `clicks [data-testid=add]`. The clicking lives in plain utilities the step composes.
-- **`then` bindings are witnesses, not alternatives** — a `then` runs *every* binding it declares
+- **`then` bindings are witnesses, not alternatives** — a `then` runs _every_ binding it declares
   and fails when they disagree, because "database right, user still watching a spinner" is the bug
   nobody catches.
 - **What language the prose is in** — identifiers are English in every project; `description`,
@@ -265,6 +265,7 @@ whole project — codegen builds the `PersonaId` union from it, materialises one
 scenario actor per person, and seeds a user row each:
 
 ```ts snippet:definePersonas
+
 ```
 
 `pikku.config.json` carries the settings around them — nothing about a person:

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

@@ -5,7 +5,7 @@ A **persona** is a person your product is for; an **actor** is one body that sig
 - 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.
 - Never write an email address: each is derived from the persona 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 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 persona 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 personas in TypeScript
@@ -50,6 +50,32 @@ A project that never declares a persona keeps working: a scenario that names no
 - `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.
 
+## Actors 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. An actor has none until one is stored
+for it, so every step that reaches the addon fails with `No <X> session`. Give
+the `actor` plugin a `credentials` option, and each actor 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 actor sign-in the plugin reads `ACTOR_CREDENTIAL_<PERSONA>_<NAME>` —
+`dan` + `dolibarr` is `ACTOR_CREDENTIAL_DAN_DOLIBARR` — and stores it with
+`credentialService.set` for that actor. 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 actor has no
+upstream credential: `remove` drops one stored at an earlier sign-in.
+
+- **Values live in `.env` (or CI secrets), never in `personas.ts` or code.**
+  Use a dedicated upstream test account per persona, 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 actor
+  in re-stores whatever the variable holds now.
+
 ## The same actors sign a human in
 
 Declared actors are not only for automated runs. `signInPath` is Better Auth's
@@ -57,8 +83,8 @@ Declared actors are not only for automated runs. `signInPath` is Better Auth's
 frontend gets a one-click "Sign in as …" switcher over the **same** list, and an
 app can be reviewed as each kind of user without anyone knowing a seed password.
 
-The sandbox dev server bakes both halves into the frontend from the declared
-personas: `VITE_DEV_ACTORS` (the JSON actor list) and `VITE_DEV_ACTOR_SECRETS`
+The dev server bakes both halves into the frontend from the declared
+personas — the sandbox's, or the template's `bun run dev`, never `pikku dev`: `VITE_DEV_ACTORS` (the JSON actor list) and `VITE_DEV_ACTOR_SECRETS`
 (`{ email: credential }`, one per persona — `SCENARIO_ACTOR_SECRET` itself never
 goes in a bundle; see **pikku-auth**). Neither var is set in a production
 build, so the control renders nothing there — but gate the reads on your
@@ -85,3 +111,39 @@ When the switcher is there but signing in fails with `401 Invalid actor
 secret`, check which server answered before checking the secret: a frontend
 whose dev proxy (`VITE_API_PROXY`, default `http://localhost:3000`) points at
 another project's API sends the sign-in there.
+
+**A runner of your own that starts vite has to bake them itself**, from the
+generated persona meta (`<outDir>/workflow/personas.gen.json`, which already
+carries the derived `email`):
+
+```js
+const personas = Object.values(JSON.parse(readFileSync(personasPath, 'utf8')))
+
+env.VITE_DEV_ACTORS = JSON.stringify(
+  personas.map(({ id, email, name, jobTitle }) => ({
+    key: id,
+    email,
+    name,
+    jobTitle: jobTitle ?? '',
+  }))
+)
+env.VITE_DEV_ACTOR_SECRETS = JSON.stringify(
+  Object.fromEntries(
+    await Promise.all(
+      personas.map(async ({ email }) => [
+        email,
+        await deriveActorSecret(env.SCENARIO_ACTOR_SECRET, email),
+      ])
+    )
+  )
+)
+```
+
+**Set `SCENARIO_ACTOR_SECRET` yourself**, at least 32 characters, in the
+environment both processes read. Left unset, `pikku dev` mints an ephemeral root
+for its own run that a separately spawned vite cannot see, so the two derive
+from different roots: the switcher renders every persona and each click is
+refused, which reads as a broken login rather than missing configuration. On a
+brand-new project the persona file does not exist until the first `pikku dev`
+codegen, after vite has baked an empty list — watch it and restart the frontend
+when it changes.