---
stepsCompleted: [step-01-init, step-02-discovery, step-02b-vision, step-02c-executive-summary, step-03-success, step-04-journeys, step-05-domain-skipped, step-06-innovation, step-07-project-type, step-08-scoping, step-09-functional, step-10-nonfunctional, step-11-polish, step-12-complete]
inputDocuments:
  - "product-brief-gitpulse.md"
  - "product-brief-gitpulse-distillate.md"
  - "market-git-dashboard-ia-research-2026-04-24.md"
workflowType: 'prd'
documentCounts:
  briefs: 2
  research: 1
  projectDocs: 0
classification:
  projectType: desktop_app
  domain: general
  complexity: low
  projectContext: greenfield
---

# Product Requirements Document - GitPulse

**Author:** Ramez
**Date:** 2025-04-25

## Executive Summary

GitPulse is a local-first, open source desktop application that serves as the multi-repository command center for developers managing five or more Git repositories on a single machine. It automatically discovers all Git repos on disk, presents their status in a unified visual dashboard, enables batch git operations, and provides model-agnostic AI insights — all without requiring a login, configuration file, or cloud connection.

**Target users:** Indie developers, freelances, and power users managing 10-50+ repositories across client work, open source contributions, and personal projects. These developers lose significant time daily to manual `git status` checks, forgotten pushes, stale branches, and the cognitive overhead of tracking repository state across directories.

**The problem:** No open source tool combines automatic disk discovery, a visual multi-repo dashboard, batch git operations, and AI-powered insights in a performant, cross-platform, zero-configuration package. GitKraken (Electron, paid, 3.1/5 rating) paywalls private repos. GitButler ($17M raised, Tauri/Rust) is single-repo by design and Fair Source licensed. lazygit and gita offer no visual dashboard. The niche is empty.

**The product:** Built on Tauri v2 with a Rust backend and React frontend, GitPulse delivers a ~15 MB binary with <200 MB RAM. The AI layer is model-agnostic — users bring their own intelligence via Ollama (local, private) or cloud APIs (Gemini, DeepSeek, OpenAI, Anthropic). Privacy is the default; cloud is the opt-in, with a clear visual indicator showing data flow mode. The system tray agent provides passive monitoring without requiring the dashboard to be open.

### What Makes This Special

1. **Model-agnostic AI infrastructure.** Unlike GitKraken (Gemini-only) or GitButler (Claude-only), GitPulse lets developers choose their AI engine per task — Ollama for private commit messages, DeepSeek for cost-effective analysis, Gemini for complex reasoning. The product provides the plumbing; the user provides the intelligence.

2. **Zero-friction onboarding.** From download to full dashboard in under 30 seconds. No sign-up, no token, no network, no configuration. The first scan — seeing all repositories appear instantly — is the primary conversion moment. Every competitor gates value behind auth flows or manual setup.

3. **Structural performance moat.** Tauri + Rust produces binaries 10-15x smaller and 3-5x less memory-hungry than Electron competitors. This is architectural — competitors would need to rebuild from scratch to match it.

4. **Truly open source (MIT/Apache).** GitButler's Fair Source license prohibits building competitors and is not OSI-approved. GitPulse's MIT/Apache licensing allows forking, commercial use, and community trust — a genuine adoption accelerator in the open source ecosystem.

5. **Complementary to AI IDEs.** Cursor, Copilot, and Windsurf solve intra-repo productivity. GitPulse solves inter-repo visibility. Developers use both without conflict — eliminating the "us vs. the giants" positioning trap.

## Project Classification

| Attribute | Value |
|-----------|-------|
| **Project Type** | Desktop Application (Tauri v2 + React + Rust) |
| **Domain** | Developer Productivity / Developer Infrastructure |
| **Complexity** | Low (no regulatory requirements; complexity is technical, not compliance-driven) |
| **Project Context** | Greenfield — new product, no existing system |
| **License** | MIT/Apache (truly open source) |
| **Target Platforms** | Windows, macOS, Linux |

## Success Criteria

### User Success

