@hienlh/ppm 0.7.26 → 0.7.28

package/docs/design-guidelines.md

@@ -14,6 +14,85 @@
 
 ---
 
+## Mobile-First UI Rules (MANDATORY)
+
+These rules MUST be followed when creating or modifying any UI component. PPM is primarily used on phones and tablets.
+
+### 1. Dialogs → Bottom Sheet on Mobile
+- **NEVER** use `<Dialog>` alone. All dialogs MUST render as bottom sheets on mobile (`md:` breakpoint).
+- Desktop (`md:` and above): centered dialog is fine
+- Mobile (below `md:`): full-width bottom sheet, slides up from bottom, max-height 85vh, rounded top corners
+- Pattern: use `hidden md:block` for desktop dialog, `md:hidden` for mobile bottom sheet, or a responsive wrapper
+
+### 2. No Hover States on Mobile
+- **NEVER** rely on `hover:` for essential interactions or information disclosure
+- Hover states are acceptable for desktop enhancement but must have a touch alternative
+- Use `active:` or `pressed` states for touch feedback instead
+- Action buttons hidden behind `hover:` MUST be always-visible on mobile (use `md:opacity-0 md:group-hover:opacity-100`)
+
+### 3. Touch Targets
+- Minimum touch target: **44×44px** (Apple HIG)
+- Minimum spacing between interactive elements: **8px**
+- Prefer `py-3 px-4` over `py-1 px-2` for buttons on mobile
+- Icon-only buttons: minimum `size-10` (40px) with padding
+
+### 4. Context Menus → Long-Press or Inline Actions
+- **NEVER** use right-click context menus as the only way to access actions on mobile
+- Use long-press (400ms) with `select-none` to prevent text selection
+- Or show inline action buttons that are always visible on mobile
+- Pattern: `useLongPress` hook for touch, `onContextMenu` for desktop
+
+### 5. Scrolling & Overflow
+- Lists MUST scroll independently, not the whole page
+- Use `overflow-y-auto` on scroll containers, not on body
+- Avoid horizontal scroll unless explicitly needed (tab bars)
+- Test that touch scrolling doesn't accidentally trigger tap actions
+
+### 6. Text & Spacing
+- Body text: minimum `text-sm` (14px) on mobile, `text-xs` (12px) only for metadata/labels
+- Line spacing: `leading-relaxed` for readability on small screens
+- Padding: `p-4` minimum for content areas on mobile, `p-2` acceptable for compact lists
+
+### 7. Layout Patterns
+- Mobile: single-column layout, full-width components
+- Desktop: multi-column, sidebars, split views
+- Use `flex-col md:flex-row` for responsive layouts
+- Sidebar content → drawer/bottom sheet on mobile
+
+### 8. Forms
+- Input fields: full width on mobile (`w-full`)
+- Labels above inputs, not beside (saves horizontal space)
+- Use native `<select>` or bottom sheet pickers on mobile, not custom dropdowns
+- Auto-focus first input on dialog/sheet open
+
+### 9. Thumb Zone — One-Handed Reachability
+- Primary actions (submit, confirm, navigate) MUST be in the **bottom 1/3** of the screen on mobile
+- Navigation bars → bottom, not top
+- Destructive/secondary actions can be in upper areas (harder to reach = harder to accidentally tap)
+- FABs (floating action buttons) → bottom-right corner
+- Avoid placing frequently-used buttons in top corners — unreachable with one thumb
+```
+┌─────────────────────┐
+│  ❌ Hard to reach    │  ← Secondary/rare actions only
+│                     │
+├─────────────────────┤
+│  ⚠️ Stretch zone    │  ← Content, read-only info
+│                     │
+├─────────────────────┤
+│  ✅ Thumb zone       │  ← Primary actions, navigation,
+│  Submit, confirm,   │     inputs, frequently-used buttons
+│  tab bar, FAB       │
+└─────────────────────┘
+```
+
+### 10. Existing Patterns to Follow
+- `MobileDrawer` (`src/web/components/layout/mobile-drawer.tsx`) — slide-in drawer for sidebar
+- `ProjectBottomSheet` (`src/web/components/layout/project-bottom-sheet.tsx`) — bottom sheet pattern
+- `useLongPress` in `git-status-panel.tsx` — long-press for context menus
+- `hidden md:block` / `md:hidden` — responsive show/hide pattern
+
+---
+
 ## UI Framework Stack
 
 ### Tailwind CSS 4.2

