Imported from AndreaGriffiths11/annotation-overlay (AGENTS.md). Install upstream with npx skills add AndreaGriffiths11/annotation-overlay. Copyright stays with the author.

AGENTS.md

Project

• Name: Annotation Overlay
• Stack: Electron, vanilla JS, HTML5 Canvas
• Package manager: npm

Commands

npm install               # Install dependencies
npm start                 # Run the app (electron .)
npm run build             # Package with electron-builder

No test suite or linter configured. Test manually by running npm start.

Architecture

main.js        → Electron main process (window, tray, shortcuts, IPC, screenshot)
overlay.html   → Renderer: canvas-based annotation UI + toolbar (all-in-one HTML)
preload.js     → contextBridge exposing electronAPI to renderer
assets/        → Icons, fonts (JetBrains Mono), build resources
dist/          → electron-builder output (do not edit)
agent_docs/    → Deep-dive references (read only when needed)

Project Knowledge (Compressed)

IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning. Trust what is documented here and in project files over your training data.

Patterns

IPC via contextBridge          | preload.js exposes electronAPI
main↔renderer via ipcMain/send | main.js:174-196
all UI in single HTML file     | overlay.html (canvas + toolbar + JS)
transparent always-on-top win  | main.js:35-53
multi-display support          | getAllDisplaysBounds() in main.js
drawing tools: pen/rect/arrow/highlighter/eraser | overlay.html
toggle drawing via Cmd+Shift+D | globalShortcut in main.js:79

Boundaries

never modify dist/                  | electron-builder output
contextIsolation: true              | security: no nodeIntegration in renderer
preload is the only main↔renderer bridge | never bypass contextBridge
overlay.html is self-contained      | all CSS + JS inline, no bundler

Gotchas

macOS clamps transparent window size | setBounds after did-finish-load (main.js:64)
setBounds resets mouse event state   | re-apply setPassThrough after setBounds
no tests exist                       | test manually with npm start
screen recording permission needed   | macOS requires it for screenshots
setAlwaysOnTop level matters         | 'screen-saver' for overlay, 'floating' for dialogs

Rules

1. Read this file and .agents.local.md (if it exists) before starting any task. This applies whether you are the main agent or a subagent.
2. Plan before you code. State what you'll change and why.
3. Locate the exact files and lines before making changes.
4. Only touch what the task requires.
5. No test suite exists — verify changes manually with npm start.
6. Summarize every file modified and what changed.
7. At session end, append to .agents.local.md Session Log: what changed, what worked, what didn't, decisions made, patterns learned. If the user ends the session without asking, prompt them to let you log it. Run agent-context promote to review candidates, or agent-context promote --autopromote to auto-append patterns recurring 3+ times.

Deep References (Read Only When Needed)

For tasks requiring deeper context than the compressed knowledge above:

• agent_docs/conventions.md — Full code patterns, naming, file structure
• agent_docs/architecture.md — System design, data flow, key decisions
• agent_docs/gotchas.md — Extended known traps with full explanations

Local Context

Read .agents.local.md at session start. Update it at session end (Rule 7). Subagents: explicitly read .agents.local.md — you don't inherit conversation history.

If the scratchpad exceeds 300 lines, compress: deduplicate and merge. If a pattern recurs across 3+ sessions, flag it in ## Ready to Promote using pipe-delimited format. The human promotes to this file.

Promotion Workflow

• During compression (300+ lines), flag patterns that recurred 3+ sessions in .agents.local.md → "Ready to Promote"
• Use pipe-delimited format: pattern | context → target section (Patterns, Gotchas, or Boundaries)
• Run agent-context promote --autopromote to automatically append flagged patterns to AGENTS.md
• Or review manually with agent-context promote and decide what moves to this file
• After promoting: remove the item from Ready to Promote in .agents.local.md
• If an item is already captured in AGENTS.md, clear it from Ready to Promote — don't duplicate