**The 5-Second Wow:** From launch to a fully populated dashboard in under 30 seconds. No login, no config, no wizard — just instant visibility. This is the primary conversion moment. If the first scan doesn't delight, nothing else matters.

**Measurable Success Signals:**
- Average repos scanned per user > 10 (validates the multi-repo problem exists for this user)
- Batch operation used within first session (validates the "command center" value proposition)
- Smart Status consulted > 3 times per session (validates AI layer adds real value)
- System tray notification acted upon within 24 hours (validates passive monitoring utility)
- At least 2 AI backends configured per active user (validates model-agnostic approach)

**Emotional Success:**
- *Monday morning relief:* "I can see exactly which repos need attention" replaces the dread of 23 `git status` commands
- *Control feeling:* "I know the state of all my code" replaces anxiety about forgotten pushes and stale branches
- *Trust moment:* "My code never leaves my machine" (local mode badge) establishes the privacy foundation

### Business Success

| Timeframe | Metric | Target |
|-----------|--------|--------|
| **Month 3** | GitHub stars | 500+ |
| **Month 3** | Monthly active users | 500+ |
| **Month 3** | Cumulative downloads | 2,000+ |
| **Month 3** | Hacker News Show HN score | 200+ upvotes |
| **Month 6** | GitHub stars | 2,000+ |
| **Month 6** | Monthly active users | 2,000+ |
| **Month 6** | Paying subscribers (cloud tier) | 50 |
| **Month 6** | D30 retention | 40%+ |
| **Month 12** | GitHub stars | 5,000+ |
| **Month 12** | Monthly active users | 10,000+ |
| **Month 12** | Paying subscribers | 200 |
| **Month 12** | MRR | $1,500+ |
| **Month 12** | D30 retention | 50%+ |

**Fundraising trigger:** Seed round ($1–2M) if 5,000 MAU + 3% free-to-cloud conversion by month 9.

### North Star & KPIs

**North Star KPI:** Monthly active users who scan 10+ repositories (validates both adoption and problem-solution fit).

**Secondary KPIs:**
- D7 retention > 30%, D30 retention > 40% (product stickiness)
- Batch operations per session > 1 (power feature adoption)
- Smart Status engagement rate > 50% of sessions (AI value validation)
- System tray notification action rate > 60% (passive monitoring value)
- GitHub star-to-download ratio > 0.25 (organic enthusiasm signal)

**Technical performance targets** are defined in the Non-Functional Requirements section (NFR1–NFR8).

## Product Scope & Phased Development

### MVP Strategy

**Approach: Problem-Solving MVP** — deliver the core "repo visibility" problem solved in 30 seconds, then layer intelligence and automation on top.

- The first scan IS the product. If it doesn't delight, nothing else matters.
- AI is a progressive enhancement, never a dependency. The product works perfectly without it.
- Zero-friction is non-negotiable. Every config step or login screen is a conversion killer.
- Cross-platform from day 1 — the target audience (indie devs, freelancers) is platform-diverse.
- **Resource assumption:** Solo developer with potential community contributors post-launch. MVP designed for one-person execution over 2-3 months.

### Phase 1 — MVP Core (Weeks 1-6)

- Weeks 1-2: Rust backend — disk scanner, git status parser, Tauri scaffolding
- Weeks 3-4: React frontend — Card Grid, List View, batch operations UI
- Weeks 5-6: System tray + Ollama integration + privacy indicator + packaging
- **Delivers:** Auto-scan + Dashboard + Batch Ops + System Tray + Smart Status (Ollama) + Zero-config launch

### Phase 1.5 — MVP Complete (Weeks 7-10)

- Cloud AI integration (Gemini, DeepSeek, OpenAI, Anthropic)
- Dormancy detection, `.gitpulseignore` refinements
- Code signing for Windows/macOS, i18n framework scaffolding
- **Delivers:** Full MVP as originally scoped — all Day 1 features

**Must-have capabilities for Day 1 launch:**

