feat(harness): agent-drivable dev harness and CI that gates

A coding agent could develop this repo's Go packages and could not
develop the application: every path to running YellowJacket ended in a
blocking GTK window, so 265 bound methods, 46 events, 33 component
directories and 13 stores had exactly one form of verification
available — `tsc --noEmit`.

The unlock is that `wails dev`'s dev server on :34115 serves the real
frontend with the real generated bindings against the same Go backend a
desktop window attaches to, so a plain Chromium under Xvfb gets a fully
functional app. Four test tiers now exist, cheapest first:

- `make ui-test` — 313 Vitest tests in a real browser in ~2 s, no app,
  no backend, no display. Works because `frontend/wailsjs/` is a pure
  passthrough to `window.go`/`window.runtime`, so faking just those two
  globals runs the real bindings and the real store code.
- `make test` — services in-process, asserting on the payload the
  frontend would receive, via a new `events.Emit` wrapper.
- `make dev-headless` + `playwright-cli` — the real app, driven
  interactively, with an event bridge on `window.__yjEvents` and a
  dev-only control surface at `/__test/`.
- `make e2e` — 19 of those flows frozen as Playwright specs.

`events.Emit(ctx, …)` replaces all 35 direct `runtime.EventsEmit` call
sites: wails' `getEvents` `log.Fatalf`s on any context without its
runtime, so those paths could not run under test and a background
worker could take the app down. Four packages had each hand-rolled the
same guard; nine more guarded on `ctx != nil`, which does not help.
`TestNoDirectRuntimeEmits` fails the build on a new one.

Fixtures are generated, not committed (`make testdata`), and seeds are
built by *running the app* — never by hand-writing config and DB rows,
which would be a second description of a valid YJ_HOME.

`.gitea/workflows/ci.yml` is the first workflow here that tests
anything; the other three only package, so `gitea_ci` reported only
packaging jobs and misled anyone asking whether a push was healthy.
Both jobs were prototyped to green in a bare ubuntu:24.04 container
before the YAML was written, which immediately caught `make lint`
linting three configurations that nothing builds: all three passes
omitted `webkit2_41`, so wails resolved webkit2gtk-4.0 — which Arch
still ships and Ubuntu 24.04 dropped.

Operational instructions live in `.pi/skills/yellowjacket-dev/`,
measured discoveries in `.planning/NOTES.md`, and architecture in
`CLAUDE.md` — split by tense, not by topic, because a topical split
gives every new fact two plausible homes. `make skill-check` fails a
commit if the skill cites a make target that does not exist.

.pi/journal.md

