groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-electron-engineer/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: groundwork-electron-engineer
+description: >
+  Implement, review, and refactor Electron desktop applications using the
+  hardened main/preload/renderer process model, typed IPC contracts with
+  runtime validation, enforced security defaults, fuse-hardened Forge
+  packaging, and Playwright _electron boot smokes. Use for work touching the
+  main process, preload bridges, IPC channels, BrowserWindow configuration,
+  contextBridge, utilityProcess, auto-update, code signing, desktop packaging,
+  nativeTheme, or Electron testing. Make sure to use this skill whenever a
+  user is working in an Electron codebase, building desktop shell features,
+  fixing desktop app bugs, or reviewing Electron code.
+---
+
+# Electron Engineer
+
+Desktop execution engineer for Electron applications. This skill guides implementation within the flagship-app architecture — a privileged main process that only orchestrates, fully sandboxed Node-free renderers behind a narrow typed bridge, security defaults that are baked rather than advisory, and a boot smoke driven by Playwright's `_electron` driver, the agent-closable loop this stack was chosen for.
+
+## Operating Contract
+
+1. Locate the process before editing. Main, preload, renderer, and shared each have distinct responsibilities and their own compiler context; a change that blurs the boundary is wrong even when it works.
+2. The capability core owns business logic. The renderer is a thin surface adapter, and privileged core access belongs on main's side of the IPC seam — never re-implement a rule the core's contract already proves.
+3. Route durable desktop policy to the canonical docs (`docs/principles/stack/electron/`) instead of duplicating it in code comments or this skill.
+4. Verify typecheck (both tsconfigs), lint (including the boundary rules), unit tests, and — for shell-touching changes — the boot smoke before declaring work complete.
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+## Core Pillars
+
+1. **Main Is an Orchestrator** — Window creation, security policy, IPC registration, OS integration. CPU-heavy or crash-prone work runs in a `utilityProcess` with MessagePorts wired renderer↔utility directly. A blocked main process freezes every window the app has.
+
+2. **The Renderer Is a Web App** — Sandboxed, context-isolated, Node-free; its only platform surface is the preload-exposed `window.api`. Everything it shares with the web stack — component idiom, styling, accessibility — follows the web rules unchanged (see the deferrals below).
+
+3. **IPC Is a Contract Boundary** — One shared channel-map type consumed by both sides; `invoke`/`handle` for two-way; sender validation in every handler and zod validation for non-trivial payloads. The seam gets the same discipline the core enforces at its contracts.
+
+4. **Security Defaults Are Baked** — The hardened quartet, denied-by-default permissions, restricted navigation, allowlisted `openExternal`, custom-protocol content, strict CSP, and package-time fuses. None of these is a hardening backlog item; loosening one is a defect.
+
+5. **The Smoke Closes the Loop** — Playwright `_electron` launches the real built app, drives its window as an ordinary Page, and evaluates in the main process — headless under xvfb in CI. Generate → boot → test → observe, no human in the loop.
+
+## How to Use This Skill
+
+Match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Process Model | `references/process-model.md` | Placing new code, main vs preload vs renderer vs shared, utilityProcess, the enforced folder boundary. |
+| IPC Contracts | `references/ipc-contracts.md` | Adding or changing channels, the bridge, validation at the seam, TanStack Query over IPC, push events. |
+| Security | `references/security.md` | BrowserWindow options, permissions, navigation, openExternal, CSP, the custom protocol, fuses, Electron upgrades. |
+| Packaging & Updates | `references/packaging-and-updates.md` | Forge config, makers, fuses at package time, code signing, notarization, auto-update routes. |
+| Testing & Smoke | `references/testing-and-smoke.md` | The three test tiers, Playwright `_electron` patterns, xvfb CI, skip-with-reason guards. |
+| Theming & Tokens | `references/theming-and-tokens.md` | The generated brand.css, Tailwind token mapping, nativeTheme sync, dark mode on desktop. |
+
+## Shared with the web stack — deferrals
+
+The renderer is a normal Vite + React web app, and the web stack's rules apply to it unchanged. That knowledge is owned by the Next.js engineer skill (`.agents/skills/groundwork-nextjs-engineer/`, installed alongside any web surface) and by `docs/principles/stack/typescript/frontend.md` (always deployed with this app); it is deliberately **not** duplicated here:
+
+- **Component idiom, composition, and visual language** → `groundwork-nextjs-engineer/references/visual-language.md` and `groundwork-nextjs-engineer/references/ux-principles.md`. Skip the App Router / Server Component material — an Electron renderer is fully client-side and has no server boundary.
+- **Tailwind usage and styling discipline** → `groundwork-nextjs-engineer/references/tailwind-and-styling.md`. Only the desktop delta (the generated token file, nativeTheme sync) lives in this skill's `references/theming-and-tokens.md`.
+- **Data-fetching discipline** (cache-layer rules, no fetch-in-useEffect) → `groundwork-nextjs-engineer/references/data-fetching.md`. The transport here is the IPC bridge with TanStack Query instead of SWR over HTTP — that delta is in `references/ipc-contracts.md`.
+- **Accessibility** → `groundwork-nextjs-engineer/references/ux-principles.md` (Accessibility) and `groundwork-nextjs-engineer/references/testing.md` (Accessibility Testing). Desktop changes nothing about it.
+- **Component testing idiom** (Testing Library patterns, what to assert) → `groundwork-nextjs-engineer/references/testing.md`. This skill's testing reference covers only what the shell adds: the process-split test projects and the `_electron` smoke.
+
+When the workspace has no web surface, the same canon is available as `docs/principles/stack/typescript/frontend.md` in the project's deployed docs.
+
+## Task Routing
+
+- **New capability reaching the shell** → Load `references/ipc-contracts.md`. Contract type first, then handler (validated), then bridge method, then the renderer query.
+- **New window / shell behaviour** → Load `references/process-model.md` and `references/security.md`. The quartet and the policy handlers apply to every window, no exceptions.
+- **Heavy work (parsing, crypto, indexing)** → Load `references/process-model.md`. It goes in a `utilityProcess`, not main.
+- **UI/visual work** → Load `references/theming-and-tokens.md`, then defer to the web stack's styling references. Check the generated token file before adding any colour.
+- **Release/packaging work** → Load `references/packaging-and-updates.md`. Fuses and signing live in the pipeline; signing material never enters the repo.
+- **Test work** → Load `references/testing-and-smoke.md`. Pick the cheapest tier that can carry the assertion; the smoke stays thin.
+- **Electron upgrade** → Load `references/security.md` (currency window). Treat a skipped support window as a security finding.
+
+## Safety Gates
+
+- Do not loosen the hardened quartet — `contextIsolation: true`, `sandbox: true`, `nodeIntegration: false`, `webSecurity: true` — for any window, flag, or debugging session.
+- Do not expose `ipcRenderer`, any Electron module, or a generic `invoke` passthrough on `window`; the bridge stays narrow and purpose-named.
+- Do not add an IPC handler without sender validation, or accept a non-trivial payload without zod parsing.
+- Do not import Electron or Node built-ins in `src/renderer/` or `src/shared/` — the lint boundary and per-process tsconfigs enforce this; a suppression comment is a review finding.
+- Do not serve app content over `file://` or weaken the CSP to unblock a feature.
+- Do not ship a build whose fuses were not flipped by the packaging pipeline, and do not flip `nodeCliInspect` off — it breaks the Playwright `_electron` loop.
+- Run typecheck, lint, and unit tests where the toolchain is available; report a tier as skipped-with-reason (never silently green) where it is not.
+
+## Hallucination Controls
+
+Before presenting Electron guidance as factual:
+
+- Check `package.json` for the actual Electron major and available dependencies; the support window moves every 8 weeks.
+- Check `src/shared/ipc.ts` for the real channel map before referencing or inventing channels.
+- Check `src/main/policy.ts` for the actual navigation/permission/external-URL rules before describing the app's security behaviour.
+- Check `electron.vite.config.ts` and `forge.config.ts` for the real build/packaging shape before recommending tooling changes.
+- Label any recommendation based on general Electron knowledge (rather than project-specific patterns) as an inference.
+
+## Output Expectations
+
+- Changes name the process each touched file runs in and why the code belongs there.
+- IPC changes show all four pieces: contract type, validated handler, bridge method, renderer consumption.
+- Shell changes state their security impact explicitly, even when it is "none".
+- Verification steps name the specific Nx targets (`typecheck`, `lint`, `test`, `smoke`) with the skipped-with-reason caveat where the binary or display is absent.
+- Recommendations distinguish project conventions from general Electron practice.
+
+## Antipatterns
+
+Reject these patterns:
+
+- **Node-enabled renderers** — `nodeIntegration: true` also silently kills the sandbox for that renderer; the controls fail as a set.
+- **Raw ipcRenderer on window** — The bridge exists to be narrow; this makes it infinitely wide.
+- **`sendSync`** — Blocks the renderer event loop. There is always an async shape.
+- **Untyped ad-hoc channels** — A channel missing from the shared contract is a seam that drifts silently.
+- **Trusting renderer input in main** — Compile-time types are not runtime guarantees; validate sender and payload.
+- **CPU-heavy work in main** — It freezes every window. `utilityProcess` exists.
+- **Shared folders with runtime code** — `src/shared/` carries types only; shared behaviour leaks Node toward the sandbox.
+- **`webSecurity: false` or CSP wildcards to "unblock" development** — Fix the content, not the boundary.
+- **Un-fused release builds** — Post-CVE-2025-55305, ASAR integrity off is a shipping defect.
+- **Fat smoke suites** — The smoke proves boot and wiring; rules are proven in unit tiers and at the core's contract.

