# EnvoyOS — Multi-PC, Multi-Monitor Productivity Suite

A productivity-focused desktop application built with Godot 4.6. Designed for engineers and knowledge workers who work across multiple PCs and monitors. The core value proposition: **every keystroke, file, and timer is one hop away regardless of which machine you're sitting at.**

---

## Project Highlights

- **All-in-One Toolkit**: AI tools, clipboard sync, file transfer, timers, inventory tracking, video/audio settings, and built-in support documentation in a single interface.
- **Modular Architecture**: Clean separation between logic (`*_engine.gd`) and UI (`*_ui.gd`) ensures scalability and easy maintenance.
- **Cross-PC Sync**: ENet-based multiplayer with AES-256 encrypted clipboard, planned file transfer, and shared state.
- **Multi-Monitor Aware**: DPI scaling, per-monitor layout memory, window tiling, and floating overlays.
- **AI Integration**: Local Ollama-powered code assistant, suggestions, and (planned) transcription.

---

## Why Support?

Developing and maintaining open-source tools takes time, effort, and resources. Your support directly funds:

- New feature development & bug fixes
- Performance optimizations & engine updates
- Documentation & community resources

Every contribution, no matter the size, helps keep this project growing and accessible to everyone. Thank you for your support! ☕✨

---

## Current State

### Completed / Working
| Module | Status |
|--------|--------|
| Clipboard sync (ENet + AES-256) | ✅ Working |
| AI Chat (Ollama streaming) | ✅ Working |
| Markdown Editor (autosave) | ✅ Working |
| VoIP (UDP, VAD, jitter buffer) | 🚧 In Progress |
| Audio settings (volume, mute, mic level) | 🚧 In Progress |
| Timer panel (12 slots, fuel-bar UI) | ✅ Working |
| Inventory panel (12 slots, fuel-bar UI) | 🚧 In Progress |
| Tab management (custom tab bar, session persistence) | ✅ Working |
| OS Grid layout (configurable rows × cols) | 🚧 In Progress |
| Theme builder (bg/font/accent/shade/transparency) | ✅ Working |
| Video settings (FPS, DPI, window mode, position, size) | ✅ Working |
| Web tab browser (paginated Chrome export) | 🚧 In Progress |
| Ship game (2D physics, object pooling) | ✅ Working |
| TOP / Power state tracker | 🚧 In Progress |
| User AFK detection (cross-platform) | ✅ Working |
| Window drag/resize (borderless) | ✅ Working |
| System tray minimization | ✅ Working |

### Missing / Stub (Blocking)
| File | Status | Action Required |
|------|--------|-----------------|
| `system_engine.gd` | Empty | Implement CPU/RAM/disk/GPU stats |
| `system_ui.gd` | Empty | Build system dashboard (CPU graph, RAM bar, disk, AFK) |
| `ai_code_engine.gd` | Empty | Build code-gen/review/explain engine |
| `ai_code_ui.gd` | Empty | Side-by-side code editor + AI panel |
| `music_engine.gd` | `extends Node` only | Implement playback queue, seeking, shuffle |