@@ -0,0 +1,112 @@
+# Work log
+
+Temporal memory: what happened and what's next. Structure lives in
+`CLAUDE.md`, operational instructions in `.pi/skills/yellowjacket-dev/`,
+measured discoveries in `.planning/NOTES.md`. Don't duplicate those here.
+
+## Current state
+
+Plan 005 (agent development harness) is **complete — all seven
+phases**. Everything from phase 1 onward is still **uncommitted**: one
+large but coherent working-tree diff, nothing pushed.
+
+All four tiers verified green from a cold, cleaned state:
+`make ui-test` 313 passed, `make lint` 0 issues × 3 configurations,
+`make test` green × 3 passes, `make e2e` 19 passed. Both CI jobs
+verified green in a bare `ubuntu:24.04` container, including 19/19 on
+WebKit.
+
+- [ ] **Push `.gitea/workflows/ci.yml` and confirm with `gitea_ci`.**
+      Nothing has run on the shared runner yet — the whole workflow was
+      validated locally in Docker. A run that never starts looks
+      identical to one that passed, so the push is not done until
+      `gitea_ci` says so.
+- [ ] Decide whether to commit phases 1–7 as one commit or split by
+      phase (waiting on the user; nothing is committed yet).
+
+Unverified on the real runner, and the likeliest first failures:
+`actions/upload-artifact` needs node in the container (it is installed
+by an earlier step, and the step is `continue-on-error`, so a failure
+there cannot mask a real one); and the `npm_config_store_dir` pnpm
+cache is best-effort — if pnpm ignores it we lose warmth, nothing else.
+
+Open items deliberately not fixed: WAV tags are write-only
+(`TestWAVTagsAreNotReadableYet`), `themeStore.loadFromBackend`'s failure
+handler cannot recover, `backend/playlist` has no CRUD suite.
+
+## Log
+
+### 2026-08-11 — cold skill run, then phase 7 (CI)
+
+- **Followed the skill cold first**, as the last session asked. It
+  works: app up from a wiped `.dev/`, an undocumented flow driven
+  (queue panel + shuffle, asserted on `QueueModeChanged`), stopped —
+  ~1 minute, no dead ends. One real config bug: `outputDir` in
+  `.playwright/cli.config.json` resolves against **cwd**, not the
+  config file's directory (only `initScript` does that), so snapshots
+  were landing above the repo and a *stale* one from the previous
+  session answered `ls -t` instead. That cost a DOM walk to disprove a
+  regression that did not exist. Four smaller doc gaps fixed
+  (`sandbox-seed` already runs `testdata`; `ui-setup`/`e2e-setup` were
+  undocumented prerequisites; `snapshot` prints a path; `dev-stop`
+  leaves the browser open), plus `dev-headless.sh`'s own banner, which
+  was suggesting the bare `window.go` call its next paragraph warns
+  against.
+- **Built both CI jobs as container scripts before writing any YAML**,
+  then transcribed the YAML back out and re-ran it to prove the
+  transcription. Push-and-see is a bad loop on a self-hosted runner.
+- **It found a real bug immediately**: `make lint` omitted
+  `webkit2_41` on all three passes, so it was linting configurations
+  nothing builds. Invisible on Arch (which still ships
+  `webkit2gtk-4.0.pc`), fatal on Ubuntu 24.04. Tag sets now match
+  `make test`.
+- **Both open decisions settled by measurement**: ALSA `null` PCM for
+  audio (no daemon; the elapsed clock really advances), dead-address
+  stub for the explore artifact (and setting it for the *app* run, not
+  just seeding, is worth 8x on suite wall clock). **WebKit is a
+  required step** — it had never been run anywhere, so one throwaway
+  container run replaced a coin flip with 19/19 at +11 s.
+
+### 2026-08-10 — phase 6, pi affordances
+
+- Added `.pi/skills/yellowjacket-dev/` as a directory rather than a flat
+  file: only the description is always in context, so `SKILL.md` stays
+  short enough that reading it whole is never a decision, and the deeper
+  material sits in `references/{harness,fixtures,ui-tier,schema-change}.md`.
+- Settled the CLAUDE.md-vs-skill split **grammatically, not topically**,
+  because a topical split is what rots — every new fact gets two
+  plausible homes. Three docs, three tenses: NOTES.md is past
+  (measured, dated, append-only), CLAUDE.md is present (what the system
+  is), the skill is imperative (what to run). A new paragraph's tense
+  decides where it goes.
+- The five gotchas (binding timeouts, first-run wizard, `pkill -f`,
+  seeds-by-running, WebKit-is-CI-only) went **inline in SKILL.md**, not
+  into a reference: you need them before the failure, not after.
+- Trimmed CLAUDE.md's "Fixtures and the headless harness" section by
+  about half — the command sequences and gotchas it was carrying are now
+  the skill's, and leaving both would have created exactly the duplicate
+  description this repo has a standing rule against.
+- Added `make skill-check` / `scripts/skill-check.sh` + a pre-commit
+  hook: every command in `.pi/**/*.md` must be a real `make` target, so
+  the Makefile stays the source of truth for invocation and a renamed
+  target fails a commit instead of misleading an agent later. Verified
+  it fails (it caught its own not-yet-created target) and passes.
+- Added the `/e2e` prompt template: promoting a hand-driven
+  `playwright-cli` session into a spec is a transcription with four
+  fixed substitutions (refs → testids, sleeps → `waitForEvent`, raw
+  `window.go` → `callBinding`, short fixture → `LONG_TRACK`), plus three
+  runs — pass, pass again, pass after a DB restore — because the usual
+  failure is a spec depending on state the hand-driving left behind.
+- One shell trap: under `set -euo pipefail`, `x="$(make -pqRr | …)"`
+  fails the whole assignment, because `make -q` exits non-zero when a
+  target is out of date and `pipefail` propagates it.
+
+### Earlier
+
+Phases 1–5 of plan 005: fixture generator and manifest, headless launch
+and seeds, the event bridge + `data-testid` pass + `backend/testctl` +
+`e2e/`, the Vitest component tier + `make bindings-check`, and the
+`events.Emit` wrapper with its in-process service-event tests. Recaps
+and the five "verified end to end" blocks are in
+`.planning/plans/active/005-agent-development-harness.md`; the lessons
+are in `.planning/NOTES.md`.