package/docs/project-roadmap.md

@@ -1,455 +1,179 @@
-# PPM Project Roadmap & Status
+# PPM Project Roadmap
 
-**Last Updated:** March 19, 2026
+**Last Updated:** March 22, 2026
 
-## Current Version: v2.0 (Complete v0.5.21)
+## Vision
 
-### Overall Progress: 95%
-
-Multi-project, project-scoped API refactor with improved UX, Monaco Editor, auto-title chat sessions.
-
----
-
-## Phase Breakdown
-
-### Phase 1: Project Skeleton ✅ Complete
-- Bun runtime setup, TypeScript configuration
-- CLI with Commander.js
-- Hono server basic structure
-- React frontend with Vite
-
-**Status:** Done (v1 foundation)
-
----
-
-### Phase 2: Backend Core ✅ Complete
-- Services: ProjectService, ConfigService, FileService, GitService
-- YAML-based project registry
-- Path traversal protection
-- Auth middleware (token-based)
-
-**Status:** Done, enhanced in v2
-
-**Latest Work (260315):**
-- Project-scoped API refactor: `/api/project/:name/*` routes
-- ProviderRegistry singleton pattern
-
----
-
-### Phase 3: Frontend Shell ✅ Complete
-- React layout (Sidebar, TabBar, MainArea)
-- Zustand stores (project, tab, file, settings)
-- Theme switcher (dark/light/system)
-- Mobile responsive navigation
-
-**Status:** Done, improved in v2
-
-**Latest Work (260315):**
-- Mobile nav refactor, tab bar auto-scroll
-- URL sync for project/tab/file state
-- Tab metadata persistence in localStorage
-
-**Latest Work (260317):**
-- Project Switcher Bar: 52px left sidebar with project avatars, drag-to-reorder
-- Project color customization (12-color palette or custom hex)
-- Mobile ProjectBottomSheet for project selection
-- Keep-alive workspace switching (hide/show instead of unmount, preserves xterm DOM)
-- Sidebar tab system: Explorer / Git / History tabs (removed projects/git-status tab types)
-- Smart project initials with collision detection (1-char, 2-char, or index fallback)
-
----
-
-### Phase 4: File Explorer & Editor ✅ Complete
-- FileTree component with directory expansion
-- Monaco Editor integration with syntax highlighting and IntelliSense
-- File read/write operations
-- Monaco diff viewer for git diffs
-
-**Status:** Done, CodeMirror fully removed (v0.5.17+)
-
-**Latest Work (260317):**
-- Migrated CodeMirror → Monaco Editor (@monaco-editor/react) for better syntax highlighting and diff viewer
-- Alt+Z keyboard shortcut for word wrap toggle in editor and diff viewer
-- Improved code completion and IntelliSense
-
-**Latest Work (260319):**
-- CodeMirror fully removed from codebase
-- Monaco Editor polishing for large file performance
+PPM is the **lightest path from phone to code** — a self-hosted, BYOK, multi-device web IDE with AI. No desktop app install needed. No subscription. Everything on your machine, accessible from any browser.
 
 ---
 