| Capability | Why Must-Have |
|------------|---------------|
| Auto disk scan | Core value proposition — no scan, no product |
| Card Grid view | Primary visual interface for pattern recognition |
| List View with batch ops | Differentiator vs single-repo tools |
| Per-repo error reporting | Batch ops fail partially — silent failures destroy trust |
| System tray agent | Passive monitoring = sustained engagement |
| Smart Status (Ollama) | "Wow" moment — AI-generated health summaries |
| Privacy indicator | Trust foundation — shows data flow mode |
| Zero-config launch | Conversion moment — 30 seconds to value |
| Cross-platform (Win/Mac/Linux) | Target audience is platform-diverse |
| `.gitpulseignore` | Privacy control — exclude sensitive repos |

**Nice-to-have for Day 1 (cut if timeline pressure):**

| Capability | Rationale | Target |
|------------|-----------|--------|
| Cloud AI (4 providers) | Ollama covers core AI use case | Phase 1.5 |
| Dormancy detection | Useful but not conversion-critical | Phase 1.5 |
| i18n framework | English sufficient for launch | Phase 2 |

### Phase 2 — Growth (Months 4-6)

- Repository grouping, tagging, workspace contexts
- Advanced Smart Status: cross-repo dependency detection
- File watcher for real-time status updates
- Git worktree integration, CLI companion (`gitpulse-cli`)
- Premium cloud tier: multi-machine sync, team analytics

### Phase 3 — Expansion (Months 7-12)

- Inter-repository dependency graph visualization, MCP support
- Autonomous AI agents for code review and anomaly detection
- GitHub/GitLab integration (PRs, issues, CI status)
- Enterprise tier: SSO, compliance dashboards, audit trails

### Explicitly Out of MVP

Cloud sync/team collaboration, built-in code editor/diff viewer, merge conflict resolution UI, CI/CD integration, GitHub/GitLab API integration (issues, PRs, CI), mobile companion, enterprise features (SSO, compliance, audit logs). Telemetry: opt-in only with clear disclosure.

### Risk Mitigation

**Technical:**

| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| Scan performance on slow/network drives | Medium | High | Benchmark early (week 2); async scan with progress; scan timeout |
| Tauri v2 tray inconsistencies across platforms | Medium | Medium | Use stable tray API; test all 3 platforms weekly |
| Ollama model loading times | Low | Medium | Smart Status runs async — don't block dashboard |
| Large repo count (100+) UI perf | Medium | Medium | Virtualized list/grid rendering from day 1 |
| SmartScreen/code signing friction | High | High | Budget for signing cert ($200-500/yr); prioritize in Phase 1.5 |

**Market:**

| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| GitButler ships multi-repo first | Low | High | First-mover speed; model-agnostic as durable differentiator |
| No adoption (tooling fatigue) | Medium | High | Zero-friction is the moat; Show HN as primary launch |
| AI features perceived as gimmick | Medium | Medium | Deterministic fallback always available |
| Provider API changes break integration | Medium | Low | Abstract AI behind provider interface |

**Resource:**

| Risk | Probability | Impact | Mitigation |
|------|------------|--------|------------|
| Solo dev bandwidth — all platforms | Medium | High | Tauri handles cross-platform; test all OS weekly |
| Burnout from scope creep | Medium | High | Strict Phase 1/1.5 boundary; cut cloud AI to 1.5 if needed |
| Post-launch support drain | High | Medium | GitHub Issues triage; community contribution guidelines from day 1 |

## Innovation & Novel Patterns

### Detected Innovation Areas

**1. Model-Agnostic AI Plumbing for Git (Primary Innovation)**

No git tool offers per-task AI engine selection. GitKraken locks to Gemini. GitButler locks to Claude. GitPulse provides the plumbing — the user provides the intelligence. Per-task routing (Ollama for routine commits, cloud for complex analysis) is unprecedented in this category.

*Assumption challenged:* A git tool must choose its AI provider for the user. GitPulse: the user chooses per task.
*Validation:* Users configuring 2+ AI backends (Success Criteria metric).