.pi/prompts/e2e.md

@@ -0,0 +1,55 @@
+---
+description: Promote a hand-driven playwright-cli session into a committed spec in e2e/
+argument-hint: "[name of the flow]"
+---
+Promote the flow I just drove by hand into a committed Playwright spec.
+Flow: ${@:-infer it from the playwright-cli commands in this session}
+
+This is a transcription with fixed substitutions, not a fresh test.
+Work from what actually happened in this session, not from what the UI
+looks like it should do.
+
+**1. Recover the flow.** List the `playwright-cli` calls made this
+session, in order, and the assertion each one was really checking. Then,
+before writing anything, ask the running app what fired:
+
+```
+playwright-cli -s=yj eval "() => window.__yjEvents.names()"
+```
+
+Await the events that are actually in that list. Do not guess event
+names from `backend/events/`.
+
+**2. Substitute, one for one.**
+
+- `click e15` → a role or `data-testid` selector. Snapshot refs are
+  per-snapshot and meaningless in a spec. If the only stable selector
+  would be structural, add a `data-testid` to the Lit component and
+  re-run `make ui-test`.
+- any sleep, or "it looked settled" → `waitForEvent(app, 'X')`.
+- `window.go.…` → `callBinding(app, path, args)`, which times out.
+- a short fixture track → `LONG_TRACK`, if the flow needs playback to
+  still be running on the next line. Every other fixture is 2–6 s.
+- `getByRole('button', { name })` → add `exact: true`.
+
+**3. Place it.** `e2e/specs/<area>.spec.ts`, importing `test`, `expect`
+and the helpers from `../support/fixtures.js` — never `@playwright/test`
+directly. Match the surrounding specs' comment style: say what the test
+is protecting against, not what the lines do.
+
+**4. Prove it is a spec and not a recording.** Three runs, in order:
+
+```
+make e2e E2E_ARGS='--grep "<name>"'    # it passes
+make e2e E2E_ARGS='--grep "<name>"'    # again — catches dependence on
+                                       #   state the first run left
+```
+
+then once more after restoring the database through `/__test/`, which
+catches dependence on state *my hand-driving* left behind — the single
+most likely way a promoted spec passes here and fails in CI. Leave the
+database as you found it: snapshot/restore, or reset in `beforeEach`.
+
+**5. Then the whole suite:** `make e2e`. If the promotion turned up a
+new trap, append it to `.planning/NOTES.md`; if it turned up a bug,
+tell me rather than asserting the broken behaviour.

.pi/settings.json

@@ -0,0 +1,3 @@
+{
+  "skills": ["../.claude/skills"]
+}

