mission-control/README.md

# Mission Control

An ADHD-centric personal productivity hub that unifies GitLab activity, beads task tracking, and manual task management into a single native interface.

**Core principle:** Surface THE ONE THING you should be doing right now.

This is NOT a dashboard of everything. It's a trusted advisor that understands your work and helps you decide what matters.

## Features

### Focus View
The primary interface displays the single most important item you should be working on. When no focus is set, it suggests the top item from your queue. Actions available:
- **Start** - Open the associated URL and begin working
- **Defer** - Postpone for 1 hour or until tomorrow
- **Skip** - Remove from today's queue

### Queue View
A prioritized list of all your work items. Filter by type, search across titles, and batch-select items for bulk operations. Drag to reorder priorities.

### Inbox
Triage incoming items from GitLab or manual captures. Items flow in, you decide where they go.

### Quick Capture
Global hotkey (`Ctrl+Shift+Space`) to capture a thought instantly. Type it, hit enter, and it becomes a bead. Triage later.

### Batch Mode
When you have multiple items of the same type (e.g., code reviews), batch them together for focused flow sessions with time estimates.

### GitLab-Beads Bridge
Automatic synchronization creates beads from GitLab events:
- MR review requests
- Issue assignments
- Mentions in discussions
- Comments on your MRs

The bridge tracks mappings, handles deduplication, and recovers from partial sync failures.

### Decision Logging
Every action (start, defer, skip, complete) is logged with context: time of day, queue size, and optional reasoning. This data enables future pattern learning.

### bv Triage Integration
Surfaces AI-powered recommendations from `bv --robot-triage`:
- Top picks based on graph analysis
- Quick wins (low effort, available now)
- Blockers to clear (high unblock impact)

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Cmd+1` | Focus view |
| `Cmd+2` | Queue view |
| `Cmd+3` | Inbox |
| `Cmd+4` | Debug view |
| `Cmd+,` | Settings |
| `Ctrl+Shift+Space` | Quick capture |

Shortcuts use `Ctrl` instead of `Cmd` on non-macOS platforms.

## Architecture

```
Frontend (React 19 + Vite)     Backend (Tauri/Rust)
        |                              |
        |---- IPC (invoke) ----------->|
        |                              |
        |                     CLI Traits (mockable)
        |                              |
        |                     lore --robot (GitLab)
        |                     br (beads tasks)
        |                     bv --robot-* (triage)
```

Mission Control shells out to CLIs rather than importing them as libraries. This keeps boundaries clean and avoids schema coupling.

## Tech Stack

| Layer | Technology |
|-------|------------|
| Shell | Tauri 2.0 (Rust backend) |
| Frontend | React 19 + Vite |
| Styling | Tailwind CSS |
| Animations | Framer Motion |
| State | Zustand + TanStack Query |
| IPC | Tauri commands + events |

## External Dependencies

MC requires these CLIs to be installed and available in PATH:

- **lore** - GitLab data sync (`lore --robot me`)
- **br** - Beads task management (`br create`, `br close`)
- **bv** - Beads triage engine (`bv --robot-triage`, `bv --robot-next`)

## Local State

All MC-specific state lives in `~/.local/share/mc/`:

| File | Purpose |
|------|---------|
| `gitlab_bead_map.json` | Maps GitLab events to bead IDs (deduplication) |
| `decision_log.jsonl` | Append-only log of all user decisions with context |
| `state.json` | Current focus, queue order, UI state |
| `settings.json` | User preferences |

## Development

### Prerequisites

- Node.js 20+
- Rust (latest stable)
- Tauri CLI (`npm install -g @tauri-apps/cli`)

### Commands

```bash
# Install dependencies
npm install

# Start development (frontend only)
npm run dev

# Start development (frontend + backend)
npm run tauri:dev

# Run tests
npm run test           # Vitest unit tests
npm run test:watch     # Vitest watch mode
npm run test:coverage  # With coverage
npm run test:e2e       # Playwright e2e tests
cargo test             # Rust tests

# Lint
npm run lint           # ESLint
cargo clippy -- -D warnings  # Rust lints

# Build
npm run build          # Frontend only
npm run tauri:build    # Full app bundle
```

### Project Structure

```
src/
  components/      # React components
  hooks/           # Custom React hooks
  lib/             # Utilities, type definitions
  stores/          # Zustand state stores
src-tauri/
  src/
    commands/      # Tauri IPC command handlers
    data/          # CLI traits, bridge logic, state
    error.rs       # Error types
    lib.rs         # App setup
    main.rs        # Entry point
tests/
  components/      # Component tests
  lib/             # Library tests
  e2e/             # Playwright tests
```

## Testing

The codebase uses test-driven development with trait-based mocking:

- **Frontend:** Vitest + React Testing Library for component tests
- **Backend:** Rust unit tests with mock CLI traits
- **E2E:** Playwright for full application testing

CLI integrations use traits (`LoreCli`, `BeadsCli`, `BvCli`) that can be mocked in tests, keeping tests fast and deterministic without external dependencies.

## Design Principles

Mission Control follows ADHD-centric design principles:

- **The One Thing** - UI's primary job is surfacing THE single most important item
- **Achievable Inbox Zero** - Every view has a clearable state
- **Time Decay Visibility** - Age is visceral (fresh=bright, old=amber/red)
- **Batch Mode for Flow** - Group similar tasks for focused sessions
- **Quick Capture, Trust the System** - One hotkey, type it, gone
- **Ambient Awareness, Not Interruption** - Notifications are visible but never modal

## License

Private - not for distribution.