**2. Vacant Quadrant — Auto-Discovery + Dashboard + Batch + AI**

No open source tool occupies the intersection of automatic disk discovery, multi-repo visual dashboard, batch git operations, and AI-powered insights. This is a first-mover position, not incremental improvement.

*Assumption challenged:* Developers don't need a dedicated multi-repo tool — shell scripts and CLI suffice. GitPulse: instant visual visibility fundamentally changes the experience.
*Validation:* D7 retention > 30% validates visibility as a game-changer.

**3. Multi-Level Privacy Indicator**

The visual badge switching between "Your code never leaves your machine" (Ollama) and "Cloud — data transits to [provider]" is novel UX. No competitor offers this transparency. Aligns with post-Copilot data policy momentum (April 2025).

*Assumption challenged:* Developers trust tools by default. GitPulse: in a post-Copilot world, trust is earned through explicit transparency.
*Validation:* If local mode remains most-used even when cloud keys are configured, privacy-first hypothesis is validated.

**4. Zero-Friction as Architectural Competitive Advantage**

No login, no config, no wizard. The first scan is the conversion moment. Made possible by Tauri + Rust architecture (<30 seconds total). Electron competitors physically cannot deliver this experience.

*Assumption challenged:* Guided onboarding improves retention. GitPulse: retention comes from instant value, not hand-holding.
*Validation:* Time from download to first batch operation < 2 minutes.

### Validation Approach

| Innovation | Validation Method | Success Signal |
|------------|-------------------|----------------|
| Model-agnostic AI | Track backend configuration count per user | 2+ backends per active user |
| Vacant quadrant | D7/D30 retention + repos scanned per user | D7 > 30%, avg repos > 10 |
| Privacy indicator | Local vs cloud usage ratio | Local mode dominant even with cloud configured |
| Zero-friction | Time-to-first-action measurement | < 2 minutes download to first batch op |

### Innovation Risk Mitigation

| Risk | Mitigation |
|------|------------|
| Model-agnostic too complex to configure | Smart defaults: Ollama auto-detected, cloud as opt-in guided setup |
| Users stay in "no AI" mode | Smart Status works in deterministic mode — AI is enhancement, not dependency |
| Performance degrades at 100+ repos | Lazy loading, pagination, incremental scan |
| GitButler adds multi-repo | First-mover + MIT/Apache vs Fair Source + model-agnostic as durable differentiator |

## User Journeys

### Journey 1: Sarah's Monday Morning (Indie Dev — Happy Path)

**Persona:** Sarah, 32, freelance full-stack developer. She juggles 23 repositories: 8 client projects, 6 open source contributions, 5 personal experiments, and 4 configuration/utility repos. She context-switches daily and routinely loses track of uncommitted changes.

**Opening Scene:** Monday 9 AM. Sarah sits down with coffee, dreading the ritual of checking each repo. She's been burned before — last month she lost 3 hours of work in a client repo because she forgot to push before switching machines.

**Rising Action:** She launches GitPulse for the first time. No login screen. No setup wizard. The binary opens instantly and begins scanning her home directory. In under 30 seconds, 23 tiles populate the dashboard — each showing branch name, status color (green/yellow/red), ahead/behind count, and last commit timestamp.

**Climax:** Three tiles immediately catch her eye:
- `client-acme-app` — yellow, "3 uncommitted changes, last activity Friday 6 PM"
- `oss-contrib-lib` — red, "12 commits behind origin/main"
- `personal-scripts` — yellow, "uncommitted changes, 2 weeks ago"

She selects all three with Shift+Click, clicks "Batch Pull" — the two behind repos update in seconds. For the uncommitted changes, she clicks into `client-acme-app`, sees the diff summary, and Ollama suggests a commit message: "Update authentication middleware for session timeout handling." She accepts, commits, pushes. Total time: 2 minutes.

**Resolution:** Her entire repo fleet is green. She minimizes GitPulse to the system tray and starts coding with confidence. The tray icon will pulse if anything changes during the day — she doesn't need to check again.