.pi/skills/yellowjacket-dev/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: yellowjacket-dev
+description: Operating YellowJacket's development harness — which of the four test tiers to use for a given change, how to run the app headless and drive it with playwright-cli, seed and sandbox lifecycle, the three build-tag passes, and the failure modes that waste a cycle if you meet them cold. Use whenever building, running, testing or debugging this repo.
+---
+
+# Working on YellowJacket
+
+`CLAUDE.md` says what this system **is**. This skill says what to
+**run**. `.planning/NOTES.md` records what we **measured** and when.
+Keep them in those three tenses: if something here is wrong, fix it
+here and add the discovery to `NOTES.md` — do not add a corrective
+paragraph to `CLAUDE.md`.
+
+Every command below is a `make` target on purpose. The Makefile is the
+source of truth for *how* to invoke something; this file only decides
+*which* and *in what order*. `make skill-check` fails if a target named
+here has disappeared.
+
+## Read this part before you fail
+
+Five things cost a cycle each the first time. They are here, not in a
+reference, because you need them *before* the failure, not after.
+
+- **Time out every binding call.** A bound Go method called with wrong
+  argument types makes the backend log `error parsing arguments` and
+  **never fire the callback**, so the promise hangs forever. Use
+  `window.__yjEvents.call(path, args, ms)` (browser) or `callBinding`
+  (specs), never a bare `window.go.…`. When one hangs anyway,
+  `make dev-logs` — `.dev/app.log` is the only place the reason appears.
+- **Nothing is clickable on a fresh `YJ_HOME`.** `<first-run-wizard>`
+  intercepts all pointer events until a library exists, and the click
+  fails with a Playwright interception error that reads like a selector
+  bug. Use a seed unless you are *testing* the wizard, in which case
+  `make dev-headless-fresh`.
+- **Never `pkill -f`.** The pattern matches the invoking shell's own
+  command line, killing it and silently dropping the rest of your
+  compound command. `make dev-stop` kills by saved PID.
+- **Seeds are produced by running the app**, never by hand-writing a
+  `config.toml` and DB rows — a hand-built `YJ_HOME` is a second
+  description of a valid one and will drift. `make sandbox-seed` drives
+  the real `AddLibrary` binding and waits for the real scan.
+- **Playwright's WebKit does not run on Arch** (Ubuntu-only libs).
+  `--browser=webkit` is CI-only; local work is Chromium.
+
+## Which tier
+
+Four tiers. Start at the cheapest one that can see your change, and
+only climb when it cannot.
+
+| You changed | Run | Cost |
+|---|---|---|
+| A Lit component, a store, the shortcut service | `make ui-test` | ~2 s, no app |
+| …and it renders differently | `make ui-visual` | + 6 baselines, opt-in |
+| Any Go code | `make test` | 3 passes, ~2 min |
+| A service that emits events | `make test` — assert on the payload, see `backend/queue/emit_test.go` | in-process, no app |
+| A bound method or a bound struct field | `make bindings` then `make ui-test` | ~1.5 s + 2 s |
+| A user-visible flow across frontend *and* backend | `make e2e` (needs the app up) | ~1 min |
+| Something you cannot predict — exploring | `make dev-headless SEED=default` + `playwright-cli` | interactive |
+| A `.sql` or `.templ` file | `make generate`, then the checklist in [references/schema-change.md](references/schema-change.md) | |
+
+Two targets are once-per-clone prerequisites that are **not**
+dependencies of the targets needing them, so on a fresh checkout each
+fails with a missing-browser error that reads like a broken test:
+`make ui-setup` before `make ui-test`, and `make e2e-setup` before
+`make e2e`. (`make testdata` *is* a dependency of `make test` and
+`make sandbox-seed`; run it by hand only when invoking `go test`
+directly, since anything using `internal/testfixtures` **skips**
+rather than fails without it — a green run without the library means
+less than it looks.)
+
+Two rules about climbing:
+
+- **A component test passing is not the app rendering.** If you touched
+  anything in `frontend/src`, verify it in the real app too — start it
+  headless, `screenshot --filename=/tmp/shot.png`, and *read the PNG*.
+- **Do not write an e2e spec first.** Drive the flow by hand, then
+  promote it with `/e2e`. Specs written blind assert on selectors that
+  do not exist.
+
+Before a commit, the gate is `make lint`, `make test`, `make ui-test`
+and `make bindings-check` — all four are also lefthook hooks, so
+skipping them locally only defers the failure.
+
+## Running the app
+
+The app cannot be started without a display: `devserver.Run` ends in a
+blocking GTK window with no flag to suppress it. The harness gives it a
+virtual one and returns.
+
+```bash
+make sandbox-seed NAME=default    # once (~10 s; runs make testdata itself,
+                                  # then builds a seed by running the app)
+make dev-headless SEED=default    # starts in the background, returns when :34115 answers
+make dev-logs                     # tail .dev/app.log
+make dev-stop                     # SIGTERM, so shutdown hooks persist state
+```
+
+Then drive it. Run `playwright-cli` **from the repo root** — it picks
+up `.playwright/cli.config.json` from the cwd, and writes its snapshots
+and console logs to `.playwright-cli/` relative to the cwd too. `playwright-cli`'s own skill covers the commands; what
+is specific here is that a session must be *named* so it survives
+across separate shell calls:
+
+```bash
+playwright-cli -s=yj open http://localhost:34115
+playwright-cli -s=yj snapshot                       # a11y tree, pierces shadow DOM
+playwright-cli -s=yj screenshot --filename=/tmp/shot.png
+playwright-cli -s=yj eval "() => window.__yjEvents.names()"
+playwright-cli -s=yj eval "() => window.__yjEvents.call('queue.Queue.GetState', [], 5000)"
+playwright-cli -s=yj click e391                     # ref from the snapshot
+playwright-cli -s=yj close                          # `make dev-stop` does not do this
+```
+
+`snapshot` prints a *path*, not the tree — read the file it names, and
+check the timestamp, because a stale one from a previous session sits
+in the same directory.
+
+`.playwright/cli.config.json` is picked up automatically: it sets the
+viewport, `data-testid`, and the init script that installs the event
+bridge. **Assert on an event, not a timeout** — half this app is
+push-driven. The bridge and the dev-only `/__test/` control surface are
+documented in [references/harness.md](references/harness.md).
+
+Other `YJ_HOME`s exist for humans and block the terminal: `make dev`,
+`make sandbox <name>`, `make fresh-install`. Do not use them; you will
+never get the shell back.
+
+## Go, and the three build configurations
+
+`make test` and `make lint` already run all three. Spell them out only
+when iterating on a single package:
+
+```bash
+go test -tags webkit2_41 ./backend/player/                        # the app build
+go test -tags webkit2_41 -run TestName ./backend/player/
+go test -tags "webkit2_41 indexbuild" ./backend/explore/... ./cmd/...   # dump importer
+go test -tags "webkit2_41 dev" ./backend/testctl/...              # control surface
+```
+
+Forgetting the tag gives a build error that looks like a missing
+package. Audio integration tests additionally need
+`YELLOWJACKET_INTEGRATION=1`.
+
+Three things golangci-lint v2 will reject that are easy to write:
+a dynamic `fmt.Errorf` without a sentinel (`err113`), a `return` with
+no blank line before it (`nlreturn`), and a long `//nolint` comment on
+the same line as its statement (`golines` reflows it and breaks the
+directive) — put the directive on its own line above.
+
+**Emit events through `events.Emit(ctx, …)`, never
+`runtime.EventsEmit`.** `TestNoDirectRuntimeEmits` walks the tree and
+fails the build otherwise, including in files no lint pass compiles.
+
+## References
+
+- [harness.md](references/harness.md) — the event bridge API, the
+  `/__test/` endpoints, and the config traps.
+- [fixtures.md](references/fixtures.md) — the generated library, the
+  manifest, and selecting fixtures by case.
+- [ui-tier.md](references/ui-tier.md) — how the Vitest tier fakes Wails,
+  and what breaks in it.
+- [schema-change.md](references/schema-change.md) — the two-file
+  schema/migration checklist.