-### Phase 5: Web Terminal ✅ Complete
-- xterm.js integration
-- Bun native PTY (Bun.spawn with shell)
-- Terminal I/O via WebSocket
-- Resize handling (SIGWINCH)
-
-**Status:** Done
-
-**Latest Work:**
-- Multiple terminal sessions per project
-- Terminal session persistence in tabs
-
----
-
-### Phase 6: Git Integration ✅ Complete
-- GitService with simple-git
-- Status view (staged, unstaged, untracked)
-- Diff viewer (file-level and project-level)
-- Commit graph (Mermaid-based visualization)
-
-**Status:** Done
-
-**Latest Work (260315):**
-- Git staging UI improvements
-- Commit graph performance optimization
-- Branch list, PR URL detection
-
----
-
-### Phase 7: AI Chat ✅ Complete
-- Claude Agent SDK integration
-- Message streaming (async generators)
-- Tool use (file_read, file_write, git commands)
-- Tool approval flow
-
-**Status:** Done
-
-**Latest Work (260315):**
-- File attachments in chat
-- Slash command detection (/help, /git, /file)
-- Usage badge (token tracking)
-- Session management (save/load)
-
-**Latest Work (260319):**
-- Auto-generate session title from SDK summary on first message
-- Inline session rename in chat UI
-- Session history tab persistence
-
----
-
-### Phase 8: CLI Commands ✅ Complete
-- `ppm start` — Start server (foreground/daemon)
-- `ppm stop` — Graceful shutdown
-- `ppm open` — Launch browser
-- `ppm init` — Initialize config
-- `ppm projects {add,remove,list}` — Project management
-- `ppm config {get,set}` — Configuration
-- `ppm git {status,commit,branch}` — Git operations
-- `ppm chat {send,sessions,delete}` — Chat CLI
-
-**Status:** Done
-
----
-
-### Phase 9: Database Management ✅ Complete (260319)
-
-**Features:**
-- Unified database viewer for SQLite & PostgreSQL
-- DatabaseAdapter extensible pattern
-- Connection CRUD (create, edit, delete, color-code)
-- Query execution with readonly safety
-- Table browser with pagination & schema inspection
-- CLI support (ppm db commands)
-- Credentials stored securely in SQLite (never exposed in API)
-- readonly=true by default (safe-by-default)
-
-**Latest Work (260319):**
-- SQLiteAdapter & PostgresAdapter implementations
-- /api/db routes with connection sanitization
-- Database sidebar UI with connection form, color picker
-- TableCacheService for metadata caching & search
-- isReadOnlyQuery() CTE-safe safety checks
-- CLI db-cmd for database management
+## Completed Milestones
 
-**Status:** Complete, fully integrated with v0.6.3
+### v0.1–v0.5 — Foundation (Released)
+- Bun runtime, Hono server, React + Vite frontend
+- File explorer, Monaco editor, xterm.js terminal
+- AI chat (Claude Agent SDK), git integration, PWA
+- Multi-project, project-scoped API, CLI commands
+- Database management (SQLite/PostgreSQL)
 
----
-
-### Phase 10: PWA & Build ✅ Complete
-- Vite build configuration
-- Service worker (vite-plugin-pwa)
-- Offline support (cached assets)
-- Manifest.json (installable)
-- Binary compilation (`bun build --compile`)
+### v0.6 — Polish (Released)
+- Project Switcher Bar, keep-alive workspace switching
+- Auto-generate chat session titles, inline rename
+- Database adapters, connection UI, query execution
 
-**Status:** Done
+### v0.7 — Multi-Account & Mobile (Current — v0.7.25)
+- Multi-account credential management (OAuth + API key)
+- Account routing (round-robin, fill-first)
+- Usage tracking per account with visual dashboard
+- Account import/export with encryption + clipboard fallback
+- Mobile UX: horizontal tab scroll, long-press context menus, touch optimization
+- Cloudflare tunnel, push notifications, Telegram alerts
 
 ---
 
-### Phase 11: Testing ✅ In Progress (65%)
+## Upcoming Roadmap
 
