Merge remote-tracking branch 'origin/main' into add-hachidori-backend

# Conflicts:
#	launcher/main.test.ts
#	src/cli/help.test.ts
#	src/core/services/__tests__/stats-server.test.ts
#	src/core/services/cli-command.test.ts
#	src/core/services/tokenizer/yomitan-parser-runtime.test.ts
#	src/main/overlay-runtime.test.ts
#	src/main/runtime/character-dictionary-auto-sync.test.ts
#	src/main/runtime/cli-command-context-deps.test.ts
#	src/main/runtime/cli-command-context-factory.test.ts
#	src/main/runtime/cli-command-context-main-deps.test.ts
#	src/main/runtime/composers/cli-startup-composer.test.ts
#	src/main/runtime/stats-server-runtime.test.ts
#	src/main/runtime/tray-main-actions.test.ts
#	src/main/runtime/tray-main-deps.test.ts
#	src/main/runtime/tray-runtime-handlers.test.ts
#	src/main/runtime/tray-runtime.test.ts
#	src/main/runtime/yomitan-anki-server-sync.test.ts
#	src/preload.ts
#	src/renderer/handlers/mouse.test.ts
#	src/renderer/yomitan-popup.test.ts

docs/knowledge-base/catalog.md

@@ -21,6 +21,7 @@ Read when: finding internal docs or checking verification status
 | Planning guide | `docs/workflow/planning.md` | active | 2026-05-23 | lightweight vs execution plans |
 | Agent skills | `docs/workflow/agent-skills.md` | active | 2026-08-23 | repo-local workflow skill ownership |
 | Verification guide | `docs/workflow/verification.md` | active | 2026-08-13 | maintained verification lanes |
+| Testing guidelines | `docs/workflow/testing.md` | active | 2026-10-04 | test style and anti-patterns |
 | Release guide | `docs/RELEASING.md` | active | 2026-05-23 | release checklist |
 
 ## Update Rules

docs/workflow/README.md

@@ -13,6 +13,7 @@ This section is the internal workflow map for contributors and agents.
 
 - [Planning](./planning.md) - when to write a lightweight plan vs a full execution plan
 - [Verification](./verification.md) - maintained test/build lanes and handoff gate
+- [Testing](./testing.md) - what a good test looks like and what not to write
 - [Agent Skills](./agent-skills.md) - repo-local workflow skill ownership
 - [Release Guide](../RELEASING.md) - tagged release workflow
 

docs/workflow/testing.md

@@ -0,0 +1,49 @@
+<!-- read_when: writing, reviewing, or deleting tests -->
+
+# Testing Guidelines
+
+Status: active  
+Last verified: 2026-10-04  
+Owner: Kyle Yasuda  
+Read when: adding or changing tests
+
+Which lanes to run lives in [Verification](./verification.md). This page covers what a
+good test looks like here.
+
+## Test Behavior, Not Wiring
+
+- Exercise a module through its public interface and assert outcomes: return values,
+  resulting state, files written, rows in sqlite, messages sent to a fake process.
+- Prefer real collaborators that are cheap: tmp dirs, in-memory or tmp sqlite, fake
+  executables, pure parsers. Fake only the edges (Electron, mpv socket, network).
+- Assert call order only when order is the behavior (startup sequencing, ABA races),
+  and then assert relative order, not the whole call log.
+
+## Do Not Write
+
+- Pass-through tests: a builder or handler that only forwards deps (`*-main-deps.ts`,
+  `*-runtime-handlers.ts`) needs no test. TypeScript already checks the shape.
+- Source-text tests: reading `.ts`, `.css`, `.html`, `.lua`, `.swift`, or workflow YAML
+  and asserting with regexes. If the invariant matters, extract the logic and run it
+  (see `src/preload-ipc-listeners.ts`). Policy lints over workflow YAML are the
+  exception and belong in one parsed-YAML check.
+- "Stays deleted" tests for removed modules, flags, or selectors. `tsc` and review
+  catch reintroduction.
+- Tests that restate constants, defaults, labels, or window options.
+- The same rule at several layers. Test a rule once where it lives; keep one
+  end-to-end case (for the tokenizer, the golden corpus) for integration.
+
+## Keep Tests Small
+
+- Shared setup goes in a `makeDeps(overrides)` helper or a `*-test-harness.ts` file, not
+  pasted into every test.
+- Near-identical cases become a table: `for (const c of cases) test(c.name, ...)`.
+- Inject timers, clocks, and loggers instead of patching globals or private members.
+- A bug fix gets a regression test for the behavior that broke, named after the
+  behavior, not the ticket.
+
+## Known Debt
+
+- `src/main/main-wiring.test.ts` and `src/renderer/renderer-init-order.test.ts` still
+  regex `main.ts` / `renderer.ts` to guard startup ordering. Replace each test with a
+  behavioral one as the logic moves out of `main.ts` closures.

docs/workflow/verification.md

@@ -14,8 +14,9 @@ Read when: selecting the right verification lane for a change
   files in `package.json`.
 - `scripts/run-test-lane.mjs` runs each test file in its own `bun test` process
   (per-file isolation with a wall timeout) so a hanging test or leaked global in
-  one file cannot cascade into the rest of the lane. `--jobs N` parallelizes;
-  `--single-process` restores the shared-process mode for debugging.
+  one file cannot cascade into the rest of the lane. Files run in parallel, one
+  worker per CPU by default; `--jobs 1` runs serially and `--single-process`
+  restores the shared-process mode for debugging.
 - `bun run test:fast` is the full source gate: discovered `src/**`, launcher
   unit, and `scripts/**`.
 - `.github/workflows/quality-gate.yml` is the reusable `workflow_call` gate for
@@ -71,7 +72,7 @@ bun run docs:build
 
 - `bun run test:coverage:src` runs the same discovered `bun-src-full` membership as
   `test:src` through a sharded coverage runner: one Bun coverage process per test
-  file, then merged LCOV output.
+  file (parallel, one per CPU unless `--jobs N`), then merged LCOV output.
 - A failing coverage shard stops the runner with a nonzero status. Coverage is a
   source test gate, not a report-only step.
 - Machine-readable output lands at `coverage/test-src/lcov.info`.