groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-electron-engineer/references/performance-and-reliability.md

@@ -0,0 +1,80 @@
+# Performance & Reliability
+
+## Table of Contents
+- [Where a Desktop App Spends Its Budget](#where-a-desktop-app-spends-its-budget)
+- [The Main Process Is Never Blocked](#the-main-process-is-never-blocked)
+- [Renderer Performance Is Web Performance](#renderer-performance-is-web-performance)
+- [IPC Efficiency](#ipc-efficiency)
+- [Memory Across Long-Lived Windows](#memory-across-long-lived-windows)
+- [Cold Boot](#cold-boot)
+- [Reliability of the IPC Layer](#reliability-of-the-ipc-layer)
+- [A Backend That Is Unreachable](#a-backend-that-is-unreachable)
+- [What Lives in the Core, Not Here](#what-lives-in-the-core-not-here)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## Where a Desktop App Spends Its Budget
+
+Performance is a budget spent deliberately, allocated top-down and measured at the tail, not the average (`docs/principles/quality/performance.md`). A desktop shell spends it across three surfaces with different failure modes: the **main process**, where blocking work freezes every window at once; the **renderer**, which is a web app and pays the web's bundle and frame costs; and the **bridge** between them, where a chatty IPC pattern turns a cheap call into a per-frame tax. The process boundaries that contain these costs are the process-model's subject (`references/process-model.md`); this is the performance and reliability lens on them.
+
+## The Main Process Is Never Blocked
+
+One main process serves every window. A synchronous parse, hash, or file walk on it freezes all of them simultaneously — there is no per-window isolation to fall back on (`references/process-model.md`). The test for any main-process code is the one the process model states: **can this take longer than a frame?** Reading a config file or registering a handler — no, main is fine. Parsing a large file, indexing, image work — yes, and it goes to a `utilityProcess` with its ports wired renderer↔utility directly so the heavy traffic never transits or blocks main (`references/process-model.md`).
+
+`sendSync` over IPC is forbidden for the same reason from the other side: it blocks the renderer's event loop for the full round trip (`references/ipc-contracts.md`). Every privileged call is an async `invoke`.
+
+## Renderer Performance Is Web Performance
+
+The renderer is a normal Vite + React app, so the web stack's performance discipline applies unchanged: lazy-load routes and heavy components behind code-split boundaries, keep the bundle lean, and gate deterministic budgets — bundle size, not noisy wall-clock — in CI (`docs/principles/quality/performance.md`). Two desktop-specific notes:
+
+- **The bundle is local, but it is not free.** It loads from the bundle protocol rather than a network, so transfer cost is near zero — but parse and execute cost is not, and a bloated main chunk still slows cold boot. Code-split anyway.
+- **One window is one renderer.** A second window (settings, about) is a second renderer with its own bundle and memory; share chunks through the build, and do not spawn windows the app does not need.
+
+## IPC Efficiency
+
+The bridge is a serialization boundary: every `invoke` structured-clones its arguments and result across the process line. That cost is invisible per call and ruinous in a loop. Two rules keep it cheap:
+
+- **Never call the bridge in a hot loop.** A per-row or per-frame `invoke` pays the clone cost every iteration. Fetch the collection in one call and iterate in the renderer.
+- **Batch and coarsen the contract.** Design channels around the renderer's actual unit of work — `items:list` returning a page, not `item:get` called N times. A coarse channel is one clone; a chatty one is N (`references/ipc-contracts.md`).
+
+Push channels (main → renderer) carry coarse events too: a file-watcher that fires per-keystroke should coalesce before it `webContents.send`s, so the renderer invalidates once, not a hundred times (`references/ipc-contracts.md`).
+
+## Memory Across Long-Lived Windows
+
+A desktop window lives for hours or days, so a leak that a page reload would have swept never gets swept. The discipline is lifecycle hygiene at the boundaries:
+
+- **Every subscription returns its unsubscribe, and the renderer calls it.** A bridge push subscription returns a remover; an effect that registers one must return it for cleanup, or the listener and its closure outlive the component (`references/ipc-contracts.md`).
+- **Bound caches.** TanStack Query's cache is bounded by its garbage-collection time; an ad-hoc `Map` accumulating per-result entries is not — it is the unbounded queue the performance canon rejects, in client form.
+- **Tear down `utilityProcess` workers** when their work is done. A spawned worker that is never killed is retained memory and a retained handle.
+
+## Cold Boot
+
+Time-to-first-window is the desktop app's first impression. Keep main's startup to the four things it must do — register the protocol, apply the security policy, register handlers, create the window — and defer everything else until after the window is visible (`references/process-model.md`). Show the window with a skeleton and let data arrive into it over IPC; do not block window creation on a gateway call or a heavy index. Build the index in a `utilityProcess` after the first frame, not before it.
+
+## Reliability of the IPC Layer
+
+Reliability is designed in, not hoped for, and for the renderer the IPC seam is the dependency that fails (`docs/principles/quality/reliability.md`). TanStack Query is the renderer's resilience layer over that seam, exactly as it would be over HTTP: its `queryFn`s call the typed bridge, and its caching, retry, and invalidation give the renderer bounded retries with backoff and a served-from-cache fallback for free (`references/ipc-contracts.md`). Configure retry to back off and to retry only transient failures — a rejected privileged call from a validation failure is a bug or an attack, not a state to retry into (`references/ipc-contracts.md`). A failed `invoke` rejects the query, and the component renders that error state rather than letting the rejection escape.
+
+## A Backend That Is Unreachable
+
+When the workspace has a hosted core, main holds the HTTP client and the renderer reaches the gateway only through main (`references/ipc-contracts.md`). That places the gateway's reliability in main, and the discipline is the one the resilience patterns describe at any client edge:
+
+- **Timeout and bounded retry on main's HTTP client.** Every outbound call to the gateway has a timeout and a jittered, bounded retry for transient failures — a hung gateway connection otherwise stalls the IPC call that is waiting on it.
+- **Map unreachable to a domain result.** Main returns a typed "unreachable" result the renderer can render, not a raw thrown error — the gateway being down is an expected state with a designed UI, decided at design time alongside the happy path (`docs/principles/quality/reliability.md`).
+- **Degrade, do not blank.** A feature whose gateway data is unavailable serves cached data or an explicit unavailable state while the rest of the app works; the window stays usable when one capability is down.
+
+## What Lives in the Core, Not Here
+
+Server reliability patterns belong to the capability core and its services, not the desktop shell (`docs/principles/quality/reliability.md`). **SLOs and error budgets** are defined and measured server-side. **Load shedding** protects the server from overload regardless of how clients behave — a backstop the server owns, not something a client implements for it. **Server-side circuit breakers** are earned against slow downstreams and tuned against real traffic in the core. The client's share is the right amount of resilience at the edge: timeout, bounded retry, a cache fallback, and a designed degraded state. The business rules about a failure — recoverability, retry budget, what a result means — are proven in the core, and the renderer renders the result.
+
+## Anti-Patterns
+
+- **Blocking the main process.** A synchronous parse or hash freezes every window — `utilityProcess` it.
+- **`sendSync`.** Blocks the renderer event loop for the round trip; always async.
+- **IPC in a hot loop.** Per-row or per-frame `invoke` pays the clone cost every iteration — fetch once, iterate locally.
+- **Chatty fine-grained channels.** N calls where one coarse channel would do; design channels around the renderer's unit of work.
+- **Leaked subscriptions.** A push listener registered without its unsubscribe outlives the component across a multi-day session.
+- **Unbounded ad-hoc caches.** A `Map` that only grows is the latency bomb in client form; let TanStack Query bound it.
+- **Blank on unreachable.** No designed state for a down gateway ships a frozen or empty window.
+- **Reimplementing server reliability in the shell.** Load shedding, SLOs, and reflexive circuit breakers live in the core.

package/src/engineer-skills/groundwork-electron-engineer/references/process-model.md

@@ -0,0 +1,94 @@
+# Process Model
+
+## Table of Contents
+- [The Three Processes](#the-three-processes)
+- [Main Is an Orchestrator](#main-is-an-orchestrator)
+- [The Enforced Folder Boundary](#the-enforced-folder-boundary)
+- [Per-Process Compiler Contexts](#per-process-compiler-contexts)
+- [utilityProcess for Heavy Work](#utilityprocess-for-heavy-work)
+- [Shared Code Crosses as Types Only](#shared-code-crosses-as-types-only)
+- [Adding a Window](#adding-a-window)
+
+---
+
+## The Three Processes
+
+| Process | Runs | May import | Job |
+|---|---|---|---|
+| **main** (`src/main/`) | Node + Electron main APIs | anything | Orchestration: windows, security policy, IPC handlers, OS integration |
+| **preload** (`src/preload/`) | sandboxed bridge context | `electron` (bridge subset) + shared types | Expose the narrow `window.api`; nothing else |
+| **renderer** (`src/renderer/`) | Chromium, sandboxed, Node-free | web code + shared types | The UI — a normal Vite + React web app |
+
+`src/shared/` is not a process: it is the contract-type module all three import (types only — see below).
+
+This is the VS Code / Slack / Signal shape. It exists because a renderer with Node access turns any XSS into machine compromise, and a busy main process freezes every window at once.
+
+## Main Is an Orchestrator
+
+`src/main/index.ts` does four things: registers the bundle protocol, applies the security policy, registers IPC handlers, creates windows. Everything else is delegation.
+
+The test for new main-process code: **can this take longer than a frame?** Parsing a large file, hashing, indexing, image work — yes, so it goes to a `utilityProcess`. Reading a config file, showing a dialog, registering a handler — no, main is fine.
+
+Keep main's modules pure where possible: `src/main/policy.ts` holds the security rules with **no Electron imports**, which is why `policy.test.ts` runs in plain Node. When adding privileged logic, split it the same way — decision (pure module, unit-tested) from wiring (thin Electron glue in `index.ts`/`ipc.ts`).
+
+## The Enforced Folder Boundary
+
+```
+src/
+  main/      # privileged orchestration
+  preload/   # the bridge — contextBridge only
+  renderer/  # the web app — no Node, no Electron
+  shared/    # IPC contract types — types only
+```
+
+The split is physical and lint-enforced (the Slack pattern): `eslint.config.mjs` carries `no-restricted-imports` blocks that fail the build when `src/renderer/` or `src/shared/` imports `electron` or a Node built-in. The rule exists because the boundary erodes one convenient import at a time, and each erosion is invisible until it is a sandbox hole.
+
+Never suppress the rule. If the renderer "needs" a Node capability, that is a new IPC channel (`references/ipc-contracts.md`), not an exemption.
+
+## Per-Process Compiler Contexts
+
+Two tsconfigs police the boundary alongside the lint:
+
+- `tsconfig.node.json` — main, preload, shared, configs, smoke tests. `types: ["node"]`, **no DOM lib**.
+- `tsconfig.web.json` — renderer + shared. DOM lib, `jsx: react-jsx`, **no Node types**.
+
+`npm run typecheck` (the `typecheck` Nx target) runs both. A renderer file that touches `process` or a main file that touches `document` is a compile error, not a code-review catch. When adding files, make sure they land in the right include set — a file checked by neither tsconfig is unverified code.
+
+## utilityProcess for Heavy Work
+
+`utilityProcess` is the documented home for CPU-intensive tasks, untrusted services, and crash-prone components — a `child_process.fork` equivalent launched through Chromium's Services API, with Node enabled and MessagePort support.
+
+The pattern (VS Code's extension host is the reference):
+
+```ts
+// main: spawn and wire ports renderer↔utility DIRECTLY
+import { utilityProcess, MessageChannelMain } from 'electron';
+
+const worker = utilityProcess.fork(
+  new URL('./indexer.js?modulePath', import.meta.url).pathname,
+);
+const { port1, port2 } = new MessageChannelMain();
+worker.postMessage({ type: 'port' }, [port1]);
+window.webContents.postMessage('indexer:port', null, [port2]);
+```
+
+The direct port wiring matters: heavy traffic never transits — or blocks — main. electron-vite builds utility workers first-class via the `?modulePath` import suffix.
+
+Use `utilityProcess`, not `child_process.fork`, for anything that talks to a renderer: fork has no port wiring and no Services API integration. Plugin-style or untrusted code never runs in the renderer — a utility process contains its crash or compromise.
+
+## Shared Code Crosses as Types Only
+
+`src/shared/ipc.ts` carries the channel map and payload types both sides import. It must contain **no runtime behaviour** — a "utils" module imported by main and renderer drags Node-flavoured code toward the sandbox and couples both sides' upgrade paths. The lint boundary enforces the import side; review enforces the no-runtime side: if a shared file gains a function body that does more than type-level work, move it.
+
+Constants are the one nuance: a string-literal channel name in the contract type is fine; a shared object of behaviourful helpers is not.
+
+## Adding a Window
+
+Every window — main, settings, about, anything — gets the identical hardened construction:
+
+1. Build it in `src/main/index.ts` (or a sibling module main imports) with the full `webPreferences` quartet and the shared preload.
+2. Load content only from the bundle protocol or the dev server; never a remote URL, never `file://`.
+3. The global policy (`applySecurityPolicy`) already covers it — permission denial and navigation restriction hook `web-contents-created`, so they apply to new windows automatically. Do not bypass that path with per-window overrides.
+4. If the window needs new capabilities, they arrive as IPC channels, not as loosened `webPreferences`.
+
+A second renderer entry point goes in `electron.vite.config.ts`'s renderer `rollupOptions.input` map, with its own HTML file carrying the same CSP.

package/src/engineer-skills/groundwork-electron-engineer/references/security.md

@@ -0,0 +1,107 @@
+# Security
+
+## Table of Contents
+- [The Posture](#the-posture)
+- [The Hardened Quartet](#the-hardened-quartet)
+- [Permissions: Denied by Default](#permissions-denied-by-default)
+- [Navigation and window.open](#navigation-and-windowopen)
+- [shell.openExternal Allowlist](#shellopenexternal-allowlist)
+- [The Custom Protocol](#the-custom-protocol)
+- [Content-Security-Policy](#content-security-policy)
+- [Fuses](#fuses)
+- [The Currency Window](#the-currency-window)
+- [Security Review Checklist](#security-review-checklist)
+
+---
+
+## The Posture
+
+An Electron app is a browser with a privileged process attached: every web vulnerability becomes a local-machine vulnerability the moment a boundary control is loosened. The generated app ships with the full baseline **enforced in code** — `src/main/index.ts` (wiring), `src/main/policy.ts` (rules, pure and unit-tested), `forge.config.ts` (fuses). This reference explains each control so changes preserve it; the canonical statement is `docs/principles/stack/electron/security.md`.
+
+The controls fail **as a set**: enabling `nodeIntegration` silently disables the sandbox for that renderer. There is no safe partial loosening.
+
+## The Hardened Quartet
+
+```ts
+webPreferences: {
+  contextIsolation: true,   // never off
+  sandbox: true,            // never off
+  nodeIntegration: false,   // never on
+  webSecurity: true,        // never off — not even "temporarily for dev"
+},
+```
+
+These are Electron's own defaults, restated explicitly so no upgrade, flag, or debugging session changes them silently. They apply to **every** window (`references/process-model.md` → Adding a Window). The framework's generation tests assert the generated main never contains a loosened value — treat the same assertion as a review rule for hand-written changes.
+
+`webSecurity: false` and `allowRunningInsecureContent` as debugging crutches are how production apps ship with the front door open. Fix the content.
+
+## Permissions: Denied by Default
+
+```ts
+session.defaultSession.setPermissionRequestHandler((_wc, _permission, callback) => {
+  callback(false);
+});
+```
+
+Electron's default **grants** permissions (camera, microphone, geolocation) to any content that asks; in a desktop app, content that asks unexpectedly is the attack. Granting a permission is a product decision: extend the handler with an explicit `permission === '...'` allowlist and a comment recording why — never remove the handler.
+
+## Navigation and window.open
+
+Two hooks in `applySecurityPolicy`, registered on `web-contents-created` so they cover every window automatically:
+
+- **`will-navigate`** blocks navigation unless `isTrustedNavigationTarget` allows it — the bundle protocol always, the dev-server origin only while developing. A renderer that can reach an attacker's page hands the attacker a privileged-adjacent context.
+- **`setWindowOpenHandler`** returns `{ action: 'deny' }` unconditionally; allowlisted https links are handed to `shell.openExternal` (the OS browser) instead of becoming Electron windows.
+
+New in-app routes need no changes (the SPA never navigates the top frame). A legitimate new navigation target (e.g. an OAuth window) is a change to `policy.ts` with a test in `policy.test.ts`, not an inline exemption.
+
+## shell.openExternal Allowlist
+
+`shell.openExternal` launches whatever the OS associates with the input — `file:`, `smb:`, custom scheme handlers, anything. It is therefore only ever called on URLs that pass `isAllowedExternalUrl` (https-only baseline). Widening the allowlist is a recorded decision in `policy.ts` + test, per scheme, never a pass-through. The renderer can request it through the validated `shell:open-external` channel; it cannot reach `shell` any other way.
+
+## The Custom Protocol
+
+Packaged app content is served over `app://` (`registerBundleProtocol`), never `file://` — `file://` grants origin-level access to the filesystem namespace and breaks standard web security semantics. The handler resolves requests against the built renderer directory and rejects anything failing the `isContainedPath` traversal check.
+
+In dev, electron-vite serves the renderer over `ELECTRON_RENDERER_URL`; the policy treats that origin as trusted only when the env var exists (i.e. never in a packaged build).
+
+## Content-Security-Policy
+
+`src/renderer/index.html` ships a strict CSP via `<meta http-equiv>` (the right mechanism for custom-protocol content):
+
+```
+default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:
+```
+
+This strictness is achievable because **all privileged data flows over IPC, not fetch** — the renderer has no business calling the network. Keep it that way: a feature that "needs" `connect-src` should route through main (`references/ipc-contracts.md` → Core Access). A CSP containing `*` is no CSP. `style-src 'unsafe-inline'` carries Vite's dev-mode style injection; scripts stay `'self'`-only in every mode.
+
+## Fuses
+
+Fuses are build-time switches baked into the binary — runtime config cannot re-enable what a fuse removed. They are flipped inside the Forge packaging step (`forge.config.ts`), so an unfused binary cannot reach a release channel:
+
+| Fuse | Setting | Why |
+|---|---|---|
+| `RunAsNode` | **off** | The shipped binary must not double as a general-purpose Node executable |
+| `EnableNodeOptionsEnvironmentVariable` | **off** | Blocks `NODE_OPTIONS` injection |
+| `EnableCookieEncryption` | **on** | At-rest cookie protection |
+| `EnableEmbeddedAsarIntegrityValidation` | **on** | CVE-2025-55305: heap-snapshot tampering backdoored Signal/Slack/1Password past code-integrity checks; ASAR integrity is the fix |
+| `OnlyLoadAppFromAsar` | **on** | Companion to integrity validation — no side-loaded app directory |
+| `nodeCliInspect` | **on, deliberately** | Flipping it off breaks Playwright's `_electron` launch; the agent-closable smoke loop outranks the marginal hardening |
+
+Post-CVE-2025-55305, shipping without ASAR integrity is called out as a defect, not a hardening opportunity. Do not move fuse flipping out of the packaging pipeline into a checklist.
+
+## The Currency Window
+
+Only the latest **three** Electron majors receive security patches, and a new major ships every 8 weeks — Chromium CVEs land in the shipped app on Chromium's schedule, not the team's. An app more than three majors behind is running known-exploitable browser bugs. Treat the upgrade as scheduled work with dependency-CVE priority; verify the Playwright driver pairing in CI when bumping (driver/Electron launch regressions have happened — e.g. the 36.x launch failure fixed in 37).
+
+## Security Review Checklist
+
+For any PR touching `src/main/`, `src/preload/`, `forge.config.ts`, or `index.html`:
+
+- [ ] Quartet untouched in every `BrowserWindow`
+- [ ] No new `ipcMain.handle` without sender validation; zod on non-trivial payloads
+- [ ] Preload still exposes only purpose-named methods — no `ipcRenderer`, no generic passthrough
+- [ ] Navigation/permission/external-URL changes live in `policy.ts` with tests
+- [ ] CSP not weakened; no new `connect-src`
+- [ ] Content still served over `app://`
+- [ ] Fuse config unchanged (or the change is a recorded decision)
+- [ ] No renderer/shared import of Electron or Node (lint must stay green without suppressions)

package/src/engineer-skills/groundwork-electron-engineer/references/testing-and-smoke.md

@@ -0,0 +1,129 @@
+# Testing & Smoke
+
+## Table of Contents
+- [The Three Tiers](#the-three-tiers)
+- [Unit: Node Project (Main Policy)](#unit-node-project-main-policy)
+- [Unit: Renderer Project (Fake the Bridge)](#unit-renderer-project-fake-the-bridge)
+- [The Playwright _electron Smoke](#the-playwright-_electron-smoke)
+- [_electron Patterns](#_electron-patterns)
+- [CI: xvfb and Skip-with-Reason](#ci-xvfb-and-skip-with-reason)
+- [Keeping the Smoke Thin](#keeping-the-smoke-thin)
+- [Test Commands](#test-commands)
+
+---
+
+## The Three Tiers
+
+| Tier | Tool | Environment | Proves |
+|---|---|---|---|
+| Unit (main) | vitest, `main` project | plain Node | The pure security/policy rules |
+| Unit (renderer) | vitest, `renderer` project | jsdom, bridge faked | Components against the bridge contract |
+| Smoke (boot) | Playwright `_electron` | the real built app | Boot, rendering, IPC wiring, theme push |
+
+This maps onto the multi-surface verification contract: generation (snapshot, framework-side), compilation (`tsc` + lint), boot (the smoke). Business rules are **not** on this list — they are proven once at the capability core's contract; surface tests assert wiring and rendering only.
+
+These tiers are the Electron idiom of the framework testing canon (`docs/principles/foundations/testing.md`): the renderer and main unit tests are the fat middle the canon's honeycomb puts the weight on, and the boot smoke is the thin top — a fat smoke is the fat-integration-suite antipattern wearing a desktop coat. When this file and the canon disagree, the canon wins and this file is the one to fix.
+
+`vitest.config.ts` defines the two unit projects with per-process environments. Test placement follows the process split: `src/main/**/*.test.ts` runs in Node, `src/renderer/**/*.test.tsx` runs in jsdom. A test that needs the wrong environment is in the wrong process.
+
+## Unit: Node Project (Main Policy)
+
+Main's testable logic lives in pure modules (`policy.ts` — no Electron imports), so it runs in plain Node with zero mocking:
+
+```ts
+it.each(['http://example.com', 'file:///etc/passwd', 'javascript:alert(1)'])(
+  'rejects %s', (url) => expect(isAllowedExternalUrl(url)).toBe(false),
+);
+```
+
+When adding privileged logic, keep this shape: decision in a pure module + test; wiring in the thin Electron glue, proven by the smoke. Do not import `electron` in a vitest file — in plain Node the module resolves to the binary path string, not the API, and mocking the whole surface buys nothing the pure-module split doesn't buy better.
+
+## Unit: Renderer Project (Fake the Bridge)
+
+The renderer's platform surface is `window.api`, so tests fake exactly that seam:
+
+```tsx
+const fakeApi: RendererApi = {
+  getStatus: async () => ({ status: 'ok', version: '0.1.0-test', platform: 'test' }),
+  openExternal: async () => ({ opened: false }),
+  onThemeChanged: () => () => undefined,
+};
+beforeEach(() => {
+  Object.defineProperty(window, 'api', { value: fakeApi, configurable: true });
+});
+```
+
+Typing the fake as `RendererApi` keeps it honest: a contract change breaks the fake at compile time. Async UI rule: query-backed components render their pending state first — `await screen.findByText(...)` past it; asserting on the container immediately races the resolution.
+
+Everything else about component testing — Testing Library idiom, what to assert, accessibility queries — is the web stack's, unchanged: `groundwork-nextjs-engineer/references/testing.md`.
+
+## The Playwright _electron Smoke
+
+Playwright's Electron support is officially "experimental" but is the de-facto standard (VS Code tests with it); it is the reason GroundWork picked this stack — the strongest agent-closable loop of any desktop option. The driver needs **no browser downloads** (`playwright install` is unnecessary): it launches the app's own Electron binary.
+
+The generated smoke (`tests/smoke/app.spec.ts`) is the canonical shape: launch the **built** app, first window, title + rendered heading, one IPC round-trip, the theme push channel, one main-process assertion.
+
+## _electron Patterns
+
+```ts
+import { _electron as electron } from 'playwright';
+
+const app = await electron.launch({ args: ['out/main/index.js'] });
+const page = await app.firstWindow();          // a normal Playwright Page
+```
+
+- **Renderer assertions** — everything Playwright can do to a web page: `expect(page).toHaveTitle(...)`, `getByRole`, `getByTestId`, screenshots.
+- **Bridge round-trips** — `page.evaluate(() => globalThis.api.foo())` exercises preload + sender validation + handler end-to-end. (Cast `globalThis`; the smoke compiles under the node tsconfig, which has no DOM types.)
+- **Main-process assertions** — `app.evaluate(({ app, nativeTheme }) => ...)` runs **inside main** with the electron module injected: assert on windows, theme state, app metadata. This hook is unique to Electron among desktop options.
+- **Push-channel proof** — assert the DOM consequence, e.g. `toHaveAttribute('data-theme', /^(light|dark)$/)` after main's initial broadcast.
+- **Always `await app.close()`** in a `finally` — a leaked Electron process wedges CI workers.
+- Launching a **packaged** binary instead of the dev build: `electron.launch({ executablePath })` — worth one lane before releases; the day-to-day smoke uses the built output for speed.
+- Driver/runtime pairings can regress across Electron majors (the 36.x `Process failed to launch!` Linux regression, fixed in 37) — when a major bump breaks launch, check the pairing before debugging the app.
+
+## CI: xvfb and Skip-with-Reason
+
+Electron is never truly headless — Linux CI needs a display server. The `smoke` target routes through `tool/electron_exec.sh`, which:
+
+1. Verifies `node_modules` and the Electron binary exist (bootstrap state) — else **"tier skipped"** with the bootstrap command.
+2. On Linux with no `DISPLAY`/`WAYLAND_DISPLAY`: wraps the run in `xvfb-run --auto-servernum` when available — else **"smoke tier skipped"** naming xvfb.
+3. Builds, then runs `playwright test`.
+
+The contract is *skipped-with-reason, never silently green*: a missing toolchain degrades exactly the way a missing Docker daemon degrades `./dev`. CI installs `xvfb` to run the lane for real; macOS/Windows runners and desktop sessions need no wrapper. Artifacts on failure (screenshot, trace) are configured in `playwright.config.ts`.
+
+## Keeping the Smoke Thin
+
+Boot minutes are this stack's expensive test currency. The smoke proves the app **boots and is wired** — it is not an E2E suite:
+
+- One spec, happy path, serial (`workers: 1`).
+- New IPC channels get unit tests (policy + renderer fake) by default; extend the smoke only when a channel's *wiring* is novel (new push mechanism, new window).
+- Feature behaviour belongs in renderer unit tests; business rules belong at the core's contract. A fat smoke is the fat-integration-suite antipattern wearing a desktop coat.
+
+## Mutation Testing — the assertion-quality read-out
+
+The main-process policy modules (`policy.ts` — URL allow-listing, sender validation, IPC guards) are dense security logic, exactly where a covered-but-unasserted line is a real risk. **StrykerJS** is the read-out that proves those tests bite: it mutates the rule and confirms a test fails. Treat it as a **signal, never a gate**, run it incrementally on changed code (`stryker run --incremental`), and point it at the pure policy modules first — a surviving mutant on a security rule is the missing assertion to add. The renderer's pure logic earns the same spot check; the Electron glue and the smoke do not (they prove wiring, not branches).
+
+## Generate the Inputs You Can't Enumerate
+
+The same pure policy modules are the prime target for property-based testing (canon principle 7). A hand-written `it.each` list of malicious URLs checks the cases you thought of; an allow-list rule that ingests untrusted strings is exactly where the dangerous input is the one you didn't enumerate. Drive `isAllowedExternalUrl` and sender-validation guards with **`fast-check`** generators — arbitrary URLs, schemes, and host shapes — and assert the security invariant holds (`file:`/`javascript:`/credential-bearing URLs always rejected; only the allow-listed origins pass). One property closes a class of bypass the example list never reaches. The renderer's pure logic earns the same treatment; the Electron glue and the boot smoke do not — they prove wiring, not branches. Service-boundary tools (Schemathesis, coverage-guided fuzzing) belong at the capability core's contract, not the desktop shell.
+
+## Naming Tests by Behaviour
+
+A policy test name must state the rule and the condition from the failure log alone — `rejects file:// URLs` and `rejects credential-bearing hosts`, not `policy test 3`. The generated `it.each('rejects %s', ...)` shape already encodes this; keep it. Renderer component naming follows the web stack idiom (`groundwork-nextjs-engineer/references/testing.md`), unchanged.
+
+## Test Commands
+
+```bash
+npx nx run <app>:test        # both vitest projects (node + jsdom)
+npx nx run <app>:test -- --project renderer   # one project
+npx nx run <app>:smoke       # build + Playwright _electron (display-guarded)
+npx nx run <app>:typecheck   # tsc, both process tsconfigs
+npx nx run <app>:lint        # eslint incl. process-boundary rules
+```
+
+## Bet Slice Rollout — the permanent tests a slice owes
+
+When a bet slice's progress tests go green, the slice rolls out permanent coverage before it closes (bet workflow, Delivery). The bet-progress tests prove the capability once and are archived; these stay. Test placement follows the process split, and surface tests assert wiring and rendering only — never a business rule the capability core already owns.
+
+- **Main policy unit tests (when the slice added privileged logic).** Every new security or policy decision the slice introduced gets a pure-module test in the `main` project, with the rejection cases exercised, not just the allow case — this is the densest risk surface in the stack.
+- **Renderer unit tests (when the slice added a component or state).** Components the slice introduced with conditional rendering, async pending states, or error handling get jsdom tests against the faked `window.api` bridge; the typed fake keeps the bridge contract honest.
+- **Smoke extension (only when wiring is novel).** A new IPC channel gets unit tests by default; extend the boot smoke only when the channel's *wiring* is genuinely new — a new push mechanism or window — never for feature behaviour. Trace assertions do not apply — an Electron app emits no OpenTelemetry traces, so there is no span surface to assert on.

package/src/engineer-skills/groundwork-electron-engineer/references/theming-and-tokens.md

@@ -0,0 +1,74 @@
+# Theming & Tokens — the Desktop Delta
+
+This reference covers **only what the desktop shell adds** to theming. Tailwind composition rules, styling discipline, visual language, and accessibility are the web stack's, unchanged: `groundwork-nextjs-engineer/references/tailwind-and-styling.md` and `groundwork-nextjs-engineer/references/visual-language.md` (or `docs/principles/stack/typescript/frontend.md` when no web surface is installed).
+
+## Table of Contents
+- [The Projection Chain](#the-projection-chain)
+- [The Generated brand.css](#the-generated-brandcss)
+- [The @theme Mapping](#the-theme-mapping)
+- [nativeTheme Sync (the Desktop Dark Mode)](#nativetheme-sync-the-desktop-dark-mode)
+- [Evolving the Brand](#evolving-the-brand)
+
+---
+
+## The Projection Chain
+
+The theme is **generated from the design system's brand tokens**, not authored in the app:
+
+```
+docs/design-system.md → .groundwork/config/brand-tokens.json (visual block)
+                      → src/renderer/src/assets/brand.css      (GENERATED)
+                      → @theme inline mapping in main.css       (static)
+                      → Tailwind utilities in components
+```
+
+The same tokens drive every surface of the product (web, CLI, mobile, desktop), so cross-surface visual consistency is a build artifact, not a review hope. A hex literal in a component is a review finding — it forks the design system silently.
+
+## The Generated brand.css
+
+`brand.css` carries the projected values as CSS custom properties and is regenerated, never hand-edited:
+
+- Palette roles in both themes: `--gw-primary`, `--gw-accent`, `--gw-surface`, `--gw-surface-alt`, `--gw-text-body`, `--gw-success`, `--gw-error`, `--gw-warning`, `--gw-info` — light values on `:root`, dark values on `:root[data-theme='dark']`.
+- Typography: `--gw-font-display`/`--gw-font-body` (+ weights). Families render once they are bundled or system-available.
+- Shape: `--gw-radius-base`.
+
+Unlike the Dart projection (which resolves OKLCH at generation time), the renderer is CSS — token values pass through verbatim and Chromium resolves OKLCH natively. The file header records the projection source (`visual-block`, `identity-only`, or `default` — the three-tier fallback every token consumer implements).
+
+## The @theme Mapping
+
+`main.css` maps the custom properties into Tailwind v4 theme tokens once:
+
+```css
+@theme inline {
+  --color-primary: var(--gw-primary);
+  --color-surface: var(--gw-surface);
+  --color-foreground: var(--gw-text-body);
+  --font-display: var(--gw-font-display);
+  --radius-base: var(--gw-radius-base);
+  /* ... */
+}
+```
+
+Components consume the utilities these tokens create (`bg-surface`, `text-primary`, `font-display`, `rounded-base`) and **never read `--gw-*` variables directly** — the mapping is the API, the variables are the projection artifact. Tailwind v4 is CSS-first: there is no `tailwind.config.js`; the plugin loads in the **renderer section** of `electron.vite.config.ts` and applies to the renderer only (main and preload have no styling surface). Needing a new semantic token means extending the `@theme` mapping from a `--gw-*` value — and if no token expresses the need, that is a design-system gap to raise, not a license to inline a value.
+
+## nativeTheme Sync (the Desktop Dark Mode)
+
+On desktop, the OS owns dark mode and **main is the source of truth** — this is the structural difference from the web stack's `next-themes` approach:
+
+1. Main broadcasts `nativeTheme.shouldUseDarkColors` on the `theme:changed` push channel — once after `did-finish-load`, and on every `nativeTheme.on('updated')`.
+2. The renderer's entry point subscribes via the bridge and mirrors the value onto `<html data-theme="dark|light">`.
+3. `brand.css` resolves every `--gw-*` per theme from that attribute; utilities update without component involvement.
+
+Implementation rules:
+
+- Components never branch on theme to pick values — the custom properties already resolved per-theme. (Conditional *structure* via a `data-theme` selector is fine; conditional *colours* is the antipattern.)
+- Every role carries light **and** dark values — a design-system commitment, not an option; verify visual changes in both themes (flip the OS setting, or `app.evaluate(({ nativeTheme }) => { nativeTheme.themeSource = 'dark'; })` in a smoke-side check).
+- A user-facing theme override (light/dark/system menu) is implemented by setting `nativeTheme.themeSource` in main via an IPC channel — keeping main the single source of truth — never by writing `data-theme` directly from a component.
+
+## Evolving the Brand
+
+1. The design-system run updates `brand-tokens.json`.
+2. Regenerate (or mechanically update) `brand.css` to match — the header marks it generated; keep the `:root` / `:root[data-theme='dark']` structure intact.
+3. The `@theme` mapping and all components pick the change up for free. New palette roles need one new mapping line in `main.css`.
+
+If a visual change cannot be expressed through tokens → brand.css → @theme → utilities, raise the design-system gap; do not hand-edit the projection.

package/src/engineer-skills/groundwork-electron-engineer/sync-anchor.md

@@ -0,0 +1,22 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds — both the per-stack
+Electron / TypeScript idiom docs and the cross-cutting central canon this skill
+distils. When any listed file changes, this skill must be reviewed in the same
+commit (and the matching per-stack idiom doc reconciled to the canon). CI
+verifies the hashes match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/electron-app/docs/principles/stack/electron/index.md | e80808eecbda59c97cd5b7870d621fc07b77ec4a4a0d1b812f4990de02be2675 | 2026-06-27 |
+| src/generators/electron-app/docs/principles/stack/electron/process-model.md | d510797d59a06786fb6bd35f537566ee7f1024ce35a8985c9c94d305e3de5c43 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/electron/ipc-contracts.md | 11d728db5d33c0c9cb3a082a58a55c96d6195f61558ca38fae91806db72da9e3 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/electron/security.md | 316c118dcfb6de110d3d62b8a4c95ca79b58f5368e1b41881cd842628b3902f8 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/electron/packaging-and-updates.md | b5f91ed102290dd73e52890fd389bce5be825a3d76a0f0353673cfe32ae09871 | 2026-06-12 |
+| src/generators/electron-app/docs/principles/stack/typescript/frontend.md | 98232d067ad03c08d6c1ca5f2caec30e7c3400da55c3afb7754482bc121d7554 | 2026-06-12 |
+| src/docs/principles/foundations/testing.md | 205ac40d4c643e7b61cf1e4295df8a7b8b46dcd7c81b857aa8c642ea353f62ef | 2026-06-27 |
+| src/docs/principles/quality/observability.md | 8aa60e213ba03e989c93263153e3a1ac10b2336f6d0360c394f473660d565a0b | 2026-06-26 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-26 |
+| src/docs/principles/quality/performance.md | 18b6d3391c57d97342068f9f1da732b24de4221489d0459bb6ad8900fac0a02e | 2026-06-26 |
+| src/docs/principles/quality/reliability.md | 9c9788504e0963458667d2727c3fc2359776108be593a2efc6603f6470002252 | 2026-06-26 |
+| src/docs/principles/foundations/documentation.md | 8b576072eaf4970f1251b560781e3e755c864a7920faa599b2834c921cbb8734 | 2026-06-26 |