.pi/skills/yellowjacket-dev/references/fixtures.md

@@ -0,0 +1,67 @@
+# The fixture library
+
+`test_data/music_library_test/` is **generated, not committed**:
+`make testdata` (~1 s) builds 31 deterministic tracks across MP3, FLAC,
+Ogg Vorbis and WAV. `make testdata-force` rebuilds unconditionally,
+`make testdata-clean` deletes it. `make test` and `make sandbox-seed`
+depend on it, so it is rarely run by hand.
+
+Tests that need it fetch it through `internal/testfixtures` and skip
+themselves when it has not been generated.
+
+## Select by case, never by path
+
+```go
+m := testfixtures.Load(t)
+paths := m.Case(t, testfixtures.CaseCoverDedup)
+track := m.Track(t, rel)
+```
+
+Cases: `cover-dedup`, `multi-disc`, `various-artists`, `flac-album`,
+`ogg-album`, `wav-tracks`, `partial-tags`, `unicode`, `duplicates`,
+`edge-lengths`, `broken`.
+
+Two invariants worth not breaking:
+
+- **The clean library is exactly 31 tracks**, because `sandbox-seed`
+  verifies the scan against that count. Deliberately malformed files
+  live in a *sibling* root, `test_data/music_library_broken/`
+  (`m.BrokenPath()`), so the scanner never sees them.
+- **Tags are written by `backend/tagwriter`, not by ffmpeg** (which
+  encodes with `-map_metadata -1`). Fixture and reader therefore cannot
+  drift into agreeing with each other and disagreeing with reality.
+
+The manifest (`test_data/music_library_test.manifest.json`, outside the
+scanned root) hashes the *spec* — paths, formats, durations, tags,
+cover identity — not the bytes, because ffmpeg stamps encoder version
+strings and identical specs produce different bytes on different builds.
+
+## In e2e specs
+
+- **Every fixture except one is 2–6 seconds.** A spec that starts
+  playback and then clicks pause races the track ending and fails
+  against a correct UI. Use `LONG_TRACK` (90 s, `edge-lengths`) exported
+  from `e2e/support/fixtures.ts`.
+- **WAV tracks scan in untitled.** `backend/tagwriter` writes WAV tags
+  into a RIFF `id3 ` chunk and `dhowden/tag` has no RIFF parser, so
+  there is no "Field Recordings" artist in the Artists view. This is a
+  known open bug pinned by `TestWAVTagsAreNotReadableYet`; do not
+  "fix" a spec by asserting the broken behaviour elsewhere.
+
+## Seeds
+
+```bash
+make sandbox-seed NAME=default   # build (boots a fresh YJ_HOME and drives the app)
+make sandbox-seeds               # list
+make dev-headless SEED=default   # restore into a run
+```
+
+A seed is a tarred `YJ_HOME` produced by *running the app*: fresh home →
+real `AddLibrary` binding → poll until the real scan reports the
+manifest's track count → SIGTERM so shutdown hooks persist state → tar.
+Never hand-write one. Seeding points `YJ_CORE_INDEX_URL` at a dead
+address on purpose, so no seed depends on what the explore artifact
+server happened to be serving.
+
+Rebuild a seed after any schema change, or the restored database is
+migrated on open in a way the seed's author never saw.

