Grove User Guide

Dashboard Overview

The Grove dashboard is a single-page app with tabs:

Tab	What it does
🏠 Home	Cell status, storage, network health, activity log
📂 Files	Browse your file tree, upload, manage files
📡 Feed	Files shared with you by friends
💬 Chat	E2E encrypted messaging with peers
🤖 AI	Local AI chat (if configured)
🎟️ Invites	Create and manage invite links
⚙️ Settings	Password, redundancy, preferences

---

Files Tab

Uploading Files

• Drag and drop files onto the upload zone, or click to browse
• Progress bar shows upload status
• Files are automatically encrypted, chunked, and synced to peers

View Modes

• 📋 List view — traditional file list with details
• 🖼️ Gallery view — image grid with thumbnails (click toggle in header)

File Actions (⋯ menu)

For files in Grove:

• 🔗 Share — share with friend peers
• 🔓 Unshare — revoke access
• 🗑️ Remove Locally — delete local copy (stays backed up on peers)
• 🌲 Remove from Grove — remove from all peers

For Grove-only files (no local copy):

• 🔄 Restore — download back from peers

For local-only files:

• 🌲 Back up to Grove — encrypt and sync to peers

Folders

• 👁️ Watch — auto-backup new files added to this folder
• Click a folder to browse into it
• Batch operations: select multiple files/folders with checkboxes

---

Feed Tab

Shows files shared with you by friend peers.

Views

• 🖼️ Gallery — photo grid (default), great for shared images
• 📋 List — detailed list with download buttons

File States

• Available — chunks downloaded, ready to view/download
• ☁️ Remote — shared but not yet downloaded (click 📡 Fetch)
• 🔏 Verified — cryptographic signature verified

Lightbox

Click any image to view full-size. Navigate with:

• ◀ ▶ buttons or arrow keys
• Escape to close
• Click outside image to close

---

Sharing Files

How to Share

1. Go to Files tab

2. Click ⋯ on a file → 🔗 Share

3. Select which friend peers to share with

4. For folders: optionally enable auto-share (future files auto-shared)

5. Click Share

What Happens

• A signed grant is created for each recipient
• Grant includes the encrypted file key (only they can decrypt)
• Grant is pushed to their cell immediately
• File appears in their Feed tab

Unsharing

• Click ⋯ → 🔓 Unshare
• Select which peers to revoke
• Their grant is deleted; they lose access

---

Chat

End-to-end encrypted messaging between peers.

• X25519 key exchange — each message encrypted with recipient's public key
• ChaCha20-Poly1305 — message encryption
• Messages stored locally on each cell (not on relay)
• Relay carries encrypted messages but can't read them

---

Peers

Peer Status

• 🟢 Green dot — online and reachable
• 🔴 Red dot — offline or unreachable
• ⭐ Star — favorite peer (always syncs)

Peer Actions

• 👥 — Add/remove as friend (friends can share files)
• ⭐ — Toggle favorite
• ✕ — Remove peer (choice: keep or delete their files)

Adding Peers

• Invite link — create at Invites tab, send to person
• Manual — enter IP/hostname in Add Peer form
• Discovery — auto-discover peers on local network (mDNS)
• Recommendations — existing peers can recommend new ones

---

Storage

Two-Bar Display

• 💾 Disk — total disk usage (Grove + other files + free space)
• 🌲 Grove Storage — breakdown of Grove data:
• Your files — files you own, stored locally + on peers
• Backed up only — your files only on peers (removed locally)
• Shared — files shared with you by peers
• Helping peers — encrypted chunks you're storing for others

Backup Health

Shows how many copies of your chunks exist across the fleet:

• 🟢 Green — at or above desired replication factor
• 🟡 Yellow — below desired but above minimum
• 🔴 Red — at risk (single copy only)

Replication Factor

Default: 2 (your cell + 1 peer). Change in Settings.

• Higher = safer but uses more storage across the fleet
• Opp sync automatically maintains the target

---

Network Health

• Sync status — banner shows when background sync is active
• Peer list — all peers with status, speed, and actions
• Activity log — recent events (uploads, syncs, shares, errors)
• Route benchmark — runs every 6 hours, measures actual throughput

---

Settings

• Password — change dashboard password
• Redundancy — set desired replication factor
• Relay — configure relay server URL
• Cell name — how peers see you
• Theme — color palettes (Grove, Forest, Ocean, Rose, Sakura) + light/dark mode

---

Keyboard Shortcuts

Key	Action
Escape	Close lightbox/modal
← →	Navigate gallery lightbox

---

Tips

• First time? A tutorial appears on first load — follow the tips!
• Slow uploads? Check your replication factor (lower = fewer copies to push)
• File missing? Check "Grove Only" files in Grove Files view — it may need a Restore
• Peer offline? Chunks auto-heal to other peers after ~5 minutes
• Want privacy? All chunks are encrypted. Even your peers can't read your files.