-#### Unit Tests (50% complete)
-- [x] Mock provider tests
-- [x] ChatService tests
-- [x] ConfigService tests
-- [x] DbService tests (SQLite)
-- [ ] FileService tests
-- [ ] GitService tests
-- [x] Zustand store tests
-- [x] SessionLogService tests (redaction)
+### v0.8.0 — "Always On" (Q2 2026)
 
-#### Integration Tests (40% complete)
-- [x] Claude Agent SDK integration
-- [x] Chat WebSocket flow
-- [x] SQLite migration validation
-- [ ] Terminal WebSocket flow
-- [ ] Git operations
-- [ ] File operations
+**Theme:** Multi-device access + AI chat improvements. Solve the "I can't reach my PPM from my phone" problem.
 
-#### E2E Tests (0% — Planned for v3)
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **PPM Cloud** | Critical | Separate cloud service for device registry + tunnel URL sync. Google OAuth login. CLI `ppm cloud link` syncs tunnel URL. Open cloud dashboard on any device → see machines → tap to connect. NO code/data through cloud — only URLs + metadata. |
+| **Auto-start** | High | PPM starts on boot. macOS launchd, Linux systemd, Windows Task Scheduler. CLI: `ppm autostart enable/disable`. Required for "always accessible" story. |
+| **AI Chat enhancements** | High | Tool allow/deny config per session. Chat modes (plan/code/ask). Model selector (opus/sonnet/haiku). Effort level. Max turns. System prompt customization. Better streaming UX (collapsible tool calls). |
 
-**Status:** Making progress, good coverage for core services
+**PPM Cloud — scope guard:**
+- Cloud is OPTIONAL convenience, never a dependency. PPM works 100% without it.
+- Razor-thin: device registry + tunnel URL sync + heartbeat. Nothing more.
+- Hosting: Cloudflare Workers or Fly.io
+- CLI: `ppm cloud link`, `ppm cloud unlink`, `ppm cloud status`
+- Dashboard: list machines, status (online/offline), click to open
 
 ---
 
-## Known Issues & Gaps (v2)
-
-### Critical (Blocking)
-1. **Terminal on Windows** — Node-pty complexity; Bun PTY may not work
-   - Mitigation: Document Linux/macOS support, add Windows detection
-   - Fix: Evaluate node-pty or WSL fallback
-
-2. **Chat streaming cancellation** — Cancel button partially working
-   - Issue: Async generator hard to interrupt mid-stream
-   - Fix: Implement CancellationToken pattern
-
-### High Priority (Should Fix)
-3. **File path encoding** — Unicode filenames may break
-   - Fix: Validate UTF-8, handle encoding edge cases
-
-4. **Large file handling** — No streaming for large files (>10MB)
-   - Fix: Chunk file reads, show progress bar
+### v0.9.0 — "Open Platform" (Q2–Q3 2026)
 
-5. **Git performance** — `git log --graph` slow on large repos
-   - Fix: Limit graph depth, add pagination
+**Theme:** Multi-provider AI + extension system. Expand user base beyond Claude-only developers.
 
-### Medium Priority (Nice to Have)
-6. **Dark mode OLED** — No true black background
-   - Fix: Add separate OLED mode in settings
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **Multi-provider AI** | Critical | Refactor `ProviderInterface` for clean provider abstraction. Tiered support: Tier 1 (full agentic) = Claude Agent SDK; Tier 2 (chat + tools) = Gemini CLI, OpenAI Codex; Tier 3 (chat-only) = any OpenAI-compatible API. Clean base code for future Chinese providers (DeepSeek, Qwen). |
+| **Extension architecture** | High | Dynamic extension loading system. Extensions = npm packages exporting skills + optional UI panels. First extension: extract DB viewer from core. Extension API: register routes, UI panels, sidebar tabs, skills. Config: `"extensions": ["@ppm/ext-database", "@ppm/ext-docker"]`. |
+| **MCP Management** | Medium | UI to add/remove/configure MCP servers. Test connection. Per-project MCP overrides. Store in SQLite. Pass to Agent SDK via `mcpServers`. |
 