.pi/skills/yellowjacket-dev/references/harness.md

@@ -0,0 +1,85 @@
+# The harness: event bridge and control surface
+
+Two things ride on top of the headless app. Both exist only in dev
+builds; neither is reachable from a shipped binary.
+
+## The event bridge (`.playwright/init-events.js`)
+
+Loaded as an `initScript` by `.playwright/cli.config.json` and by
+`e2e/support/fixtures.ts`, so an exploratory session and a committed
+spec see an identical page. It records every backend event by wrapping
+`window.wails.EventsNotify` — the single choke point all 46 events pass
+through, whether or not the app subscribes to them.
+
+```js
+window.__yjEvents.wait('LibraryScanComplete', { timeoutMs: 60000 })
+window.__yjEvents.names()          // name -> count; use this to find out
+                                   // what actually fired before asserting
+window.__yjEvents.last('QueueChanged')
+window.__yjEvents.since(seq)
+window.__yjEvents.reset()          // drop the buffer
+window.__yjEvents.ready(20000)     // resolves when a binding round-trips,
+                                   // which is later than DOM-ready and true
+window.__yjEvents.call('queue.Queue.GetState', [], 5000)
+```
+
+- **`wait` resolves against already-buffered events as well as future
+  ones**, so there is no race between doing the thing and listening.
+- **Install exactly one recorder.** Listeners survive across `eval`
+  calls; a second recorder double-counts. Call `reset()`, never
+  re-register.
+- **`call` times out on purpose.** A binding with wrong argument types
+  never fires its callback. A 5 s rejection naming `.dev/app.log` beats
+  an infinite hang.
+
+In specs, use the wrappers rather than `page.evaluate`:
+`waitForEvent`, `resetEvents`, `eventNames`, `callBinding`, and the
+`app` fixture (a page with the bridge installed and the backend
+actually answering) from `e2e/support/fixtures.ts`.
+
+## The control surface (`backend/testctl`, mounted at `/__test/`)
+
+Gated twice: behind the `dev` build tag (with a no-op `!dev` twin) and
+behind `YJ_TESTCTL=1`, which `scripts/dev-headless.sh` sets and
+`make dev` does not.
+
+| Endpoint | Use |
+|---|---|
+| `GET /__test/health` | is this a seeded dev build, and which library |
+| `POST /__test/db/snapshot?name=X` | save the SQLite state |
+| `POST /__test/db/restore?name=X` | put it back (see below) |
+| `POST /__test/emit` `{name, data}` | force any backend event |
+| `POST /__test/sql` `{sql, args}` | read rows, or a write count |
+
+`TestCtl` in `e2e/support/fixtures.ts` is the typed client.
+
+- **`emit` is the fast way to render a push-driven view** without
+  staging the work that would produce it — job progress, download
+  progress, scan progress. It calls `events.Deliver`, which *errors*
+  when the event reaches nobody, so a `200` means it really arrived.
+- **`restore` is slow** (~40 s in the suite) because it copies every
+  table. Prefer snapshotting once and restoring only when a spec
+  genuinely mutates state.
+
+## Traps in the config
+
+- **The two path keys in `.playwright/cli.config.json` resolve
+  differently.** `initScript` is relative to the *config file's*
+  directory (`"init-events.js"`, not `".playwright/init-events.js"`);
+  `outputDir` is relative to the *shell's cwd*. Set `outputDir` to
+  `".playwright-cli"` and run `playwright-cli` from the repo root, or
+  snapshots land somewhere neither `.gitignore` nor your next `ls`
+  will find, and you will read a stale one from a previous session
+  and think a component regressed.
+- **`snapshot` writes a file, it does not print the tree.** The
+  command prints a path under `outputDir`; read that. Only the tail
+  is echoed.
+- **Three separate browser caches.** `playwright-cli`, `@playwright/test`
+  (`make e2e-setup`) and the Vitest provider (`make ui-setup`) each
+  download their own Chromium. One working is no guarantee for the next.
+- **`getByRole('button', { name })` matches substrings.** "Play" also
+  matches "Add queue to playlist"; transport controls need
+  `exact: true`.
+- **`e2e/` is its own npm package** with `"type": "module"`. Without
+  that, Playwright transpiles the specs to CJS and every `import.meta`
+  throws — reported, unhelpfully, as "No tests found".

