PwrSnap: Instructions file for Codex

PwrSnap Repository Guidance

Source of Truth

• docs/architecture.md is the canonical description of what PwrSnap is and why it is shaped this way — read it before changing scope, schema, or IPC contracts. It is deliberately short and carries no phase order or task lists.
• This file (AGENTS.md) holds the enforcement rules — the invariants a change can violate. docs/architecture.md explains why; the sections below say what you must not break.
• Solution learnings (post-incident notes, gotchas) live in docs/solutions/.
• Shipped-behavior references live at the top level of docs/ — the release runbook, the Windows guide and signing doc, the ffmpeg build reference, and the third-party license notices doc.
• Two documents that began as plans survive as living references, because each is the only written statement of something still true: the bundle format spec and the Windows port status (an open backlog).
• docs/plans/ and docs/brainstorms/ are gone and are not coming back. Do not recreate them. A change that needs written scope belongs in an issue or a PR description; a change that is architectural belongs in docs/architecture.md.
• The original Claude Design handoff bundle (HTML/JSX/CSS reference for the Library + Float-Over + Tray surfaces) is preserved verbatim under design/. Treat it as a visual reference, not as code to import.

Workflow

• Retention policy for docs (replaces the former blanket "never delete" rule). The old rule read: "Do not delete or 'clean up' files in docs/brainstorms/, docs/plans/, or docs/solutions/." It was written to stop drive-by tidying of decision artifacts, and it worked — but it also preserved ~40 phase plans and requirements docs long past the point where they described the product. They accumulated status: active front matter and unchecked task lists over features that had shipped months earlier, and agents reading them were reliably misled. The policy now:
  • docs/solutions/ is still never deleted. Post-incident notes stay true whether or not the code moved on; they record how a class of bug was found. Same for the top-level shipped-behavior docs in docs/.
  • docs/architecture.md is amended, not archived. When a decision in it stops holding, fix it in the PR that changed it.
  • Plan-shaped documents are deleted once the work lands. A plan's value expires when the code exists — the code, its comments, and AGENTS.md are truer sources. Keep one only if it is the sole written statement of a still-live contract — and then move it out of plan-shaped naming into docs/, and say at the top of the file what it is and why it survived. docs/architecture-bundle-format.md and docs/windows/port-status.md are the two that qualified.
  • Git history retains everything. "It might be useful someday" is not a reason to keep a document that is currently wrong.
• Treat any surviving plan document as a decision artifact, not an implementation script, and verify its claims against the code before acting on them.
• Never suggest wiping the user's database (even on a dev machine). The pwrsnap.db at ~/Library/Application Support/PwrSnap/pwrsnap.db contains real captures the user cares about. If a migration / schema bug bricks startup, the fix is in code — make the migration self-heal, detect drift, add a repair pass — NOT to tell the user rm pwrsnap.db*. Same rule for any other persisted state: captures dir, cache dir, settings.json, secrets. Suggesting "blow it away" is a non-starter.
• To reproduce the Linux GitHub Actions Desktop E2E job locally, prefer pnpm test:desktop-e2e:docker from the repo root (or pass --test '<pattern>' --iterations 30 for flake hunting). This runs the Linux/xvfb subset on Docker's native Linux platform; macOS-only clipboard, tray, menu-bar, screen-capture, and AppKit windowing specs are expected to be skipped. Add --platform linux/amd64 only when investigating architecture-specific GHA parity.
• The macOS GHA Desktop E2E job runs the whole suite with PWRSNAP_E2E_DISABLE_GPU=1 (software rendering — see .github/workflows/ci.yml), and pnpm test:desktop-e2e does not set it. A plain local run is therefore a DIFFERENT environment than the one every screenshot golden was recorded in; check that before concluding a local-only failure is a stale golden, a flake, or "just this machine". Suites sensitive to rasterization should pin the env themselves and assert the pin rather than trust the caller — visual-regression.spec.ts does both.
• Headed desktop E2E belongs in the lab VM, not on the operator's machine. It takes over the screen — opens windows, steals focus, drives the selector and global hotkeys — and the operator's real windows can leak into a capture. For macOS Tart, self-hosted runner, or headed E2E work, follow .agents/skills/macos-vm-e2e-lab/SKILL.md. It discovers an existing PwrSuiteLab checkout and routes all lab access through that checkout's current instructions and controllers (macos-tart/run-e2e.sh). For Windows probes or Windows headed E2E, read the Windows VM skill in that same checkout. Do not provision a product-local Tart lab from this repository, improvise direct Tart or SSH access, or run headed E2E on the operator's desktop without their explicit approval.
• Keep private lab details out of this repository. Host and guest names, addresses, usernames, fingerprints, keys, config contents, and fleet inventory live only in PwrSuiteLab — including in commit messages, PR bodies, issues, and fixtures. What may live here is the product/CI contract, the fact that the lab exists and is named PwrSuiteLab, and the controller entry points it exposes (macos-tart/run-e2e.sh and its flags) — enough to invoke it, never enough to map it.