-7. **Keyboard shortcuts** — Limited shortcuts defined
-   - Fix: Add Cmd+K, Cmd+P (file search), Cmd+/ (comment)
+**Multi-provider — tiered approach:**
+- Tier 1 (full agentic): Claude Agent SDK — file edit, terminal, git, full autonomy
+- Tier 2 (chat + tools): Provider-specific CLIs (Gemini CLI, Codex) — agentic via their own tool system
+- Tier 3 (chat-only): Any OpenAI-compatible API — conversation only, no tools
+- Provider interface refactor is foundation work — do it clean now, avoid painful refactor later
 
-8. **Session persistence** — Chat history lost on server restart
-   - Fix: Persist sessions to filesystem or localStorage with IndexedDB
-
-9. **Collaborative editing** — No multi-user support
-   - Status: Planned for v3
-
-10. **Mobile terminal** — Terminal hard to use on small screens
-    - Fix: Optimize touch input, add virtual keyboard
+**Extension architecture — design principles:**
+- Extensions are npm packages: `ppm ext install @ppm/ext-database`
+- Extension manifest defines: skills, UI panels, sidebar tabs, routes, settings schema
+- DB viewer = first official extension, proves the architecture
+- Keep PPM core lightweight, features are opt-in via extensions
+- No marketplace yet (just npm), marketplace comes in v1.0
 
 ---
 
-## v2.0 Checklist
-
-- [x] Project-scoped API refactor
-- [x] Per-project chat sessions
-- [x] Per-project git operations
-- [x] Multi-tab UI with state persistence
-- [x] File attachments in chat
-- [x] Mobile responsive improvements
-- [x] URL sync for bookmarking/sharing
-- [x] Project Switcher Bar (52px sidebar, avatars, colors, reordering) (260317)
-- [x] Keep-alive workspace switching (preserve xterm DOM) (260317)
-- [x] Sidebar tab system (Explorer/Git/History/Database tabs) (260317, 260319)
-- [x] Monaco Editor migration (CodeMirror → Monaco, fully removed) (260317-260319)
-- [x] Project color customization (12-color palette + custom hex) (260317)
-- [x] Auto-generate chat session titles from SDK summary (260319)
-- [x] Inline session rename UI (260319)
-- [x] Database Management (SQLite/PostgreSQL, adapters, UI, CLI) (260319)
-- [x] SQLite migration (db.service.ts, backward YAML compat, connection tables v3) (260319)
-- [ ] Complete test coverage (65% complete)
-- [x] Documentation updates (260319)
-- [ ] Security audit (planned)
-
-**Release Status:** v0.6.3 released, v2.0 + database management complete
-
----
+### v0.10.0 — "Intelligence" (Q3 2026)
 
-## Upcoming Features (v3.0)
+**Theme:** PPM's own AI layer. Built-in bot + programmable skills.
 
-### Collaborative Editing (High Priority)
-- Real-time multi-user file editing
-- Cursor synchronization via WebSocket
-- Conflict resolution (OT or CRDT)
-- User presence indicators
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **PPM Skills API** | High | Stable internal API for AI to control PPM: file.read/write/search, terminal.run, git.status/commit/diff, db.query, editor.open/goto, project.switch. Skills are the bridge between AI and PPM features. |
+| **Built-in Clawbot** | High | Lightweight AI agent built into PPM using Anthropic Messages API (not Agent SDK). Uses Skills API + MCP tools. Instant response, no external CLI deps. For quick tasks: file search, code explanation, simple refactors. |
+| **Inline SQL** | Medium | Select text in Monaco → run as SQL. Connection picker in editor context menu. Results panel below editor. Leverages existing DB service. |
 
