CLAUDE.md

1# CLAUDE.md — Autonomous Agent Instructions
2 
3This project is **fully autonomous**. Claude Code operates independently across all roles: product, design, development, DevOps. Read the relevant role docs before making changes.
4 
5---
6 
7## Role Documents
8 
9| Doc | When to Read |
10|-----|-------------|
11| [`docs/PRODUCT.md`](docs/PRODUCT.md) | Before adding features, changing UX, or making product decisions. Contains vision, terminology, and product principles. |
12| [`docs/DESIGN.md`](docs/DESIGN.md) | Before touching CSS, colors, or UI components. Contains the full color system (Dark/Light), component patterns, and glass effect specs. |
13| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Before writing code. Contains directory structure, code conventions, IPC channels, data flow, and key architectural constraints. |
14| [`docs/DEVOPS.md`](docs/DEVOPS.md) | Before changing build scripts, native modules, or deployment config. Contains build pipeline, signing, and environment setup. |
15| [`docs/USER_FLOWS.md`](docs/USER_FLOWS.md) | Before modifying user-facing behavior. Contains step-by-step flows with edge cases — use as acceptance criteria. |
16| [`docs/MARKETER.md`](docs/MARKETER.md) | Before editing `site/`, adding media assets, or producing social/marketing content. Contains SEO rules, asset optimization standards, canonical URL rules, and the marketing content library. |
17 
18**Read the relevant role doc(s) before starting work.** Don't guess at conventions — they're documented.
19 
20---
21 
22## Documentation Rules
23 
24**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.
25 
26| What Changed | Docs to Update |
27|--------------|----------------|
28| CSS / colors / theme variables | `docs/DESIGN.md` color tables + `docs/ARCHITECTURE.md` if new variables added |
29| User-facing behavior or UX | `docs/USER_FLOWS.md` flow steps + `docs/PRODUCT.md` if feature scope changed |
30| New feature | `docs/PRODUCT.md` feature list + `docs/USER_FLOWS.md` new flow + `docs/ARCHITECTURE.md` if new files/IPC + `README.md` if major |
31| Removed feature | Remove from `docs/PRODUCT.md` + `docs/USER_FLOWS.md` + `README.md` |
32| Architecture / new files / IPC | `docs/ARCHITECTURE.md` directory tree + IPC table + data flow |
33| Build / scripts / native modules | `docs/DEVOPS.md` scripts table + build pipeline |
34| Code conventions changed | `docs/ARCHITECTURE.md` conventions section |
35| New tool or annotation type | `docs/PRODUCT.md` tool table + `docs/USER_FLOWS.md` new tool flow + `docs/ARCHITECTURE.md` directory tree + `README.md` shortcut table |
36| Theme system changes | `docs/DESIGN.md` + `docs/ARCHITECTURE.md` theme system section + `docs/USER_FLOWS.md` §8.4 |
37| Marketing site / SEO / media assets | `docs/MARKETER.md` + update `sitemap.xml` lastmod + verify canonical URLs |
38 
39### How to Update
40 
411. After finishing code changes, review the table above
422. Open each affected doc and update the specific sections — don't rewrite entire files
433. Keep tables, values, and file paths in sync with the actual code
444. If you added a new file, it must appear in `docs/ARCHITECTURE.md` directory tree
455. If you changed a CSS variable value, the corresponding `docs/DESIGN.md` color table must match
46 
47**These docs are the project's memory.** They're how context survives across sessions. Skipping updates means the next session starts with wrong information.
48 
49---
50 
51## Critical Constraints
52 
53These are non-negotiable rules. Violating them causes crashes or broken UX:
54 
55### Threading
56- **ONNX Runtime crashes in worker_threads.** Embeddings must run on the main thread. SAM runs in a child process (not worker).
57- The Ollama worker delegates embedding generation back to main via message passing.
58 
59### CSS
60- **Never hardcode colors.** All colors come from CSS variables in `src/renderer/theme.css`.
61- Two themes exist: `dark`, `light`. Changes must work in both + the solid fallback.
62- **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.
63 
64### Undo Flow
65- **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.
66 
67### Renderer Code Style
68- **No ES modules** in renderer JS: prefer `var`, no `import`/`export`. All tools attach to `window` via IIFEs.
69- Main process uses standard CommonJS `require()`.
70 
71### Naming
72- UI text says **"snip"** not "screenshot". The capture action is **"Snip and Annotate"**.
73 
74### Purple Brand
75- Accent color is **purple/violet**. Never blue. See `docs/DESIGN.md` for exact values per theme.
76 
77### Marketing Site (`site/`)
78- **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.
79- Optimize all media assets for web (compress images to JPG, convert video to MP4 with `crf 28`, remove originals after conversion).
80- Use semantic HTML (`section`, `h2`/`h3`, `alt` text on images, `aria-label` on interactive elements).
81 
82### Releases
83- **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.
84- 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.
85 
86---
87 
88## Project Overview
89 
90**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).
91 
92### Key Paths
93| What | Where |
94|------|-------|
95| Main process entry | `src/main/main.js` |
96| Theme tokens | `src/renderer/theme.css` |
97| Home window | `src/renderer/home.html` + `home.js` + `home.css` |
98| Editor window | `src/renderer/editor.html` + `editor-app.js` + `editor-styles.css` |
99| Annotation tools | `src/renderer/tools/*.js` |
100| Preload (IPC bridge) | `src/preload/preload.js` |
101| AI agent | `src/main/organizer/agent.js` + `worker.js` |
102| Extension registry | `src/main/extension-registry.js` |
103| Extensions (bundled) | `src/extensions/` + `extensions.json` |
104| Extensions (user) | `~/Library/Application Support/snip/extensions/` |
105| CLI | `src/cli/snip.js` |
106| MCP adapter | `src/mcp/server.js` (wraps CLI, direct socket for `render_diagram`) |
107| Diagram renderer | `src/renderer/diagram.html` + `diagram-renderer.js` + `src/preload/diagram-preload.js` |
108| Extension sandbox | `src/main/extension-sandbox.js` + `extension-sandbox-worker.js` |
109| Ollama manager | `src/main/ollama-manager.js` |
110| Ollama (system) | `/Applications/Ollama.app` or `/usr/local/bin/ollama` (user-installed) |
111| Ollama models | `~/.ollama/models/` (managed by system Ollama) |
112| Config | `~/Library/Application Support/snip/snip-config.json` |
113| Screenshots | `~/Documents/snip/screenshots/` |
114| Index | `~/Documents/snip/screenshots/.index.json` |
115 
116### Running the App
117```bash
118npm run dev    # Electron with verbose logging
119npm start      # Normal launch
120npm run build        # Package as macOS DMG
121npm run build:linux  # Package as Linux AppImage + deb
122```
123