.pi/skills/yellowjacket-dev/references/schema-change.md

@@ -0,0 +1,52 @@
+# Changing the database schema
+
+The reasoning — why there are two files, what the old 48-step migration
+chain got wrong, and when squashing is legitimate — is in `CLAUDE.md`
+under *Backend packages → database*. Read it once. This is the
+checklist.
+
+A schema change needs **two** files, not one:
+
+1. **`backend/database/sql/schemas/*.sql`** — `CREATE TABLE ... IF NOT
+   EXISTS`, the literal target shape, what sqlc reads and what a fresh
+   install gets verbatim. Add the new column **last** in the
+   `CREATE TABLE`.
+2. **`backend/database/sql/migrations/NNNN_description.sql`** — the
+   `ALTER TABLE ... ADD COLUMN` (and any index on it) that gets an
+   existing database to the same shape. Schema files are a no-op against
+   a table that already exists, so without this an upgrade never gets
+   the column.
+
+Then:
+
+```bash
+make generate                                        # sqlc + templ
+go test -tags webkit2_41 ./backend/database/         # migration + column-order tests
+make test
+```
+
+Rebuild any seed you rely on (`make sandbox-seed NAME=default`) and
+delete your own dev `YJ_HOME` if you want to see the fresh-install path
+rather than the migrated one.
+
+## The three ways this goes wrong
+
+- **Column order must match between the two paths.** `ADD COLUMN`
+  always appends, so a migrated column declared anywhere but last in
+  `CREATE TABLE` leaves fresh and upgraded installs disagreeing on
+  order — and sqlc binds `SELECT *` positionally, so one of them
+  silently reads the wrong field.
+  `TestMigrations_ColumnOrderMatchesFreshInstall` is the regression test.
+- **Do not put an index on a migrated column in `sql/schemas/`.**
+  Schema files run *before* migrations, against a database that may not
+  have the column yet, and the predicate fails. Declare the index in the
+  migration, after the `ALTER TABLE`.
+- **Do not add a third description of the schema anywhere.** A
+  migration's `ADD COLUMN` failing with "duplicate column name" against
+  an already-current database is expected and tolerated, not an error to
+  route around.
+
+New queries go in `backend/database/sql/queries/`; generated Go lands in
+`backend/database/sql/sqlcgen/`, which is never edited by hand. Tests
+use `database.NewTestDB(t)`, built by the same `applySchema` production
+uses, so the two cannot diverge.