-**Estimated Effort:** 3 weeks
-**Dependencies:** CRDT library (yjs or automerge)
+**Built-in Clawbot — why it matters:**
+- Claude Agent SDK spawns subprocess — heavy, slow startup, requires CLI installed
+- Clawbot = instant, lightweight, works with any LLM via Messages API
+- Users can use Clawbot to create extensions → zero-friction extension authoring
+- Foundation for "AI creates extensions on demand" vision
 
 ---
 
-### Custom Tool Registry
-- Allow users to define custom AI tools (shell scripts, HTTP endpoints)
-- Tool UI generator based on JSON schema
-- Rate limiting and sandboxing
-
-**Estimated Effort:** 2 weeks
-**Dependencies:** JSON Schema library
+### v1.0.0 — "Production Ready" (Q4 2026)
 
----
+**Theme:** Enterprise, marketplace, stability.
 
-### Plugin Architecture
-- Load custom providers from npm or local plugins
-- Provider discovery and versioning
-- Hot-reload support
-
-**Estimated Effort:** 2 weeks
-**Dependencies:** Plugin loader (Rollup, Module Federation)
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **Self-hosted PPM Cloud** | High | Docker image of PPM Cloud for enterprise/team. Same codebase, self-hosted config flag. `docker-compose up` and it works. LDAP/SSO integration. |
+| **PPM Marketplace** | High | Publish/install/update extensions. Browse community extensions. Revenue sharing for paid extensions. Clawbot can create extension → test → publish in minutes. |
+| **Stability & hardening** | Critical | Security audit, performance optimization, comprehensive test coverage (>80%), documentation for contributors, CI/CD pipeline. |
 
 ---
 
-### Performance Profiling UI
-- Flamegraph viewer for CPU profiling
-- Memory allocation tracking
-- Network waterfall visualization
-
-**Estimated Effort:** 1 week
-**Dependencies:** Profiling library (speedscope, Clinic.js)
-
----
+## Post-v1.0 — Feature Backlog (To Be Prioritized)
 
-### Advanced Git Features
-- Interactive rebase UI
-- Cherry-pick/squash support
-- Stash management
-- Rebase conflict resolution
-- Submodule support
+Features to pick from after v1.0. Will be reviewed and scheduled based on user feedback and strategic priorities.
 
-**Estimated Effort:** 2 weeks
-**Dependencies:** Existing simple-git wrapper
+| Feature | Category | Description |
+|---------|----------|-------------|
+| **Collaborative viewing** | Social | Read-only live session sharing via tunnel. Others watch terminal/editor real-time. High demo value. |
+| **Workspace snapshots** | UX | Save/restore full state (open files, terminals, chat). Critical for mobile where browser kills tabs. |
+| **Ollama / local models** | AI | Run AI offline with local models. No API cost, privacy-first. Plugs into Clawbot as a provider. |
+| **Project templates** | DX | `ppm init --template react/nest/go`. Community templates from Marketplace. |
+| **AI command palette** | AI | Natural language commands ("deploy production", "run tests") → Skills API. |
+| **Notification hub** | UX | Push notification "AI task finished" on mobile. Webhook integrations (Slack, Discord). |
+| **Layout customization** | UX | User arranges panels freely. Save separate desktop vs mobile layouts. |
+| **Git advanced** | Git | Interactive rebase UI, cherry-pick, stash management, conflict resolution. |
+| **Performance profiling** | DevTools | Flamegraph viewer, memory tracking, network waterfall. |
+| **Multi-user workspace** | Enterprise | Shared project access, role-based permissions, team features. |
+| **Mobile terminal UX** | Mobile | Virtual keyboard shortcuts, gesture controls, better touch input. |
+| **CI/CD integration** | DevOps | GitHub Actions / pipeline status in PPM, trigger builds from UI. |
+| **Cross-platform binaries** | Distribution | Compile macOS/Linux/Windows binaries via `bun build --compile`. `npx ppm` without Bun. |
+| **OLED dark mode** | UX | True black background for OLED screens. |
+| **Collaborative editing** | Social | Real-time multi-user file editing with CRDT (yjs/automerge). |
 
 ---
 