### Known Bugs / Technical Debt
| Issue | Location | Fix |
|-------|----------|-----|
| `grid_engine.gd` references `clipboard_engine.is_connected_to_network` (doesn't exist) | `grid_engine.gd` line ~230 | Change to `clipboard_engine.can_broadcast` / `clipboard_engine.is_connecting` |
| `tab_engine.gd` and `top_engine.gd` are 95% duplicates | Both files | Merge into one class or have TopEngine extend TabEngine |
| No input validation on VoIP port field | `voip_ui.gd` | Add `is_valid_int()` check before `int()` cast |
| Timer/Inventory `hh:mm:ss` parse has no overflow guard | `time_ui.gd`, `inventory_ui.gd` | Validate h≤23, m≤59, s≤59 before arithmetic |
| Music/Media tab is a dead tab | `main_engine.gd` ALL_TABS | Either implement or remove from list |
| No CI / automated testing | Repo root | Add GitHub Actions with `godot --headless --check-only` |

---

## Feature Roadmap

### Phase 1 — Fix & Stabilise (Weeks 1–2)

| # | Task | Details |
|---|------|---------|
| 1.1 | Implement `system_engine.gd` | CPU %, RAM used/total, disk usage, GPU load (platform-specific), network throughput. Emit signals for UI. |
| 1.2 | Implement `system_ui.gd` | Dashboard with live-updating gauges, AFK timer (reuse `user_active_engine.gd`), process list (optional). |
| 1.3 | Fix `grid_engine.gd` broken refs | Replace `is_connected_to_network` → `can_broadcast`, `is_reconnecting` → `is_connecting`. |
| 1.4 | Merge `tab_engine` / `top_engine` | One base class, reduce duplication. |
| 1.5 | Add input validation | VoIP port, Timer/Inventory time parsing, all user-facing number fields. |
| 1.6 | Implement or remove Music tab | Either build `music_engine.gd` + wire `music_ui.gd`, or remove "Media" from ALL_TABS. |
| 1.7 | Add unit tests (GUT) | ThemeSerializer round-trip, TabEngine CRUD, TimeEngine tick, InventoryEngine expiry, ClipboardEngine encrypt/decrypt. |
| 1.8 | CI pipeline | GitHub Actions: `godot --headless --check-only` + GUT test run on push. |

### Phase 2 — Multi-PC Power Features (Weeks 3–6)

| # | Task | Details |
|---|------|---------|
| 2.1 | **Clipboard History Ring Buffer** | Store last 100 items (text + images) with timestamp, source PC, app name. Global hotkey `Ctrl+Shift+V` opens searchable picker across all peers. |
| 2.2 | **Snippet Library** | Save frequently-used text blocks (code snippets, email templates, API keys). Sync to all PCs. One-click paste. |
| 2.3 | **Cross-PC Text Search** | Type a keyword → search all peers' clipboard history simultaneously via RPC. |
| 2.4 | **P2P File Transfer** | Drag file onto Network tab → AES-256 encrypt → chunked ENet stream → progress bar → destination PC. Reuse existing crypto. |
| 2.5 | **Shared Workspace Folder** | Synced directory (chunked transfer). Edit on PC-A, open on PC-B. |
| 2.6 | **Shared Kanban Board** | To-Do / In-Progress / Done. RPC-synced in real-time. Cards: title, tags, due date, assigned PC. Reuse `clipboard_engine` RPC pattern. |
| 2.7 | **Notification Mirroring** | System/app notifications broadcast to all peers. "PC-A idle > 10 min" → toast on PC-B. Timer expiry → alert all. |
| 2.8 | **Command Palette (`Ctrl+K`)** | Fuzzy-search all actions: "open tab", "change theme", "start timer 3", "connect to PC-B", "mute audio". One keystroke to do anything. |
| 2.9 | **Global Hotkeys (OS-level)** | Register via native helper: clipboard history, screenshot, quick paste. Works even when app is unfocused. |
| 2.10 | **Offline Queue** | When disconnected, queue clipboard/file/task changes. Auto-sync on reconnect (extend existing reconnection logic). |

### Phase 3 — Multi-Monitor & AI (Weeks 7–10)

| # | Task | Details |
|---|------|---------|
| 3.1 | **Monitor Layout Memory** | Detect monitors, save per-monitor window positions/sizes per panel. Restore on reconnect. `user://monitor_layout.json`. |
| 3.2 | **Floating Overlays** | Always-on-top widgets: timer countdown, clipboard dock (last 5 items), AFK indicator glow. Assignable to specific monitor. |
| 3.3 | **Window Tiling / Snapping** | `Ctrl+1..4` → quadrant. `Ctrl+Shift+Left/Right` → half. Save/load named layouts. `Ctrl+L` to cycle. |
| 3.4 | **Per-Monitor Contrast** | Each monitor can have different shade/brightness. Auto-adjust based on ambient light or time-of-day. |
| 3.5 | **AI Code Engine** | `ai_code_engine.gd`: Explain selected code, Refactor + diff view, Generate from prompt, Review PR diff. Reuse Ollama streaming client. |
| 3.6 | **AI Code UI** | `ai_code_ui.gd`: Side-by-side editor + AI response panel. Syntax highlighting, diff view, copy-to-clipboard. |
| 3.7 | **AI Meeting Notes** | Stream mic audio → local Whisper (Ollama-compatible) → bullet-point summary → sync to all peers. |
| 3.8 | **Cross-PC Input Mirroring (KVM)** | Type on PC-A → keystrokes stream to PC-B. Mouse delta streaming (relative, not absolute). Per-peer toggle. |
| 3.9 | **AI Suggestion Engine** | Wire existing "Suggestion" prompt field to a "Smart Suggestions" button on clipboard tab. 3 context-aware actions. |

### Phase 4 — Polish & Release (Weeks 11–12)

| # | Task | Details |
|---|------|---------|
| 4.1 | **Auto-start with OS** | Registry key (Win), `.desktop` file (Linux), `LaunchAgent` (macOS). |
| 4.2 | **System Tray Menu** | "Show", "Mute", "Disconnect", "Open Timer", "Open Kanban", "Exit". |
| 4.3 | **Backup / Restore** | One-click export all `user://` settings to `.zip`. Import on new PC. |
| 4.4 | **Accessibility Pass** | High-contrast mode, UI font scaling, screen-reader labels on all controls. |
| 4.5 | **Session Replay** | Record 10s UI interaction replay as JSON for bug reports. |
| 4.6 | **User Documentation** | Expand SUMMARY.md → full user manual. Keyboard shortcut reference. Setup guide per OS. |
| 4.7 | **Export / Packaging** | `godot --export-release` for Windows / Linux / macOS. In-app updater (optional). |

### Phase 5 — Differentiators (Ongoing)

| # | Feature | Description |
|---|---------|-------------|
| 5.1 | Screen recording per monitor | GPU capture, "record this monitor" toggle, export to file. |
| 5.2 | Screenshot + AI annotate | Capture region → send to Ollama → written description. |
| 5.3 | Pomodoro focus mode | 25/5 preset. Auto-pauses AI streaming and network sync during focus. |
| 5.4 | Dark-light auto-switch | Theme tied to system clock (dark after 18:00). |
| 5.5 | Peer presence bar | Avatar strip showing online PCs (reuse `multiplayer.get_peers()`). |
| 5.6 | Voice commands | "Hey, paste the last email" → VAD → match snippet → paste. |
| 5.7 | Shared timer countdown | Timer on PC-A shows live on PC-B. Sync `end_timestamp` over network. |
| 5.8 | Calendar view | Timers/inventory deadlines on a mini monthly calendar. |
| 5.9 | CSV export | Timer/inventory state as CSV for spreadsheet tracking. |
| 5.10 | Low-stock alerts | Inventory item below threshold → red flag on all PCs. |

---

## Architecture Notes

```
┌─────────────────────────────────────────────────────────────────────┐
│                        MainUI / GridUI (Root)                        │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  TabBar / Grid Toolbar                                         │  │
│  └───────────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  TabContainer / Content Area                                   │  │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │  │
│  │  │ AI Chat │ │ Editor  │ │ Network │ │  Timer  │  ...        │  │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │  │
│  └───────────────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Engines (Nodes)                                               │  │
│  │  clipboard_engine │ ai_engine │ video_engine │ audio_engine    │  │
│  │  mic_engine │ web_engine │ time_engine │ inventory_engine     │  │
│  │  ui_engine │ top_engine │ tab_engine │ voip_engine            │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Network Layer: ENet (MultiplayerPeer) + AES-256 (AESContext)
Persistence:   ConfigFile (*.cfg) + JSON (*.json) + CSV (timers/inventory)
Theme:         ThemeSerializer (compressed JSON, hex colors, FastLZ)
```

---

## Supported Platforms

| OS | Clipboard | Audio | Idle Detection | Network |
|----|-----------|-------|----------------|---------|
| Windows | ✅ | WASAPI | GetLastInputInfo (P/Invoke) | ENet |
| macOS | ✅ | CoreAudio | IOHIDSystem (ioreg) | ENet |
| Linux | ✅ | PipeWire/PulseAudio | D-Bus (Mutter/KWin) / xprintidle | ENet |

---

## Keyboard Shortcuts (Planned)

| Shortcut | Action |
|----------|--------|
| `Ctrl+K` | Command Palette |
| `Ctrl+Shift+V` | Clipboard History (cross-PC) |
| `Ctrl+1..4` | Snap to quadrant |
| `Ctrl+Shift+Left/Right` | Snap to half |
| `Ctrl+L` | Cycle saved layouts |
| `Ctrl+W` / `close_tab` | Close current tab |
| `Ctrl+T` / `new_tab` | New tab |
| `Ctrl+Tab` / `Ctrl+Shift+Tab` | Next / Previous tab |

---

## Why This Saves Time

| Pain Point | Solution | Time Saved |
|------------|----------|------------|
| Copy on PC-A, walk to PC-B, paste | Cross-PC clipboard sync | 30s–2min per transfer |
| Re-type same email/snippet on each machine | Snippet library + one-click paste | 1–5min per repetition |
| "Where did I save that file?" | Shared workspace + cross-PC search | 5–15min per search |
| Set up different configs per monitor | Monitor layout memory + auto-restore | 5–10min per session |
| Explain code to colleague on another screen | AI explain + share to all PCs | 5–10min per explanation |
| Track physical inventory across desk drawers | Shared inventory with expiry alerts | Ongoing |
| "Did I finish that task?" | Shared Kanban visible on all PCs | 2–5min per check |
| Context-switch between 4 monitors on 2 PCs | Window tiling + input mirroring | 1–3min per switch |

---

## Contribution Guidelines

1. Read `AIFIX.md` for Godot 4.6 API corrections before editing.
2. Follow the `*_engine.gd` / `*_ui.gd` naming convention.
3. All new UI must handle tab-switch cleanup (check for existing wrapper before adding).
4. Network changes must go through `clipboard_engine.gd` RPC pattern (or the new `MultiplayerChannel` helper).
5. Theme changes must flow through `ui_engine.gd` → `MainUI.apply_full_theme()`.
6. Run tests: `godot --headless -s res://addons/gut/gut_cmdln.gd -gdir=res://tests`

---

## License & Attribution

See repository for license file. Built with ❤️ and too much coffee. ☕