package/src/engineer-skills/groundwork-electron-engineer/references/ipc-contracts.md

@@ -0,0 +1,138 @@
+# IPC Contracts
+
+## Table of Contents
+- [The Seam Is a Contract](#the-seam-is-a-contract)
+- [Adding a Channel End-to-End](#adding-a-channel-end-to-end)
+- [Validation at the Trust Boundary](#validation-at-the-trust-boundary)
+- [Push Channels (Main → Renderer)](#push-channels-main--renderer)
+- [TanStack Query Over the Bridge](#tanstack-query-over-the-bridge)
+- [Core Access for a Hosted Capability Core](#core-access-for-a-hosted-capability-core)
+- [The electron-trpc Variant](#the-electron-trpc-variant)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## The Seam Is a Contract
+
+The main↔renderer seam gets the same discipline the capability core enforces at its contracts. One module — `src/shared/ipc.ts` — declares every channel; both sides import it; a rename or payload change is a compile error in both processes.
+
+```ts
+// src/shared/ipc.ts (types only)
+export type IpcContract = {
+  'app:get-status': { args: []; result: AppStatus };
+  'shell:open-external': { args: [url: string]; result: OpenExternalResult };
+};
+```
+
+Channel naming: `domain:verb` (`project:open`, `settings:get`, `theme:changed`). The bridge methods name **capabilities** (`getStatus`, `openExternal`), never transport (`invoke`, `send`).
+
+`invoke`/`handle` is the two-way pattern — promise-based, errors propagate to the caller. `send`/`on` carries one-way pushes from main. `sendSync` is forbidden: it blocks the renderer event loop for the round trip.
+
+## Adding a Channel End-to-End
+
+Four pieces, in this order. A channel missing any of them is incomplete.
+
+**1. Contract type** (`src/shared/ipc.ts`):
+
+```ts
+export type ProjectSummary = { path: string; fileCount: number };
+
+export type IpcContract = {
+  // ...existing channels
+  'project:open': { args: [path: string]; result: ProjectSummary };
+};
+
+export type RendererApi = {
+  // ...existing methods
+  openProject: (path: string) => Promise<ProjectSummary>;
+};
+```
+
+**2. Validated handler** (`src/main/ipc.ts`):
+
+```ts
+const openProjectPayload = z.string().min(1);
+
+ipcMain.handle('project:open', async (event, rawPath: unknown): Promise<ProjectSummary> => {
+  assertTrustedSender(event, devServerUrl);          // every handler
+  const projectPath = openProjectPayload.parse(rawPath); // non-trivial payloads
+  return openProject(projectPath);                   // delegate; main orchestrates
+});
+```
+
+**3. Bridge method** (`src/preload/index.ts`):
+
+```ts
+const api: RendererApi = {
+  // ...existing methods
+  openProject: (path) => ipcRenderer.invoke('project:open', path),
+};
+```
+
+**4. Renderer consumption** — through the cache layer, never a bare effect:
+
+```ts
+const { data } = useQuery({
+  queryKey: ['project', path],
+  queryFn: () => window.api.openProject(path),
+});
+```
+
+Typing keeps the pieces honest: `RendererApi` is implemented by preload and consumed via the `Window` augmentation in `src/renderer/src/env.d.ts`, so a drifted signature fails both tsconfigs.
+
+## Validation at the Trust Boundary
+
+Main treats renderer input as untrusted, the same way an API treats the public internet. Two checks in every handler:
+
+- **Sender validation, always.** `assertTrustedSender` verifies `event.senderFrame.url` against the bundle protocol / dev-server origin (security checklist item 17). A destroyed or missing frame is rejected. This is what stops an iframe or a navigated-away window from driving privileged code.
+- **Payload validation with zod for anything beyond a trivial getter.** TypeScript types vanish at runtime; a compromised renderer is not bound by them. `z.string().url()`, `z.object({...}).strict()` — parse, don't trust. A handler taking no arguments (like `app:get-status`) needs only the sender check.
+
+Failures throw — `invoke` rejects in the renderer, which is correct: a rejected privileged call is a bug or an attack, not a state to paper over.
+
+## Push Channels (Main → Renderer)
+
+One-way events (theme changes, update progress, file-watcher hits) flow as `webContents.send` from main to a **subscription method on the bridge** that returns an unsubscribe function:
+
+```ts
+// preload
+onThemeChanged: (callback) => {
+  const listener = (_e: Electron.IpcRendererEvent, theme: ThemeInfo) => callback(theme);
+  ipcRenderer.on('theme:changed', listener);
+  return () => ipcRenderer.removeListener('theme:changed', listener);
+},
+```
+
+Declare push channels in `IpcPushContract` so they are part of the contract too. The renderer never receives the event object — only the typed payload. Theme is the canonical example: `nativeTheme` in main, broadcast on `updated`, mirrored onto `<html data-theme>` (`references/theming-and-tokens.md`).
+
+## TanStack Query Over the Bridge
+
+The renderer's data source is IPC, not HTTP, and TanStack Query is the convergent IPC-aware pattern: `queryFn`s call the typed bridge; caching, retry, and invalidation work exactly as in an HTTP app. This is the desktop shell's one deviation from the web stack's SWR pick — the one-cache-one-mental-model rule still holds: **TanStack Query is the renderer's only query library.**
+
+Push events invalidate queries through a bridge subscription:
+
+```ts
+useEffect(() => {
+  return window.api.onProjectChanged(() => {
+    void queryClient.invalidateQueries({ queryKey: ['project'] });
+  });
+}, [queryClient]);
+```
+
+(The effect here manages a subscription — that is its legitimate use. *Fetching* in an effect is still wrong; see the web stack's data-fetching reference for the full discipline.)
+
+## Core Access for a Hosted Capability Core
+
+When the workspace has a hosted core (services behind promoted contracts), the desktop app reaches it from **main's side of the seam**: main holds the HTTP client, tokens, and retries; the renderer asks main over IPC. This keeps credentials out of the sandboxed process, keeps the strict CSP intact (`default-src 'self'` — the renderer fetches nothing), and gives core calls the same sender/payload validation as every other channel. Do not punch `connect-src` holes in the CSP to let the renderer fetch the gateway directly.
+
+## The electron-trpc Variant
+
+tRPC-over-IPC (Zod inputs, queries/mutations/subscriptions, React Query integration) is the packaged version of this pattern — and a **recorded choice, not the default**: it sits in a maintenance lull (tRPC v11 support lives in forks) and adds per-call overhead on hot paths. The hand-rolled contract above covers the same ground with no dependency risk. Adopt electron-trpc only via a decision record naming what outgrew the hand-rolled seam.
+
+## Anti-Patterns
+
+- **Exposing `ipcRenderer`, a whole Electron module, or a generic `invoke(channel, ...args)` passthrough on `window`.** All three make the narrow bridge infinitely wide.
+- **`sendSync`.** Always an async shape instead.
+- **String-typed ad-hoc channels** with no entry in the shared contract.
+- **Trusting renderer payloads or senders** because "the types guarantee it" — they don't, at runtime.
+- **The `remote` module** or packages emulating it.
+- **Raw `useEffect` IPC fetching.** Data goes through TanStack Query; effects only manage subscriptions.

package/src/engineer-skills/groundwork-electron-engineer/references/packaging-and-updates.md

@@ -0,0 +1,82 @@
+# Packaging & Updates
+
+## Table of Contents
+- [The Toolchain Split](#the-toolchain-split)
+- [Anatomy of forge.config.ts](#anatomy-of-forgeconfigts)
+- [Makers](#makers)
+- [Code Signing](#code-signing)
+- [Auto-Update Routes](#auto-update-routes)
+- [Update Discipline](#update-discipline)
+- [Version Hygiene](#version-hygiene)
+
+---
+
+## The Toolchain Split
+
+Two tools, one pipeline:
+
+- **electron-vite builds.** One `electron.vite.config.ts` with `main`/`preload`/`renderer` sections → `out/`. Renderer HMR and main/preload hot-reload in dev; `utilityProcess` workers via `?modulePath`. Tailwind loads as a Vite plugin in the **renderer section only**.
+- **Electron Forge packages.** `forge.config.ts` drives `@electron/packager`, the makers, signing hooks, and `@electron/fuses` — the officially recommended pipeline, maintained in the `electron/` org.
+
+`package.json` `main` points at `out/main/index.js`, so packaging always consumes the built output; the `package` Nx target runs the build first. Forge's own Vite plugin remains experimental and lags Vite majors — keep the electron-vite + Forge pairing. **electron-builder** is the recorded escape hatch when packaging needs outgrow Forge's makers (exotic targets, NSIS specifics, staged-rollout updater); switching to it is a decision record, not a preference.
+
+## Anatomy of forge.config.ts
+
+The generated config has three load-bearing parts:
+
+```ts
+packagerConfig: {
+  asar: true,                 // required for the integrity fuses to mean anything
+  appBundleId: '<org>.<app>', // macOS bundle id; pairs with the AppUserModelID main sets
+},
+makers: [new MakerZIP({}, ['darwin', 'linux', 'win32'])],
+plugins: [new FusesPlugin({ ... })],   // see references/security.md → Fuses
+```
+
+The fuses plugin is the part that must never be removed or moved out of the pipeline: it is what makes "an unhardened binary cannot ship" structurally true rather than procedurally hoped. `nodeCliInspect` stays on (Playwright `_electron` needs it); everything else is hardened per the table in `references/security.md`.
+
+## Makers
+
+ZIP is the scaffold's lowest-common-denominator maker — it packages on every host OS with no native tooling. Graduate per platform when distribution starts:
+
+| Target | Maker | Notes |
+|---|---|---|
+| Windows installer | `@electron-forge/maker-squirrel` | Pairs with the Squirrel auto-update route; set `setupIcon`, match `appBundleId`/AppUserModelID |
+| macOS disk image | `@electron-forge/maker-dmg` | Sign + notarize first or Gatekeeper rejects |
+| Linux | `maker-deb` / `maker-rpm` | Needs `dpkg`/`rpm` on the build host |
+
+Cross-platform makers generally require their native OS — package per-OS in CI matrix jobs, not on one machine.
+
+## Code Signing
+
+An unsigned build is a development artifact, never a release. Both platforms treat unsigned binaries as malware, because malware is what unsigned binaries usually are.
+
+- **macOS:** Developer ID certificate + hardened runtime + entitlements, then notarization via `notarytool` (Forge wraps `@electron/notarize` — configure `osxSign`/`osxNotarize` in `packagerConfig`). `altool` is dead. Credentials arrive from CI secrets, never the repo.
+- **Windows:** **Azure Artifact Signing** (renamed from Azure Trusted Signing; GA since Jan 2026) — cloud-HSM-backed, clears SmartScreen, runs from CI via signtool/jsign. USB-token OV/EV certificates cannot live in a pipeline; they are the legacy path. (Tooling note: post-rename CLI tools have needed `--prerelease` flags — verify current tool names when wiring CI.)
+
+Signing config is wired in `forge.config.ts` when release credentials exist; until then the scaffold's unsigned `package` output is explicitly a dev artifact.
+
+## Auto-Update Routes
+
+Two sanctioned routes — pick by distribution model, record the choice:
+
+1. **Open-source, GitHub-released:** `update-electron-app` (drop-in module) against **update.electronjs.org** — free, zero infrastructure, feeds the platform-native Squirrel updaters behind Electron's built-in `autoUpdater`. Serves only semver-tagged, non-draft releases.
+2. **Everything else:** `electron-updater` with a generic/S3/GitHub feed — channels and staged rollouts included. Self-hosted feed servers only when rollout control demands them.
+
+A hand-rolled update endpoint without semver and rollback discipline is an outage generator, not a third route.
+
+## Update Discipline
+
+Fixed rules, each one a classic self-inflicted outage when skipped:
+
+- Never check for updates on `--squirrel-firstrun` — the install is still settling.
+- Call `quitAndInstall()` only after the `update-downloaded` event.
+- One in-flight `checkForUpdates()` at a time; double-calls corrupt state.
+- `app.setAppUserModelId()` must match the Squirrel shortcut ID (the generated main sets it from the same `appId` as the bundle id) or Windows notifications detach.
+- Staying inside the 3-major Electron support window is an update-discipline item (`references/security.md` → The Currency Window) — the auto-updater is the mechanism that makes the 8-week cadence shippable.
+
+## Version Hygiene
+
+- `version` in `package.json` is what `app.getVersion()` reports, what the smoke sees, and what update feeds compare — bump it semver-honestly per release.
+- Pin the Electron major deliberately (`^42.0.0` floats within the major; that is correct — patch releases are Chromium security fixes).
+- When bumping the Electron major, run the full tier set including the smoke in CI before merging: driver/runtime pairings occasionally regress (`references/security.md`).

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)