-### Cross-Platform Distribution (Planned)
-- Compile platform-specific binaries via `bun build --compile` (macOS, Linux, Windows)
-- Publish npm package with wrapper script that auto-detects platform and downloads correct binary
-- Enables `npx ppm init` without requiring Bun on the target machine
-- CI/CD pipeline for automated multi-platform builds on release
+## Release Schedule
 
-**Estimated Effort:** 1 week
-**Dependencies:** CI/CD (GitHub Actions), npm publish pipeline
+| Version | Theme | Key Features | Target |
+|---------|-------|-------------|--------|
+| **v0.7** | Multi-Account & Mobile | Account management, usage tracking, mobile UX | ✅ Current |
+| **v0.8** | Always On | PPM Cloud, auto-start, AI chat enhancements | Q2 2026 |
+| **v0.9** | Open Platform | Multi-provider AI, extension architecture, MCP | Q2–Q3 2026 |
+| **v0.10** | Intelligence | Skills API, built-in Clawbot, inline SQL | Q3 2026 |
+| **v1.0** | Production Ready | Self-hosted Cloud, Marketplace, stability | Q4 2026 |
 
 ---
 
-### Cloud Sync (Future)
-- Optional cloud backup of chat sessions
-- Cross-device session sync
-- Settings synchronization
+## Strategic Principles
 
-**Estimated Effort:** 3 weeks
-**Dependencies:** Cloud storage API (AWS S3, Dropbox)
-**Note:** Single-machine only in v2; this would be v4+
+1. **Own "phone to code"** — PPM wins on multi-device access. Don't chase Cursor/Windsurf feature parity.
+2. **PPM Cloud stays razor-thin** — Device registry + tunnel URLs only. No code storage. No cloud execution.
+3. **Multi-provider is tiered** — Full agentic = Claude SDK. Other providers get appropriate tier. Clean interface for future providers.
+4. **Extensions keep core lightweight** — Features are opt-in. DB viewer, future tools = extensions. Core stays fast.
+5. **Clawbot enables the ecosystem** — Users create extensions with AI, publish to Marketplace. Zero-friction.
+6. **Self-hosted first, always** — Cloud is optional convenience. PPM works 100% offline/local.
 
 ---
 
 ## Technical Debt
 
