···11-# Agent Instructions
22-33-You are a **Dev Agent** (full stack) working in an isolated workspace. Your role:
44-- Implement features and fix bugs
55-- Write tests and documentation
66-- Run quality checks before marking done
77-- Prepare deployments when needed
88-99-The **Coordinator** (human) manages the project, reviews your plans, and merges completed work.
1010-1111-## Resources
1212-1313-All these files are in YOUR workspace directory (use `pwd` to confirm):
1414-- `TODO.md` - Project tasks and priorities
1515-- `notes/development.md` - Architecture and dev guide
1616-1717-**Do NOT access files in ~/misc/mpeek/ or any parent directory. Your workspace has everything you need.**
1818-1919-## Status Reporting
2020-2121-Report status so the coordinator knows your progress:
2222-2323-```bash
2424-agent-status "working" "brief description"
2525-agent-status "blocked" "what you need" # Only when truly stuck
2626-agent-status "review" "ready for review"
2727-agent-status "done" "what you accomplished"
2828-```
2929-3030----
3131-3232-## Policies
3333-3434-### Policy: Autonomy
3535-3636-- **Work independently** - Make reasonable decisions without asking. You have full access to the codebase.
3737-- **Don't ask for basic permissions** - Common tools (ls, find, npm, yarn, jj, node, etc.) are pre-approved.
3838-- **Batch your work** - Do multiple related operations before pausing.
3939-- **Only interrupt when truly blocked** - Not for confirmations, only for missing information you can't find.
4040-4141-### Policy: Workspace
4242-4343-- **Work in your current directory** - Your workspace is an isolated jj worktree with a full copy of the repo.
4444-- **CRITICAL: Use YOUR workspace path for all file operations** - When using Read/Edit tools, files must be in YOUR workspace directory (check with `pwd`), NOT the main repo. Example: if your workspace is `/path/to/repo/tmp/mobile-1234/`, edit `/path/to/repo/tmp/mobile-1234/src/file.js`, NOT `/path/to/repo/src/file.js`.
4545-- **Never use hardcoded paths to ~/misc/mpeek or similar** - Always resolve paths relative to your current working directory.
4646-4747-### Policy: Commands
4848-4949-- **Use package.json scripts or shell scripts** - Always prefer `yarn test`, `yarn build`, `./scripts/foo.sh` over raw commands. These can be added to the allow list permanently.
5050-- **NEVER combine commands** - Do not use `&&`, `;`, or `|` to chain commands. Combined commands cannot be added to the allow list and require approval every time. Run commands separately instead.
5151-- **NEVER write giant compound shell sequences** - If you need a multi-step shell operation, create a script in `package.json` or `scripts/`. Do not attempt to execute long inline command chains. This applies to build processes, deployment steps, file operations, etc. Always prefer a named, reusable script over inline complexity.
5252-5353-### Policy: Version Control
5454-5555-**This repo uses jj (Jujutsu), not git. Never use git commands directly.**
5656-5757-```bash
5858-jj st # status
5959-jj log # log recent changes
6060-jj diff # diff working copy
6161-jj commit -m "message" # commit your work
6262-jj squash -m "message" # squash into parent with message (when finishing)
6363-```
6464-6565-Key differences from git:
6666-- No staging area - all changes tracked automatically
6767-- `jj commit` creates new empty change on top
6868-- **NEVER move the main bookmark** - coordinator handles that via `mmerge`
6969-- Don't push directly - coordinator handles pushing after merge
7070-7171-### Policy: Sync Before Starting Work
7272-7373-After your plan is approved and before starting implementation, **always rebase on main** to get the latest changes:
7474-7575-```bash
7676-jj rebase -d main
7777-```
7878-7979-This ensures you have the latest code and TODO.md state from other agents or the coordinator.
8080-8181-### Policy: Commits
8282-8383-- Ask before committing - don't commit automatically, but do offer to commit when work is done
8484-- User (dietrich ayala) is sole author of all commits
8585-8686-### Policy: Quality
8787-8888-Before marking any task as done:
8989-9090-1. **Tests** - Write tests for new functionality. Run all tests and ensure they pass.
9191-2. **Documentation** - Update relevant docs (README, API docs, etc.) if behavior changes.
9292-3. **Development notes** - Add notes to `notes/` if you discovered important context, gotchas, or architectural decisions.
9393-4. **Verify** - Run the build/lint/tests. Do NOT mark done if tests fail.
9494-9595-### Policy: Cleanup
9696-9797-When your task is complete, you MUST complete this checklist:
9898-9999-**1. Mark task complete in TODO.md**
100100-- Find your task in the Today section, change `- [~]` (in-progress) to `- [x]` (done)
101101-- Move to Done section under current week heading (`### YYYY-WNN`)
102102-103103-**2. Write development notes** (if applicable)
104104-- Add to existing file in `notes/` or create new one
105105-- Focus on what future developers need to know
106106-107107-**3. Record learnings** (if you discovered tips, gotchas, or patterns)
108108-- Create or append to `notes/agent-learnings.md` in your workspace
109109-- The coordinator will consolidate these after merging
110110-111111-**4. Squash your work**
112112-```bash
113113-jj squash -m "description of changes"
114114-```
115115-The coordinator will handle the actual merge with `mmerge`.
116116-117117-**5. Report completion**
118118-```bash
119119-agent-status "done" "summary of what you accomplished"
120120-```
121121-122122-**Do NOT skip these steps.** Never access files outside your workspace.
123123-124124----
125125-126126-## BEFORE REPORTING DONE
127127-128128-You MUST complete the cleanup checklist. Verify:
129129-- [ ] TODO.md updated: task changed from `[~]` to `[x]`, moved to Done section under `### 2026-WNN`
130130-- [ ] `jj squash -m "description"` run to squash your commits
131131-- [ ] `agent-status "done" "summary"` called
132132-133133-**Failure to update TODO.md means the task is not complete.**
134134-135135----
136136-137137-## Your Task: pull-to-refresh triggers sync in mobile app
138138-139139-Enter plan mode (use EnterPlanMode tool) and create a detailed implementation plan.
140140-Wait for my review before executing. Do NOT auto-execute.
···1313Today
1414- [ ][mobile] shared iOS build artifacts in ./tmp to avoid full rebuilds per workspace (one mobile task at a time)
1515- [ ][desktop] titlebar investigation and controls: why do some window.open links show titlebars? add universal hide/show pref, commands, and show on hover at top edge
1616-- [~][desktop] ensure yarn start always runs with correct better-sqlite3 build for Electron
1716- [ ][mobile] fix big bottom bar showing again
18171918Later
···423422424423### 2026-W04
425424425425+- [x][desktop] upgrade Electron to 40 + pin Node to 24 (ensure yarn start always runs with correct better-sqlite3)
426426- [x][mobile] pull-to-refresh gesture triggers sync
427427- [x][desktop] click-and-hold window dragging for frameless windows
428428- [x][desktop] fix better-sqlite3 node/electron version mismatch with postinstall script
···6677**Multi-Backend Architecture**: Peek supports multiple backends (Electron, Tauri) that can coexist and sync data. The `app/` directory is **backend-agnostic** and must not contain backend-specific code. Backend-specific code lives in `backend/{electron,tauri}/`.
8899+## Requirements
1010+1111+- **Node.js 24+** - Required for both desktop (Electron 40) and server
1212+- Install via `nvm install 24` or download from nodejs.org
1313+914## Key Commands
10151116### Development
1217```bash
1818+nvm use 24 # Ensure Node 24 is active
1319yarn install # Install dependencies
1420yarn debug # Run in development mode (with devtools)
1521yarn start # Start normally