groundwork-method 0.0.1 → 0.11.0

package/src/docs/ways-of-working/units-of-work.md

@@ -0,0 +1,40 @@
+---
+title: Units of Work
+description: How GroundWork structures delivery — Bet, Milestone, and Slice.
+status: active
+last_reviewed: 2026-05-26
+---
+
+# Units of Work
+
+GroundWork organises delivery through three nested units — **Bet**, **Milestone**, and **Slice** — each defined by the contract its dependents can rely on. A Bet's appetite holds while scope is designed. A Milestone's capability is provable behind a flag before customers see it. A Slice's API surface is testable before anything consumes it.
+
+## Pitch
+
+A Pitch is the shaped plan for solving a problem within an appetite. It contains: a problem statement, a high-level solution sketch, explicit rabbit holes and no-gos, and a falsifiable success signal — the measurable outcome that confirms the bet delivered its intended value. The appetite is an opportunity-cost judgment made before the solution is designed, not a post-design estimate.
+
+A Pitch does not contain milestones or slices. Those are derived in Decomposition, after the design is locked in Design Foundations.
+
+Multiple Pitches may exist at once. Committing to a Pitch converts it into an active Bet.
+
+## Bet
+
+A Bet is the committed execution of a Pitch — active from the moment the team decides to execute through Validation. A Bet operates on a fixed appetite with variable scope: the worth it is bounded to — judged by opportunity cost, not a calendar-time estimate — is set upfront and does not move; scope adjusts to fit what can be delivered within it.
+
+Milestones and slices are defined in the Decomposition phase, from the locked technical design. They are not part of the Pitch.
+
+## Milestone
+
+A Milestone is a demonstrable state the product reaches within a Bet — visible in the UI and verifiable behind a feature flag, but not yet exposed to customers. Milestones sequence by dependency: a Milestone that requires an earlier one to be complete must declare that dependency explicitly.
+
+The Milestone is not a customer release. It is an internal proof point: the capability exists, can be demonstrated, and composes with other Milestones toward a customer-releasable Bet.
+
+## Slice
+
+A Slice is a vertical cut through a single tech stack component — a service, a module, or a domain area — that delivers a new capability at that component's API boundary. A Slice spans the full depth of its component (schema, business logic, API surface) and stops there. The component above it — the UI or a downstream service — can consume it once the Slice is complete.
+
+The hamburger method defines what "vertical" means in practice: rather than building all schemas across components, then all business logic, then all APIs, each Slice delivers one complete column through a single component's layers. The column is independently testable before anything above it is built.
+
+Milestones close when every Slice that contributes to the Milestone's required API surface is complete.
+
+**Brownfield systems**: Services in brownfield codebases often own multiple domains or share domain logic across services. A Slice is architecture-agnostic — the definition does not assume one service equals one domain. What matters is that a Slice delivers a testable API-level capability at a component boundary, regardless of how that component's internal responsibilities are structured.

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

@@ -0,0 +1,123 @@
+---
+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
+
+**Orient first.** On any non-trivial task, refresh the repo map (`npx groundwork-method repo-map`), read its `centrality` ranking to find the hubs, and navigate them with Serena before reading widely (see Code intelligence above) — this is the first step, not optional; fall back to ordinary reads only when those tools are unavailable. Then 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. |
+| Performance & Reliability | `references/performance-and-reliability.md` | Main never blocks, renderer/bundle perf, IPC batching, long-lived-window memory, cold boot, gateway resilience. |
+| Observability | `references/observability.md` | Two-process crash reporting, structured logs across IPC, app/update telemetry, PII discipline. |
+| Documentation | `references/documentation.md` | The typed IPC contract as documentation, TSDoc on the bridge, process-boundary why-comments. |
+
+## 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.
+- **Performance / responsiveness work** → Load `references/performance-and-reliability.md`. Main never blocks; SLOs and load shedding live in the core.
+- **Crash reporting / telemetry** → Load `references/observability.md`. Both processes report; distributed tracing lives at the services the app calls.
+
+## 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/documentation.md