-| Item | Priority | Effort | Notes |
-|------|----------|--------|-------|
-| Simplify ChatService streaming | Medium | 1d | Reduce async generator complexity |
-| Extract WebSocket common logic | Low | 1d | DRY principle for chat/terminal WS |
-| Improve error messages | Medium | 2d | More actionable error text |
-| Add request logging | Low | 0.5d | Debugging aid |
-| Refactor FileService validation | Low | 1d | Centralize path checks |
-| Remove unused provider fallbacks | Low | 0.5d | Clean up mock/claude-cli code |
-
----
-
-## Testing Coverage Targets
-
-| Area | Current | Target v2 | Target v3 |
-|------|---------|-----------|-----------|
-| **Services** | 60% | 90% | 95% |
-| **Routes** | 40% | 80% | 95% |
-| **Hooks** | 30% | 70% | 90% |
-| **Components** | 10% | 50% | 80% |
-| **Overall** | 35% | 75% | 90% |
-
----
-
-## Community & Contribution Roadmap
-
-### v2 (Current)
-- [ ] GitHub issue templates
-- [ ] Contribution guidelines (CONTRIBUTING.md)
-- [ ] Developer setup guide
-- [ ] Automated CI/CD (GitHub Actions)
-
-### v3
-- [ ] Plugin development guide
-- [ ] API documentation (OpenAPI/Swagger)
-- [ ] Example plugins repository
-- [ ] Community provider registry
-
----
-
-## Release Schedule (Target Dates)
-
-| Version | Status | Features | Target Date |
-|---------|--------|----------|-------------|
-| **v1.0** | Released | Single project, basic chat, terminal | Feb 28, 2025 |
-| **v2.0** | Complete (v0.6.3) | Multi-project, project-scoped API, improved UX, Monaco Editor, auto-title, database management | Mar 19, 2026 |
-| **v2.1** | Planned | Complete test coverage, SQLite finalization, bug fixes | Apr 15, 2026 |
-| **v3.0** | Planned | Collaborative editing, custom tools, plugins | Jun 30, 2026 |
-| **v4.0** | Planned | Cloud sync, advanced git, profiling UI | Sep 30, 2026 |
-
----
-
-## Success Metrics
-
-### Adoption (By v2 Release)
-- 10+ active users (internal + early adopters)
-- 100+ GitHub stars
-- 50+ questions/issues on GitHub
-
-### Performance
-- Server startup: <500ms
-- API response: <200ms (50th percentile)
-- WebSocket latency: <50ms
-- Frontend bundle: <800KB gzipped
-
-### Quality
-- Test coverage: >75%
-- Security vulnerabilities: 0
-- Critical bugs in v2: <3
-
-### Developer Experience
-- Time to first commit: <30 minutes
-- Documentation completeness: 90%
-- Contribution acceptance rate: >80%
+| Item | Priority | Notes |
+|------|----------|-------|
+| Refactor ProviderInterface for multi-provider | High | Foundation for v0.9 |
+| Simplify ChatService streaming | Medium | Reduce async generator complexity |
+| Extract WebSocket common logic | Low | DRY for chat/terminal WS |
+| Round-robin cursor bug in AccountSelector | Medium | Positional cursor not advancing correctly |
+| Windows terminal support | Medium | Evaluate node-pty or WSL fallback |
 
 ---
 
 ## Dependencies to Monitor
 
-| Dependency | Version | Risk | Monitoring |
-|-----------|---------|------|-----------|
+| Dependency | Version | Risk | Notes |
+|-----------|---------|------|-------|
 | Bun | 1.3.6+ | Medium | Check security advisories weekly |
-| Claude Agent SDK | 0.2.76+ | Low | Follow Anthropic releases for model updates |
-| React | 19.2.4 | Low | Monitor for breaking changes |
-| TypeScript | 5.9.3+ | Low | Plan upgrades quarterly |
-| xterm.js | 6.0 | Low | Check for terminal rendering bugs |
-| Monaco Editor | 4.7.0+ | Low | Monitor for accessibility improvements |
-
----
-
-## Q&A
-
-**Q: Why no cloud sync in v2?**
-A: Complexity & scope. Single-machine focus allows faster iteration. Cloud features are v4+ when user base justifies.
-
-**Q: When will Windows be fully supported?**
-A: Investigating Bun PTY behavior. Windows support likely in v3 pending testing.
-
-**Q: Can I self-host on a server?**
-A: Yes, but no user isolation. Each user would need their own instance. Multi-user hosting planned for v4.
-
-**Q: Will there be mobile apps (iOS/Android)?**
-A: Web PWA first (installed on home screen). Native apps only if there's strong demand.
-
-**Q: How do I contribute?**
-A: v2 first focuses on internal stability. Contribution guidelines coming in v2.1. For now, open issues for bugs/features.
-
+| Claude Agent SDK | 0.2.76+ | Medium | Follow for API changes, new features |
+| React | 19.2.4 | Low | Monitor breaking changes |
+| TypeScript | 5.9.3+ | Low | Quarterly upgrades |
+| xterm.js | 6.0 | Low | Terminal rendering bugs |
+| Monaco Editor | 4.7.0+ | Low | Accessibility improvements |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hienlh/ppm",
-  "version": "0.7.26",
+  "version": "0.7.28",
   "description": "Personal Project Manager — mobile-first web IDE with AI assistance",
   "author": "hienlh",
   "license": "MIT",