.pi/skills/yellowjacket-dev/references/ui-tier.md

@@ -0,0 +1,74 @@
+# The component and store tier (`make ui-test`)
+
+313 tests in a real Chromium in ~2 s with no Wails, no backend, no
+seeded library and no virtual display. This is the cheapest coverage
+available and where the bulk of UI regression belongs.
+
+```bash
+make ui-setup          # once: the Vitest provider's own Chromium
+make ui-test           # behaviour only
+make ui-watch
+make ui-visual         # + toMatchScreenshot baselines (YJ_VISUAL=1)
+make ui-visual-update  # re-record them
+make ui-test UI_ARGS='store/queue'   # filter
+```
+
+## How it works
+
+`frontend/wailsjs/` is a pure passthrough — every binding is
+`window.go[svc][Type][Method](args)`, every runtime call is
+`window.runtime.X(...)`. So `frontend/test/support/wails-fake.ts`
+replaces **those two globals and nothing else**, and the tests then
+exercise the *real* generated bindings and the *real* store code. No
+module mocking, and no second description of the Wails layer.
+
+```ts
+emit(Events.QueueChanged, payload);      // push a backend event
+stub('queue.Queue.GetState', state);     // a value, or a function of the args
+stubFailure('queue.Queue.SetQueue');     // reject, as a Go error does
+calls('queue.Queue.SetQueue');           // what the frontend called back with
+lastArgs('queue.Queue.SetQueue');
+const el = await fixture('now-playing'); // mount; shadow()/text() query it
+```
+
+The dispatcher mirrors wails' own `desktop/events.js`, including
+`maxCallbacks` expiry and the fact that a frontend `EventsEmit`
+notifies local listeners *before* Go.
+
+## Four things that will cost you time
+
+- **Store singletons are constructed at module import**, before any test
+  can stub. `test/setup.ts` therefore carries import-time defaults for
+  the stores that read config in their constructor. Without one, a store
+  caches `undefined` where Go would have sent `[]`, and components crash
+  on `.length` — which reads exactly like a component bug and is not.
+  Adding a store that reads config on construction means adding its
+  default there.
+- **`vitest.config.mts`, not `.ts`** — it `mergeConfig`s the repo's
+  `vite.config.mts` to reuse the `@go`/`@store`/`@components` aliases,
+  and a `.ts` sibling cannot import it.
+- **Screenshots need the theme.** The setup file imports
+  `@store/theme-store` for its side effect (it applies the `--yj-*`
+  ramp to `:root`); without it a component renders white-on-white and
+  the baseline is blank.
+- **`@lit-labs/virtualizer` never produces two identical frames**, so
+  `toMatchScreenshot` on `<queue-panel>` fails with "could not capture a
+  stable screenshot" rather than a diff. Assert on its rows instead.
+
+Visual baselines are font-hinting and compositing sensitive, which is
+why they are opt-in: they only mean anything on the machine that
+recorded them.
+
+## Bindings
+
+`frontend/wailsjs/` is generated by `wails`, **not** by `go generate`,
+so the pre-commit codegen check does not cover it — a renamed Go bound
+method first shows up at runtime, as a call that never settles.
+
+```bash
+make bindings-check   # ~1.5 s, also a pre-commit hook
+make bindings         # regenerate for real
+```
+
+The generator rewrites `wailsjs/runtime/*` as mode 755 every run; that
+is churn, not drift, and the check ignores it.