**Emotional arc:** Dread → surprise (it just works) → relief (visible clarity) → confidence (everything handled) → trust (passive monitoring has her back).

**Capabilities revealed:** Auto-discovery, Card Grid view, batch operations, Smart Status (Ollama), commit message suggestions, system tray agent, per-repo status visualization.

---

### Journey 2: Leo's Post-Sprint Audit (Power User / Tech Lead — Advanced Workflow)

**Persona:** Leo, 38, senior backend engineer at a mid-size SaaS company. He manages 18 microservice repositories in a monorepo-like architecture. His team just finished a 2-week sprint, and he needs to verify all services are synchronized and identify any cross-repo dependencies that need attention.

**Opening Scene:** Sprint retrospective just ended. Leo needs to confirm all 18 services are on the latest version and identify any cascade effects from a shared library update.

**Rising Action:** He opens GitPulse and switches to List View — sortable rows let him see all 18 repos at once. He clicks the "Behind" column header — 7 repos are behind their remotes. He selects all 7, executes "Batch Pull." Two fail with merge conflicts (clearly reported per-repo with error details). Five succeed.

**Climax:** For the two conflicts, Leo doesn't panic — the per-repo error report shows exactly which files conflict. He switches to his terminal for manual resolution (GitPulse doesn't do merge conflict UI in MVP). Back in GitPulse, he refreshes — both now show green.

Now he enables Smart Status in cloud mode (his Gemini API key is already configured). The privacy badge shifts from "Local" to "Cloud — data transits to Google." He runs a cross-repo health analysis. Gemini reports: "`shared-auth-lib` was updated in 5 repos but not in `payment-service` and `notification-service` — these may need version bumps." He selects the two flagged repos, pulls, and verifies.

**Resolution:** All 18 repos green. He screenshots the dashboard for his team standup. The Smart Status saved him from a potential auth token mismatch in production.

**Emotional arc:** Responsibility → systematic control → alert (conflicts detected, handled) → insight (AI catches what manual checks missed) → professional confidence.

**Capabilities revealed:** List View with sorting/filtering, batch pull with per-repo error reporting, Smart Status cloud mode (Gemini), cross-repo dependency analysis, privacy indicator, graceful error handling with partial success UX.

---

### Journey 3: Max's Great Cleanup (Maker / Side-Project Builder — Dormancy Discovery)

**Persona:** Max, 28, creative developer with a habit of starting projects. He has 47 repositories — some active, many dormant, a few he's forgotten entirely. He hasn't done a cleanup in over a year.

**Opening Scene:** It's a Saturday afternoon. Max decides it's time to organize his digital life. He's vaguely aware that some old projects might have uncommitted changes or API keys he should secure.

**Rising Action:** He launches GitPulse. The scan finds 47 repos across 4 directories. The Card Grid is overwhelming at first — too many tiles. He switches to List View and sorts by "Last Activity." The Smart Status (Ollama, local mode — privacy matters here) generates summaries:

- 12 repos dormant for 3+ months
- 3 repos with uncommitted changes older than 2 weeks
- 8 repos with unmerged feature branches
- 2 repos with remote URLs pointing to deleted GitHub repositories

**Climax:** Max creates a mental triage:
1. The 3 repos with uncommitted changes — he reviews each, commits what's worth keeping, discards the rest
2. The 2 repos with deleted remotes — he archives them locally
3. The 8 repos with stale branches — he bulk-deletes branches that were clearly experiments (branch names like `test-thing`, `wip-new-api`)

For the 12 dormant repos, he doesn't delete anything — but he tags them "dormant" for future reference (a Phase 2 feature — for now he makes a mental note).

**Resolution:** In 20 minutes, Max has cleaned up 15 repos. His dashboard now shows a manageable set of active projects. He feels lighter — like cleaning a cluttered desk.

**Emotional arc:** Overwhelm → discovery (visual clarity from chaos) → triage control → satisfaction (order restored) → lightness.

**Capabilities revealed:** Large repo count handling, List View sorting by activity, Smart Status dormancy detection (Ollama), commit message suggestions for forgotten changes, batch operations for cleanup, clear per-repo status even at scale.

