CLAUDE.md — Autonomous Agent Instructions

This project is fully autonomous. Claude Code operates independently across all roles: product, design, development, DevOps. Read the relevant role docs before making changes.

Role Documents

Read the relevant role doc(s) before starting work. Don't guess at conventions — they're documented.

Documentation Rules

MANDATORY: After any code change, you MUST update every affected doc before considering the task complete. This is not optional — stale docs break future sessions.

How to Update

1. After finishing code changes, review the table above
2. Open each affected doc and update the specific sections — don't rewrite entire files
3. Keep tables, values, and file paths in sync with the actual code
4. If you added a new file, it must appear in docs/ARCHITECTURE.md directory tree
5. If you changed a CSS variable value, the corresponding docs/DESIGN.md color table must match

These docs are the project's memory. They're how context survives across sessions. Skipping updates means the next session starts with wrong information.

Critical Constraints

These are non-negotiable rules. Violating them causes crashes or broken UX:

Threading

• ONNX Runtime crashes in worker_threads. Embeddings must run on the main thread. SAM runs in a child process (not worker).
• The Ollama worker delegates embedding generation back to main via message passing.

CSS

• Never hardcode colors. All colors come from CSS variables in src/renderer/theme.css.
• Two themes exist: dark, light. Changes must work in both + the solid fallback.
• All new UI must align with the glass design language documented in docs/DESIGN.md. Before writing CSS, read the design doc for the correct variables, component patterns, and glass effect specs. Reuse existing patterns (e.g. tutorial-modal, toast pill, toolbar button states) rather than inventing new ones.

Undo Flow

• Every new tool must consider the undo flow. The editor has a layered undo system: annotations undo first (object stack), then crop (crop undo stack), then segment cutout, then upscale. New tools that modify the background image or canvas dimensions must implement their own undo method (like undoCrop() or undoCutout()), save pre-operation state, and integrate into the undo priority chain in both onUndo callback and the Cmd+Z keydown handler in editor-app.js. Tools that only add Fabric objects get undo for free via the annotation stack.

Renderer Code Style

• No ES modules in renderer JS: prefer var, no import/export. All tools attach to window via IIFEs.
• Main process uses standard CommonJS require().

Naming

• UI text says "snip" not "screenshot". The capture action is "Snip and Annotate".

Purple Brand

• Accent color is purple/violet. Never blue. See docs/DESIGN.md for exact values per theme.

Marketing Site (site/)

• Maximize SEO on every change. When editing site/index.html, always update structured data (ld+json), meta description, Open Graph tags, and featureList to reflect new or changed features.
• Optimize all media assets for web (compress images to JPG, convert video to MP4 with crf 28, remove originals after conversion).
• Use semantic HTML (section, h2/h3, alt text on images, aria-label on interactive elements).

Releases

• Before creating a new release tag, always bump the version in both package.json and package-lock.json (run npm install --package-lock-only to sync the lock file). Commit the version bump before tagging.
• The marketing site's download link is dynamic — site/script.js fetches the latest release from GitHub's API at runtime. No manual version update is needed; it automatically points to the newest DMG once the release workflow completes.

Project Overview

Snip is a cross-platform Electron app (macOS and Linux) — the visual communication layer between humans and AI agents. Menu-bar / system tray only (no Dock icon on macOS). Capture via global shortcut, annotate with Fabric.js tools, render diagrams via Mermaid, review agent-generated visuals with approve/request-changes flow. AI-powered organization via local Ollama LLM, semantic search. Linux support targets Wayland sessions (X11 is untested).

Key Paths

Running the App

npm run dev    # Electron with verbose logging
npm start      # Normal launch
npm run build        # Package as macOS DMG
npm run build:linux  # Package as Linux AppImage + deb