@@ -0,0 +1,126 @@
+# Documentation
+
+## Table of Contents
+- [Hierarchy](#hierarchy)
+- [The Contract Type Is the Surface Documentation](#the-contract-type-is-the-surface-documentation)
+- [TSDoc on the Bridge Contract](#tsdoc-on-the-bridge-contract)
+- [The Process Boundary Documents Itself](#the-process-boundary-documents-itself)
+- [Why-Comments on Security Policy](#why-comments-on-security-policy)
+- [Inline Comments](#inline-comments)
+- [A Comment Is Often a Smell](#a-comment-is-often-a-smell)
+- [In-Code Markers](#in-code-markers)
+- [What NOT to Document](#what-not-to-document)
+
+---
+
+A desktop shell has a documentation problem the web app does not: the same TypeScript runs in three processes at three privilege levels, and a reader must know which one a file belongs to before a single line makes sense. The architecture answers that in structure — the folder boundary, the shared contract, the typed bridge — so the documentation is mostly the code's shape, not prose around it.
+
+## Hierarchy
+
+Structure documents more reliably than comments. A comment is a promise no compiler checks, and a stale comment about *which process runs this* is worse than none — it misleads about a security boundary. Documentation priority — the foundations principle (`docs/principles/foundations/documentation.md`) written the Electron way:
+
+1. **Types and the shared contract** — `IpcContract`/`RendererApi` in `src/shared/ipc.ts`; a drifted signature is a compile error in both processes (`references/ipc-contracts.md`).
+2. **The folder boundary** — `main/`, `preload/`, `renderer/`, `shared/` declare where code runs; lint and two tsconfigs enforce it (`references/process-model.md`).
+3. **Zod schemas at the trust boundary** — runtime-checked validation that documents the accepted payload and flows into errors.
+4. **Test names** — a smoke or unit test named for its behaviour is executable documentation verified by CI.
+5. **TSDoc on the bridge and security policy** — written only where types and structure cannot carry the intent.
+6. **Inline "why" comments** — last resort for a genuinely non-obvious decision.
+
+Levels 1–4 are verified by tooling. Levels 5–6 are human promises that drift. Minimise them.
+
+## The Contract Type Is the Surface Documentation
+
+`src/shared/ipc.ts` is the single document of what the renderer may ask the privileged side to do. `IpcContract` enumerates every channel; `RendererApi` is the capability surface the UI sees. Read together they are the complete, compiler-verified description of the trust boundary — no prose inventory of "available IPC calls" stays as accurate, because this one fails the build when it lies.
+
+```ts
+// src/shared/ipc.ts — the surface, documented by its types
+export type RendererApi = {
+  openProject: (path: string) => Promise<ProjectSummary>;
+  onProjectChanged: (cb: () => void) => () => void;
+};
+```
+
+The naming carries the documentation: bridge methods name **capabilities** (`openProject`), never transport (`invoke`, `send`). A method called `invoke` documents nothing about what crosses the seam (`references/ipc-contracts.md`).
+
+## TSDoc on the Bridge Contract
+
+Most channels are self-documenting through their contract types. Add TSDoc only where a method carries a consequence the signature cannot — a privileged side effect, a security implication, an OS interaction the caller must understand:
+
+```ts
+export type RendererApi = {
+  /**
+   * Opens a path in the OS file manager. Main validates it is inside an
+   * allowed root before the shell call — a renderer cannot open arbitrary
+   * paths. Rejects if the path escapes the sandboxed roots.
+   */
+  openInFileManager: (path: string) => Promise<void>;
+};
+```
+
+The note documents the trust decision, not the mechanics. A plain `getStatus(): Promise<AppStatus>` needs nothing — the name and return type are the whole contract.
+
+## The Process Boundary Documents Itself
+
+The folder a file lives in is its most important documentation: it declares the privilege level and what the file may import (`references/process-model.md`). That boundary is physical and enforced — `no-restricted-imports` fails the build when `renderer/` or `shared/` imports `electron` or a Node built-in, and the two tsconfigs reject a renderer file touching `process` or a main file touching `document`.
+
+This is why a comment like `// runs in the renderer, no Node here` is a smell: the folder already says it, the lint already enforces it, and the comment will outlive the file's move to another directory. Trust the structure. When a file's process is genuinely ambiguous, the fix is to move it to the right folder, not to annotate it.
+
+`src/shared/` documents a stronger rule by what it contains: types only, no runtime behaviour. A function body in a shared file silently drags Node-flavoured code toward the sandbox — the absence of runtime code there is itself the contract (`references/process-model.md`).
+
+## Why-Comments on Security Policy
+
+Security configuration is the one place inline prose earns its keep, because the *reason* a setting holds is invisible in the value and dangerous to guess at. A future reader tempted to loosen a policy must find the threat model next to the line:
+
+```ts
+// sandbox + contextIsolation are non-negotiable: the renderer loads UI
+// that can be XSS'd; without these, an injection reaches Node and the OS.
+webPreferences: { sandbox: true, contextIsolation: true, nodeIntegration: false },
+
+// CSP forbids connect-src: the renderer fetches nothing directly — core
+// calls go through main over IPC, which holds the credentials.
+```
+
+Keep `src/main/policy.ts` a pure module so the rules are unit-tested rather than narrated (`references/process-model.md`). The test documents the policy's behaviour; the comment documents only the threat the test cannot express.
+
+## Inline Comments
+
+Inline comments explain **why**, never **what**. In a handler, the validation and delegation are visible; the comment captures the reason.
+
+```ts
+ipcMain.handle('project:open', async (event, rawPath: unknown) => {
+  assertTrustedSender(event, devServerUrl); // reject navigated-away frames
+  const path = openProjectPayload.parse(rawPath);
+  return openProject(path);
+});
+```
+
+A comment narrating the obvious is noise — the reader can see the `parse` call.
+
+## A Comment Is Often a Smell
+
+When you reach for a comment to explain *what* a block does, the code is asking to be refactored:
+
+- A comment naming which process a file runs in → move it to the right folder.
+- A comment explaining a generic `invoke(channel, ...)` passthrough → name the capability; the passthrough is itself an anti-pattern (`references/ipc-contracts.md`).
+- A comment decoding an untyped channel string → add it to `IpcContract`.
+- A comment summarising what a handler does → the handler does too much; delegate to a named function in main.
+
+Delete the comment and fix the code. The refactor cannot drift; the comment can.
+
+## In-Code Markers
+
+```ts
+// TODO(bob): move indexing to a utilityProcess once payloads grow. Issue #231.
+// FIXME(carol): unsubscribe leak when a window closes mid-stream. Issue #245.
+// HACK(dave): re-assert CSP after a dev-only HMR reload until upstream fix.
+```
+
+Always include `(username)` and an issue reference. A marker without one will never be resolved.
+
+## What NOT to Document
+
+- Channels whose contract type and capability name tell the whole story.
+- Which process a file runs in — the folder and the lint already say it.
+- Boilerplate window construction — the hardened `webPreferences` quartet is the documented standard (`references/process-model.md`), not a per-window note.
+- TanStack Query `queryFn`s that call the typed bridge — the types are the contract.
+- Generated or framework code — never hand-edit comments into it.

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/observability.md

@@ -0,0 +1,37 @@
+# Observability
+
+An Electron app has two processes and no backend span surface. Distributed tracing lives at the capability core — the services the app talks to — which is why trace-assertions are N/A for the desktop shell (`references/testing-and-smoke.md`). The shell's observability job is **crash reporting and structured logs across the main/renderer boundary**, plus update telemetry. Instrument for the questions you will ask when a user reports a crash you cannot reproduce; the discipline is the framework canon adapted to a binary running on someone else's machine (`docs/principles/quality/observability.md`).
+
+## Crash Reporting — Both Processes
+
+Two signals, both required, because they catch different failures:
+
+- **Native crashes.** Electron's built-in `crashReporter` (Crashpad) captures native crashes in main and renderer and uploads minidumps. Start it in main *before* `app` is ready — a reporter started late misses the early crash.
+- **JS exceptions.** A sink (Sentry-for-Electron shape) captures uncaught JS in both processes — main's `process.on('uncaughtException')`/`'unhandledRejection'` and the renderer's `window` handlers. A native crash and a JS exception are different events; you need both wired.
+
+## Structured Logs Across the Process Boundary
+
+- **Main-process logging** goes to a rotating file sink (electron-log shape) as JSON, severity-tagged. Main has no devtools console, so an unstructured main log is invisible in the field.
+- **Renderer errors forward to main** over IPC, so a single log stream reconstructs an incident that spans both processes. An error that lands only in the renderer devtools is gone the moment the window closes.
+- Tag every line with the process (`main`/`renderer`) and a session id, so a multi-process incident reads as one timeline.
+
+## App and Update Telemetry
+
+`autoUpdater` lifecycle events — update available, downloaded, applied, failed — are the signal for whether the fleet is actually on the new build. A silent update failure strands users on an old version with nothing to alert on, the desktop equivalent of a botched rollout. Carry app version, OS, and channel as context on every event.
+
+## What to Capture vs PII
+
+- **Capture** process, session id, error type and stack, app/OS/channel version, and update events.
+- **Never** log tokens, file paths containing usernames, or PII into logs, crash context, or minidumps. The upload is third-party — redact at the edge.
+
+## Where Distributed Tracing Lives
+
+The end-to-end request trace belongs to the services the app calls and is asserted at the capability core. The shell does not emit spans; it correlates by attaching a request id it can log on both sides of the IPC boundary.
+
+## Anti-Patterns
+
+- **`console.log` in main.** There is no console to read in the field — log structured to the sink.
+- **Renderer errors that never cross to main.** Lost when the window closes.
+- **A late `crashReporter`.** Started after `app` ready, it misses the crashes that happen at startup.
+- **A collector in the shell.** The app reports to a sink; it does not run backend OTel infrastructure.
+- **PII in logs or minidumps.** Usernames in paths and tokens in context follow the upload off-machine.

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`).