---

### Journey 4: Jay's 30-Second Trial (Newcomer — Conversion Moment)

**Persona:** Jay, 25, junior developer. He saw GitPulse on Hacker News Show HN with 200+ upvotes. He has only 5 repos — mostly personal projects and a fork of a popular library. He's curious but skeptical.

**Opening Scene:** Jay clicks the download link. 15 MB binary. No installer — he double-clicks the executable. On Windows, SmartScreen shows an "unrecognized app" warning (a known friction point for new desktop apps). He clicks "Run anyway."

**Rising Action:** GitPulse opens. No login screen. No "Welcome to GitPulse!" onboarding overlay. Just a clean window asking which directories to scan. He selects his `~/Projects` folder. 5 repos appear in under 3 seconds. Each tile shows meaningful data — branch, status, last commit.

**Climax:** Jay doesn't have 50 repos, so the multi-repo value isn't immediately life-changing. But he notices one tile is yellow — a personal project with uncommitted changes from 3 weeks ago that he forgot about. He clicks it, sees a Smart Status summary: "2 files modified, likely CSS adjustments based on file names." He doesn't even need AI to remember what it was — the visibility alone solved the problem.

He decides to try the AI feature. He configures Ollama (already installed from previous experiments), runs Smart Status on his forked library. The one-line summary is genuinely useful: "Up to date with upstream, 1 local modification in README." He stars the GitHub repo.

**Resolution:** Jay keeps GitPulse running in the system tray. With 5 repos it's not essential — but it's lightweight enough to justify keeping. When his repo count grows (new job, more side projects), GitPulse will already be there.

**Emotional arc:** Curiosity → skepticism → mild surprise (it works immediately) → small delight (found forgotten changes) → investment decision (keeping it for future value).

