@peaske7/readit 0.1.8 → 0.2.1

package/.claude/CLAUDE.md

@@ -11,14 +11,24 @@ Inspired by [difit](https://github.com/yoshiko-pg/difit) - a local code review t
 ```bash
 # Development
 bun install           # Install dependencies
-bun dev               # Start dev server (Vite + CLI)
-bun run build         # Build for production
-bun run test          # Run tests
+bun dev               # Start dev server (CLI with --watch)
+bun run dev:client    # Start Vite dev server only
+bun run build         # Build for production (Vite + CLI)
+bun run test          # Run unit tests (Vitest)
+bun run test:e2e      # Run e2e tests (Playwright)
+bun run test:perf     # Run performance tests
+bun run bench         # Run benchmarks
 bun run typecheck     # Run TypeScript checks
 bun run check         # Run Biome (lint + format check)
 bun run check:fix     # Fix lint + format issues
 bun run format        # Format with Biome
 
+# Go server (production binary)
+make dev              # Go server + Vite HMR
+make build            # Build single binary (dist/readit)
+make test             # Run Go tests
+make clean            # Clean build artifacts
+
 # Usage
 bunx readit <file.md>               # Review Markdown file
 bunx readit <file.html>             # Review HTML file
@@ -29,6 +39,8 @@ bunx readit <file.md> --clean       # Clear existing comments
 
 bunx readit list                    # List all files with comments
 bunx readit show <file.md>          # Show comments for a file
+bunx readit open <files...>         # Add files to running server
+bunx readit completion zsh          # Output shell integration script
 ```
 
 ## Architecture
@@ -36,97 +48,126 @@ bunx readit show <file.md>          # Show comments for a file
 ```
 readit/
 ├── src/
-│   ├── cli/
-│   │   └── index.ts           # CLI entry point (Commander.js)
-│   ├── server/
-│   │   └── index.ts           # Bun.serve() server + API routes
+│   ├── cli.ts                 # CLI entry point (Commander.js)
+│   ├── server.ts              # Bun.serve() server + API routes
+│   ├── App.svelte             # Main Svelte component
+│   ├── main.ts                # Svelte entry point
+│   ├── schema.ts              # TypeScript types
+│   ├── template.ts            # HTML template rendering
+│   ├── index.css              # Tailwind styles + CSS custom properties
 │   ├── components/
-│   │   ├── Header.tsx
-│   │   ├── DocumentViewer.tsx # Renders MD (react-markdown) or HTML (IframeContainer)
-│   │   ├── IframeContainer.tsx # Isolated HTML rendering with comment support
-│   │   ├── CodeBlock.tsx      # Syntax-highlighted code blocks
-│   │   ├── CommentInputArea.tsx
-│   │   ├── CommentListItem.tsx # Comment item in manager dropdown
-│   │   ├── CommentManagerDropdown.tsx # Dropdown menu for managing comments
-│   │   ├── CommentMinimap.tsx # Visual minimap of comment positions
-│   │   ├── CommentNavigator.tsx # Navigate between comments
-│   │   ├── FloatingTOC.tsx    # Floating TOC button (fullscreen mode)
-│   │   ├── MarginNote.tsx     # Individual margin note
-│   │   ├── MarginNotesContainer.tsx
-│   │   ├── MermaidDiagram.tsx # Mermaid diagram rendering
-│   │   ├── RawCommentsModal.tsx # View raw .comments.md file
-│   │   ├── SettingsModal.tsx  # Settings modal (font preferences)
-│   │   ├── TableOfContents.tsx # Document headings navigation
-│   │   └── index.ts
-│   ├── hooks/
-│   │   ├── useComments.ts     # Comment state management
-│   │   ├── useCommentNavigation.ts # Navigate between comments
-│   │   ├── useDocument.ts     # Document fetching and state
-│   │   ├── useFontPreference.ts # Font preference with server persistence
-│   │   ├── useHeadings.ts     # Extract headings from document
-│   │   ├── useLayoutMode.ts   # Layout mode toggle (centered/fullscreen)
-│   │   ├── useReanchorMode.ts # Re-anchor mode for unresolved comments
-│   │   ├── useScrollMetrics.ts # Scroll position tracking
-│   │   ├── useScrollSpy.ts    # Track scroll position for TOC
-│   │   ├── useTextSelection.ts # Text selection handling
-│   │   └── index.ts
-│   ├── lib/
-│   │   ├── anchor.ts          # Anchor-based comment resolution
-│   │   ├── comment-storage.ts # File-based comment storage
-│   │   ├── context.ts         # LLM context extraction
-│   │   ├── export.ts          # Export utilities (JSON, prompt format)
-│   │   ├── layout-constants.ts # Layout dimensions and breakpoints
-│   │   ├── margin-layout.ts   # Margin note position resolution
-│   │   ├── scroll.ts          # Scroll calculation utilities
-│   │   ├── utils.ts           # Common utilities (cn, etc.)
-│   │   └── highlight/         # Text highlighting system
-│   │       ├── index.ts
-│   │       ├── highlighter.ts # Unified highlighter factory
-│   │       ├── core.ts        # Core highlight logic
-│   │       ├── dom.ts         # DOM manipulation
-│   │       ├── colors.ts      # Comment color palette
-│   │       ├── types.ts       # Type definitions
-│   │       └── script-builder.ts
-│   ├── types/
-│   │   └── index.ts           # Shared types
-│   ├── App.tsx                # Main React component
-│   ├── main.tsx               # React entry point
-│   └── index.css              # Tailwind styles
+│   │   ├── Header.svelte
+│   │   ├── DocumentViewer.svelte  # Renders document HTML
+│   │   ├── CommentInput.svelte    # Comment input area
+│   │   ├── CommentNav.svelte      # Navigate between comments
+│   │   ├── CommentListItem.svelte # Comment item in manager
+│   │   ├── CommentManager.svelte  # Comment management panel
+│   │   ├── CommentBadge.svelte    # Comment count badge
+│   │   ├── MarginNote.svelte      # Individual margin note
+│   │   ├── MarginNotesContainer.svelte
+│   │   ├── ActionsMenu.svelte     # Actions dropdown menu
+│   │   ├── InlineEditor.svelte    # Inline text editing
+│   │   ├── RawModal.svelte        # View raw .comments.md file
+│   │   ├── ReanchorConfirm.svelte # Re-anchor confirmation dialog
+│   │   ├── SettingsModal.svelte   # Settings modal
+│   │   ├── ShortcutCapture.svelte # Keyboard shortcut capture
+│   │   ├── ShortcutList.svelte    # Keyboard shortcuts list
+│   │   ├── TabBar.svelte          # Multi-file tab bar
+│   │   ├── TableOfContents.svelte # Document headings navigation
+│   │   └── ui/                    # Primitive UI components
+│   │       ├── ActionLink.svelte
+│   │       ├── Button.svelte
+│   │       ├── Dialog.svelte
+│   │       ├── DropdownMenu.svelte
+│   │       ├── DropdownMenuItem.svelte
+│   │       ├── DropdownMenuSeparator.svelte
+│   │       └── Text.svelte
+│   ├── stores/                # Svelte 5 reactive stores
+│   │   ├── app.svelte.ts      # Application state
+│   │   ├── settings.svelte.ts # User settings
+│   │   ├── shortcuts.svelte.ts # Keyboard shortcuts
+│   │   ├── locale.svelte.ts   # i18n state
+│   │   └── ui.svelte.ts       # UI state
+│   └── lib/
+│       ├── anchor.ts          # Anchor-based comment resolution
+│       ├── comment-storage.ts # File-based comment storage
+│       ├── export.ts          # Export utilities (JSON, prompt format)
+│       ├── headings.ts        # Heading extraction
+│       ├── html-text.ts       # HTML text extraction
+│       ├── margin-layout.ts   # Margin note position resolution
+│       ├── markdown-renderer.ts # Server-side markdown rendering
+│       ├── mermaid-renderer.ts  # Mermaid diagram rendering
+│       ├── mermaid-config.ts  # Mermaid configuration
+│       ├── mermaid-worker.ts  # Mermaid worker thread
+│       ├── positions.ts       # Position calculations
+│       ├── shortcut-registry.ts # Keyboard shortcut registry
+│       ├── utils.ts           # Common utilities (cn, etc.)
+│       ├── highlight/         # Text highlighting system
+│       │   ├── highlighter.ts # Highlight manager
+│       │   ├── highlight-registry.ts # Highlight registry
+│       │   ├── resolver.ts    # Highlight resolution
+│       │   ├── dom.ts         # DOM manipulation
+│       │   └── types.ts       # Type definitions
+│       └── i18n/              # Internationalization
+│           ├── index.ts
+│           ├── translations.ts
+│           ├── types.ts
+│           ├── en.ts          # English translations
+│           └── ja.ts          # Japanese translations
+├── go/                        # Go server (production binary)
+│   ├── cmd/readit/main.go     # Go CLI entry point
+│   └── internal/server/       # HTTP server, markdown, comments, SSE
+├── shell/                     # Shell integration
+│   ├── readit.zsh             # Zsh plugin (@ file picker + completions)
+│   └── _readit                # Zsh compdef completion function
+├── nvim-readit/               # Neovim plugin
+│   ├── lua/readit/init.lua    # Core plugin (server mgmt, commands, keymaps)
+│   ├── lua/readit/health.lua  # :checkhealth support
+│   └── plugin/readit.lua      # Auto-loader
+├── vscode-readit/             # VS Code extension
+│   └── src/                   # Extension source (TypeScript)
+├── e2e/                       # Playwright e2e tests
+├── docs/                      # Design docs and specs
 ├── dist/                      # Built output
 ├── .claude/                   # AI agent docs
 │   ├── user-stories.md
 │   ├── roadmap.md
 │   └── settings.json
+├── Makefile                   # Go build targets (make dev, make build)
 ├── CLAUDE.md                  # This file
-├── AGENTS.md                  # AI agent instructions
-└── CHANGELOG.md               # Version changelog
+└── AGENTS.md                  # AI agent instructions
 ```
 
 ## Key Design Decisions
 
-1. **react-markdown for Markdown**: Client-side rendering, no external dependencies
-2. **unified/rehype for HTML**: Safe HTML rendering with XSS protection via html-processor
-3. **IframeContainer for HTML isolation**: Renders HTML in sandboxed iframe to prevent style/script leakage
-4. **Margin notes UX**: Comments appear as margin notes next to highlighted text (Google Docs style)
-5. **File-based comments**: Human-readable `.comments.md` files stored in `~/.readit/comments/`
-6. **difit-style UX**: CLI → local server → browser, familiar pattern
-7. **Hooks for state**: Custom hooks for comment management
+1. **markdown-it for Markdown**: Server-side rendering with shiki for syntax highlighting
+2. **Mermaid for diagrams**: Server-side Mermaid diagram rendering
+3. **Margin notes UX**: Comments appear as margin notes next to highlighted text (Google Docs style)
+4. **File-based comments**: Human-readable `.comments.md` files stored in `~/.readit/comments/`
+5. **difit-style UX**: CLI → local server → browser, familiar pattern
+6. **Svelte 5 stores for state**: Reactive stores (`.svelte.ts`) for state management
+7. **i18n support**: English and Japanese translations
+8. **Live reload**: fs.watch() on documents + SSE push to browser; handles rename-style saves (Vim/Neovim/Emacs)
+9. **Editor integrations**: Neovim plugin (Lua), VS Code extension, shell completions with `@` fzf file picker
 
 ## Tech Stack
 
 - **Runtime**: Bun
 - **CLI**: Commander.js for argument parsing
-- **Server**: Bun.serve() for API and static files
-- **Markdown Rendering**: react-markdown
-- **HTML Rendering**: unified + rehype-parse + rehype-react (with XSS sanitization)
-- **Frontend**: React 19 + TypeScript + Vite
+- **Server**: Bun.serve() for API, SSE, and static files
+- **Markdown Rendering**: markdown-it (server-side) + shiki (syntax highlighting)
+- **Frontend**: Svelte 5 + TypeScript + Vite
 - **Styling**: Tailwind CSS v4
-- **Testing**: Vitest
+- **Icons**: lucide-svelte
+- **Testing**: Vitest (unit) + Playwright (e2e)
+- **Production Binary**: Go (embeds frontend via go:embed)
 - **Quality**: Biome (lint + format), lefthook
+- **Shell Integration**: Zsh/Bash/Fish completions, fzf-powered `@` file picker
+- **Editor Plugins**: Neovim (Lua), VS Code (TypeScript)
 
 ## Current Limitations
 
-- Comments use text offset, may break if document changes significantly
+- Comments use anchor-based text matching, may break if document changes significantly
 - No comment status tracking yet (resolved/unresolved planned for v0.3.0)
 
 ## User Stories
@@ -136,7 +177,8 @@ See `.claude/user-stories.md` for detailed user stories and acceptance criteria.
 ## Code Style
 
 - TypeScript strict mode
-- Functional React components with hooks
-- Tailwind for styling (no CSS-in-JS)
+- Svelte 5 components with reactive stores
+- Tailwind for styling
 - ESM modules throughout
-- Co-located test files (`*.test.ts`)
+- Co-located test files (`*.test.ts`, `*.bench.ts`)
+- E2E tests in `e2e/`

package/.claude/commands/review.md

@@ -78,7 +78,7 @@ Reference `.claude/rules/style-guide.md` for detailed examples.
 **For surface issues:**
 
 1. Fix silently after addressing fundamental issues
-2. Run `pnpm turbo run fix` to format
+2. Run `bun run check:fix` to format
 
 ## Anti-patterns to Flag
 

package/.claude/roadmap.md

@@ -3,17 +3,17 @@
 ## v0.1.0 - MVP ✅
 
 - [x] CLI with Commander.js
-- [x] react-markdown for Markdown rendering
-- [x] HTML file support with unified/rehype (XSS protection)
-- [x] Express server serving static files
-- [x] React 19 frontend with Tailwind CSS v4
+- [x] markdown-it for Markdown rendering (server-side with shiki syntax highlighting)
+- [x] HTML file support
+- [x] Bun.serve() server serving API + static files
+- [x] Svelte 5 frontend with Tailwind CSS v4
 - [x] Text selection → comment input
 - [x] Margin notes UI (Google Docs style)
 - [x] Highlight commented text with yellow background
 - [x] Copy All / Export JSON
 - [x] File-based comment persistence (`.comments.md` files)
 - [x] Copy for LLM feature (⌘⇧C) - copy selection/comment with surrounding context
-- [x] CLI subcommands: `list`, `show`
+- [x] CLI subcommands: `list`, `show`, `open`
 
 ## v0.2.0 - File-Based Comment Storage ✅
 
@@ -65,7 +65,7 @@ Review documents, add comments, then resolve one-by-one with LLM assistance.
 ## v0.4.0 - Visual Enhancements ✅
 
 - [x] Highlight commented text in document (moved to v0.1.0)
-- [x] Syntax highlighting for code blocks (react-syntax-highlighter)
+- [x] Syntax highlighting for code blocks (shiki, server-side)
 - [x] Click highlight → scroll to margin note
 - [x] Click margin note → scroll to highlighted text
 - [x] Mermaid diagram rendering
@@ -82,13 +82,36 @@ Review documents, add comments, then resolve one-by-one with LLM assistance.
 - [ ] Filter by category
 - [ ] Category in export format
 
-## v0.6.0 - Multi-file Support
+## v0.6.0 - Multi-file Support (Partial ✅)
 
 - [ ] Glob pattern support (`readit docs/*.md`)
-- [ ] File navigation sidebar
-- [ ] Per-file comment storage
+- [x] Multiple file arguments (`readit file1.md file2.md`)
+- [x] Directory scanning (`readit <dir>`)
+- [x] `readit open <files...>` to add files to running server
+- [x] File tab navigation (TabBar.svelte)
+- [x] Per-file comment storage
 - [ ] Bulk export across files
 
+## v0.7.0 - Shell Integration & Editor Plugins ✅
+
+- [x] Zsh integration with `@` file autocomplete (fzf-powered, Forge Code-style)
+  - [x] `@<TAB>` launches fzf picker for markdown files
+  - [x] `@partial<TAB>` pre-filters fzf query
+  - [x] Syntax highlighting for `@*.md` patterns in command line
+  - [x] Standard compdef completion for subcommands and options
+  - [x] Bash and Fish completion scripts via `readit completion`
+- [x] Neovim plugin (`nvim-readit/`)
+  - [x] Server lifecycle management (start/stop/discover)
+  - [x] `:ReaditOpen`, `:ReaditStop`, `:ReaditStatus`, `:ReaditReload`, `:ReaditList` commands
+  - [x] Configurable keymaps (`<leader>r` prefix by default)
+  - [x] `:checkhealth readit` support
+  - [x] Auto-cleanup on VimLeavePre
+- [x] Enhanced live reload on file changes
+  - [x] Handle `rename` events (Vim/Neovim write-to-temp-then-rename saves)
+  - [x] Auto re-establish watcher after rename with retry logic
+  - [x] SSE auto-reconnect with exponential backoff
+  - [x] Parallel document + comments fetch on reload
+
 ## Future Considerations
 
 - Sticky notes (ペタペタ) - add notes not tied to text selection

package/.claude/user-stories.md

@@ -11,7 +11,7 @@
 **Acceptance Criteria:**
 
 - Run `readit document.md` or `readit document.html` and browser opens with rendered content
-- react-markdown for Markdown, unified/rehype for HTML (client-side rendering)
+- markdown-it for Markdown (server-side rendering with shiki syntax highlighting)
 - Clean light theme with good typography for reading
 
 ---
@@ -153,20 +153,20 @@
 
 ---
 
-### US-010: Review Multiple Files
+### US-010: Review Multiple Files ✅
 
-**As a** reviewer  
-**I want to** review multiple Markdown files in one session  
-**So that** I can review an entire document set  
+**As a** reviewer
+**I want to** review multiple Markdown files in one session
+**So that** I can review an entire document set
 
 **Acceptance Criteria:**
 
-- `readit docs/*.md` opens multi-file view
-- File tabs or sidebar navigation
+- ~~`readit docs/*.md` opens multi-file view~~ `readit file1.md file2.md` or `readit <dir>` opens multi-file view
+- File tabs or sidebar navigation (TabBar.svelte)
 - Comments stored per file
 - Bulk export across all files
 
-**Status:** Not implemented
+**Status:** Implemented (multi-file args, directory scanning, `open` command, tab bar UI). Glob patterns not yet supported.
 
 ---
 
@@ -205,6 +205,61 @@
 
 ---
 
+### US-013: Shell Integration with File Autocomplete ✅
+
+**As a** CLI user
+**I want to** autocomplete markdown file paths with `@<TAB>` in my shell
+**So that** I can quickly find and open documents without typing full paths
+
+**Acceptance Criteria:**
+
+- `readit @<TAB>` launches fzf picker for markdown files in cwd
+- `readit @partial<TAB>` pre-filters the picker with "partial" as query
+- Standard Tab completion works for subcommands and options
+- `readit completion zsh|bash|fish` outputs shell-specific setup scripts
+- `eval "$(readit completion zsh)"` installs everything in one line
+
+**Status:** Implemented (v0.7.0)
+
+---
+
+### US-014: Neovim Plugin ✅
+
+**As a** Neovim user
+**I want to** render and review markdown documents directly from my editor
+**So that** I can stay in my editing workflow while reviewing
+
+**Acceptance Criteria:**
+
+- `:ReaditOpen` starts server and opens current buffer in browser
+- `:ReaditStop` stops the server
+- `:ReaditReload` saves buffer and triggers browser refresh
+- `:ReaditStatus` shows server info
+- Configurable keymaps (default `<leader>r` prefix)
+- Server auto-cleanup on VimLeavePre
+- `:checkhealth readit` verifies dependencies
+
+**Status:** Implemented (v0.7.0)
+
+---
+
+### US-015: Live Reload on File Changes ✅
+
+**As a** reviewer
+**I want to** see the browser update automatically when I edit the source document
+**So that** I can see my changes reflected in real time
+
+**Acceptance Criteria:**
+
+- Browser updates within ~200ms of file save
+- Works with Vim/Neovim saves (write-to-temp-then-rename pattern)
+- SSE connection auto-reconnects if server restarts (exponential backoff)
+- Document HTML and comments fetched in parallel for fast reload
+
+**Status:** Implemented (enhanced in v0.7.0, base SSE existed since v0.1.0)
+
+---
+
 ## Technical Stories
 
 ### TS-001: CLI Argument Parsing
@@ -217,18 +272,22 @@
 
 ### TS-002: Server Architecture
 
-- Express server serves API + static files
-- `/api/document` returns `{ content, type, filePath, fileName, clean }`
-- `/api/heartbeat` SSE for browser disconnect detection
-- Development mode proxies to Vite
+- Bun.serve() serves API + static files
+- `/api/documents` list and add documents
+- `/api/document` fetch individual document HTML and headings
+- `/api/comments` CRUD operations for comments
+- `/api/settings` get/update user settings
+- `/api/heartbeat` SSE for browser connection tracking
+- `/api/document/stream` SSE for document updates (live reload)
+- Development mode proxies to Vite dev server
 - Production mode serves built assets from dist/
 
 ### TS-003: Build System
 
 - Vite for frontend bundling
-- tsup for CLI bundling
-- Single `npm run build` produces complete distributable
-- `npx readit` works without global install
+- `bun build` for CLI bundling (target bun, ESM)
+- Single `bun run build` produces complete distributable
+- `bunx readit` works without global install
 
 ### TS-004: File-Based Comment Storage
 
@@ -246,3 +305,29 @@
 
 - API endpoints: `GET/POST/PUT/DELETE /api/comments` for CRUD operations
 - Watch file for external changes (optional)
+
+### TS-005: Shell Integration Architecture
+
+- `shell/_readit` - Standard zsh compdef for subcommands, options, file args
+- `shell/readit.zsh` - Rich widget: `@` prefix triggers fzf markdown file picker
+- Uses `fd` for fast file listing, falls back to `find`
+- fzf with bat/head preview, initial query from text after `@`
+- `readit completion zsh|bash|fish` CLI subcommand outputs setup scripts
+- Bash completion via `complete -F`, Fish via `complete -c`
+
+### TS-006: Neovim Plugin Architecture
+
+- `nvim-readit/lua/readit/init.lua` - Core: setup, server management, commands, keymaps
+- `nvim-readit/plugin/readit.lua` - Auto-loader on markdown FileType
+- `nvim-readit/lua/readit/health.lua` - `:checkhealth` module
+- Discovers existing servers via `~/.readit/server.json`
+- Starts server with `jobstart()`, attaches files via `POST /api/documents`
+- Communicates with server via curl (non-blocking `jobstart`)
+
+### TS-007: File Watcher Resilience
+
+- `fs.watch()` with both `"change"` and `"rename"` event handling
+- On rename: retry loop (10 attempts, 200ms apart) to re-establish watcher
+- Debounced re-render (200ms) to avoid thrashing on rapid saves
+- SSE auto-reconnect with exponential backoff (1s -> 30s max)
+- Parallel fetch of document HTML + comments on reload

package/AGENTS.md

@@ -4,57 +4,61 @@ Instructions for AI coding agents working on this project.
 
 ## Project Context
 
-readit is a CLI tool for reviewing Markdown documents with inline comments. The workflow is:
+readit is a CLI tool for reviewing Markdown and HTML documents with inline comments. The workflow is:
 
 1. User runs `readit document.md`
-2. CLI converts Markdown to HTML using Pandoc
-3. Express server starts and opens browser
+2. Server renders Markdown to HTML (markdown-it + shiki for syntax highlighting)
+3. Bun.serve() starts and opens browser with Svelte 5 frontend
 4. User selects text and adds comments
-5. Comments are saved to localStorage
+5. Comments are saved as `.comments.md` files in `~/.readit/comments/`
 6. User can export comments for AI or apply back to Markdown
 
 ## Development Commands
 
 ```bash
-pnpm install          # Install dependencies
-pnpm dev              # Start development (Vite + CLI hot reload)
-pnpm build            # Build for production
-pnpm test             # Run tests
-pnpm typecheck        # TypeScript check
-pnpm check            # Biome lint + format check
-pnpm check:fix        # Fix issues
-pnpm format           # Format code
+bun install           # Install dependencies
+bun dev               # Start development (CLI with --watch)
+bun run dev:client    # Start Vite dev server only
+bun run build         # Build for production (Vite + CLI)
+bun run test          # Run unit tests (Vitest)
+bun run test:e2e      # Run e2e tests (Playwright)
+bun run typecheck     # TypeScript check
+bun run check         # Biome lint + format check
+bun run check:fix     # Fix lint + format issues
+bun run format        # Format code with Biome
 ```
 
 ## Code Organization
 
-- `src/cli/` - CLI entry point, argument parsing
-- `src/server/` - Express server, Pandoc integration
-- `src/components/` - React UI components
-- `src/hooks/` - Custom React hooks
-- `src/lib/` - Utility functions
-- `src/types/` - TypeScript types
+- `src/cli.ts` - CLI entry point (Commander.js)
+- `src/server.ts` - Bun.serve() server + API routes
+- `src/components/` - Svelte 5 UI components
+- `src/stores/` - Svelte 5 reactive stores (`.svelte.ts`)
+- `src/lib/` - Utility functions, rendering, i18n
+- `src/schema.ts` - TypeScript types
+- `shell/` - Zsh/Bash/Fish completions and `@` file picker widget
+- `nvim-readit/` - Neovim plugin (Lua)
+- `vscode-readit/` - VS Code extension
 
 ## Testing
 
-- Tests are co-located with source files (`*.test.ts`)
-- Use Vitest for testing
-- Run `pnpm test` before committing
+- Unit tests are co-located with source files (`*.test.ts`)
+- E2E tests live in `e2e/` (Playwright)
+- Run `bun run test` before committing
 
 ## Commit Guidelines
 
 - Use conventional commits (feat:, fix:, docs:, etc.)
 - Keep commits focused and atomic
-- Run `pnpm typecheck && pnpm check` before committing
+- Run `bun run typecheck && bun run check` before committing
 
 ## Adding Features
 
 1. Check `.claude/user-stories.md` for planned features
-2. Update types in `src/types/` first
-3. Create/update hooks if needed
-4. Create/update components
+2. Update types in `src/schema.ts` first
+3. Create/update stores if needed (`src/stores/`)
+4. Create/update Svelte components (`src/components/`)
 5. Add tests
-6. Update CHANGELOG.md
 
 ## Key Files to Review
 

package/Makefile

@@ -0,0 +1,32 @@
+.PHONY: dev build build-client build-server test test-client test-e2e clean
+
+# Development: Go server manages Vite child process
+dev:
+	cd go && go run ./cmd/readit -- --dev $(ARGS)
+
+# Production build: frontend first, then Go embeds it
+build: build-client build-server
+
+build-client:
+	bunx vite build
+
+build-server: build-client
+	rm -rf go/internal/server/dist
+	mkdir -p go/internal/server/dist
+	cp -r dist/. go/internal/server/dist/
+	cd go && go build -o ../dist/readit ./cmd/readit
+
+# Tests
+test:
+	cd go && go test ./...
+
+test-client:
+	bun run test
+
+test-e2e:
+	bun run test:e2e
+
+clean:
+	rm -rf dist go/internal/server/dist
+	mkdir -p go/internal/server/dist
+	touch go/internal/server/dist/.gitkeep