**Capabilities revealed:** Small footprint binary download, zero-friction launch, SmartScreen handling (implicit requirement), small repo count UX (dashboard shouldn't feel empty with <10 repos), Smart Status value even at small scale, system tray persistence.

---

### Journey Requirements Summary

| Capability Area | Journeys Revealing Need | Priority |
|----------------|------------------------|----------|
| Auto Discovery | Sarah, Max, Jay | MVP |
| Card Grid View | Sarah, Jay | MVP |
| List View (sort/filter/select) | Leo, Max | MVP |
| Batch Operations | Sarah, Leo, Max | MVP |
| Per-repo Error Reporting | Leo | MVP |
| System Tray Agent | Sarah, Jay | MVP |
| Smart Status — Ollama | Sarah, Max, Jay | MVP |
| Smart Status — Cloud APIs | Leo | MVP |
| Privacy Indicator | Leo | MVP |
| Commit Message Suggestions | Sarah, Max | MVP |
| Dormancy Detection | Max, Jay | MVP |
| Cross-repo Analysis | Leo | MVP |
| Small Repo Count UX | Jay | MVP |
| Download/First-launch UX | Jay | MVP |
| Repo Tagging/Grouping | Max | Phase 2 |
| SmartScreen/Code Signing | Jay | MVP (implicit) |

## Functional Requirements

### Repository Discovery

- FR1: The user can initiate a recursive disk scan to discover Git repositories on their machine
- FR2: The user can configure which root directories to scan
- FR3: The user can exclude directories from scanning via a `.gitpulseignore` file (glob syntax)
- FR4: The system can detect Git repositories by identifying `.git` folders
- FR5: The user can manually trigger a rescan to refresh the repository list
- FR6: The system can gracefully handle inaccessible directories (skip and log, no crash)
- FR7: The system can cache scan results for instant reload on subsequent launches

### Dashboard & Visualization

- FR8: The user can view repositories in a card grid showing branch, status (clean/dirty/ahead/behind), last commit, and stash count
- FR9: The user can view repositories in a sortable, filterable list view with multi-select
- FR10: The user can toggle between card grid and list view
- FR11: The user can sort repositories by status, last activity date, branch name, or ahead/behind count
- FR12: The user can filter repositories by status (clean, dirty, ahead, behind, dormant)
- FR13: The system can display visual status indicators (color/badges) for instant pattern recognition across all repos
- FR14: The system can render large repository lists (100+) without UI degradation

### Batch Operations

- FR15: The user can select multiple repositories and execute batch `git pull`
- FR16: The user can select multiple repositories and execute batch `git push`
- FR17: The user can select multiple repositories and execute batch `git fetch`
- FR18: The user can batch `git status` across multiple repositories
- FR19: The system can report per-repo results for batch operations (success/failure with details)
- FR20: The system can handle partial success — repos that succeed continue, repos that fail are reported with error details
- FR21: The user can see specific error details (e.g., merge conflicts, auth errors) for failed repos

### Smart Status (AI Integration)

- FR22: The user can enable Ollama integration for local, private repository health summaries
- FR23: The user can configure cloud API keys (Gemini, DeepSeek, OpenAI, Anthropic) for AI-powered analysis
- FR24: The system can generate one-line repository health summaries via the configured AI backend
- FR25: The system can suggest commit messages based on staged changes via the configured AI backend
- FR26: The system can detect and flag dormant repositories beyond a configurable threshold
- FR27: The user can see a visual privacy indicator showing whether data processing is local or cloud-based
- FR28: The system can operate entirely without any AI backend configured (deterministic status parsing as default)
- FR29: The user can route different AI tasks to different providers (e.g., Ollama for commits, cloud for analysis)
- FR30: The system can provide cross-repo analysis when using a cloud AI model (e.g., shared library dependencies across repos)

### System Tray Agent & Notifications

- FR31: The user can run GitPulse as a background system tray agent with the dashboard closed
- FR32: The system can monitor for remote changes and alert the user via native OS notifications
- FR33: The system can send push reminders for repos with unpushed commits older than a configurable threshold
- FR34: The user can configure GitPulse to auto-launch at system startup (opt-in)
- FR35: The user can access common operations (status, pull, push) via the system tray context menu

### Settings & Configuration

- FR36: The user can configure scan root directories via a settings interface
- FR37: The user can configure AI backend settings (Ollama endpoint, cloud API keys, per-task routing)
- FR38: The user can configure notification behavior (frequency, types, thresholds)
- FR39: The user can configure system tray agent behavior (launch at startup, monitoring interval)
- FR40: User settings are persisted locally and survive application restarts
- FR41: The user can reset all settings to defaults

### Onboarding & Distribution

- FR42: The user can launch GitPulse without any account, login, or network configuration
- FR43: The system can operate fully offline (all core features work without network access)
- FR44: The user can manually check for application updates via system tray or settings
- FR45: The user can download GitPulse as a single binary (no installer wizard required)
- FR46: The system can run on Windows, macOS, and Linux from initial release

## Non-Functional Requirements

### Performance

| ID | Requirement | Measurement | Target |
|----|-------------|-------------|--------|
| NFR1 | Cold startup | Time from launch to interactive dashboard | < 3 seconds |
| NFR2 | Disk scan speed | Time to discover all repositories | < 5 seconds (SSD, <100 repos) |
| NFR3 | Memory usage | RAM during normal operation | < 200 MB with 50+ repos |
| NFR4 | Binary size | Distribution artifact size | ~15 MB |
| NFR5 | Batch operation throughput | Time to pull/push 20 repos | < 30 seconds |
| NFR6 | UI rendering responsiveness | No perceptible jank during scrolling or view switching | < 16ms per frame (60fps) |
| NFR7 | Async AI loading | Smart Status does not block dashboard | AI results appear asynchronously; UI stays responsive |
| NFR8 | Incremental scan | Reload scan on subsequent launch | < 1 second from cache |

### Security

| ID | Requirement | Details |
|----|-------------|---------|
| NFR9 | API key storage | Cloud API keys stored using OS keychain/secure storage, not plaintext in config files |
| NFR10 | Privacy by default | No repository data leaves the machine unless user explicitly enables a cloud backend |
| NFR11 | Data flow transparency | Visual indicator always clearly shows whether data transits to a cloud provider |
| NFR12 | Scan scope control | Directories excluded via `.gitpulseignore` are never scanned or indexed |
| NFR13 | Zero telemetry by default | No usage data collected unless user explicitly opts in |
| NFR14 | Git execution isolation | Git commands run in isolated processes; a malicious repo cannot compromise the application |
| NFR15 | Dependency auditing | Rust and npm dependencies audited for known vulnerabilities before each release |

### Integration

| ID | Requirement | Details |
|----|-------------|---------|
| NFR16 | Ollama version compatibility | Supports Ollama stable releases (API v1) with graceful fallback on version mismatch |
| NFR17 | Cloud API compliance | Supports stable API versions for Gemini, DeepSeek, OpenAI, Anthropic; handles API error responses and rate limits gracefully |
| NFR18 | Git version compatibility | Supports Git >= 2.20 on all platforms; graceful fallback with clear error if Git is missing or too old |
| NFR19 | Native OS integration | Uses platform-native system tray APIs, notification centers, and startup launch methods — no workarounds |
| NFR20 | AI offline resilience | Ollama failure or cloud unavailability does not block any feature — deterministic fallback with AI status indication |

### Reliability

| ID | Requirement | Details |
|----|-------------|---------|
| NFR21 | Scan fault tolerance | Scan completes even if individual directories are inaccessible, corrupted, or permission-denied |
| NFR22 | Batch fault tolerance | Batch operations complete for successful repos even when individual repos fail |
| NFR23 | Crash recovery | Application state preserved across crashes — reopening does not require reconfiguration |
| NFR24 | User data persistence | Settings, scan configurations, and API keys survive application updates |

### Accessibility

| ID | Requirement | Details |
|----|-------------|---------|
| NFR25 | Keyboard navigation | All core operations (selection, batch ops, view switching) accessible via keyboard |
| NFR26 | High contrast support | Visual status indicators remain distinguishable in high contrast/dark mode |
| NFR27 | Screen reader compatibility | Key dashboard components use ARIA markup for basic screen reader support |

## Desktop Application Specific Requirements

### Platform Support

| Platform | Architecture | Distribution | Notes |
|----------|-------------|--------------|-------|
| Windows | x64 | `.exe` (portable) + optional MSI | SmartScreen handling required (code signing needed) |
| macOS | x64 + ARM (Apple Silicon) | `.dmg` | Universal binary preferred; Apple notarization required |
| Linux | x64 | `.deb` + `.AppImage` + `.rpm` | AppImage for zero-install, deb/rpm for package managers |

**Tauri v2 strategy:** Native webview per platform (WebView2/WebKit/WebKitGTK). Rust backend compiles identically across platforms. React frontend platform-agnostic. Platform-specific code (system tray, auto-launch) isolated behind feature flags.

### System Integration

- **System tray:** Windows (native via Tauri), macOS (menu bar), Linux (D-Bus/libappindicator)
- **Notifications:** Native OS notifications (Windows Action Center, macOS Notification Center, libnotify)
- **Auto-launch:** Opt-in via settings. Windows Registry, macOS LaunchAgent, Linux XDG autostart
- **Disk scanner:** Recursive `.git` detection with `.gitpulseignore` support (glob syntax)

### Update Strategy

- Manual update check via system tray / settings; GitHub Releases as distribution channel
- No forced auto-update — respect user control
- Update check is the only outbound network request in local-only mode
- Post-MVP: Tauri built-in updater (opt-in), delta updates
- **Code signing required:** Authenticode (Windows), Apple Developer + notarization (macOS), GPG (Linux)

### Offline Capabilities

- Core functionality (scan, dashboard, batch ops, deterministic status) requires zero network
- Ollama works entirely offline when running locally
- Cloud AI gracefully degrades to deterministic parsing
- Settings stored locally (JSON/TOML in app data directory)
- Scan results cached for instant reload on subsequent launches
