════════════════════════════════════════════════════════════════════════ USER GUIDE Gnomad Desktop Assistant · docs/USER_GUIDE.md ════════════════════════════════════════════════════════════════════════ USER GUIDE — GNOMAD DESKTOP ASSISTANT ===================================== Version: 0.2.0-beta.1 Project site: davidthegnomad.github.io/gnomad-desktop-assistant Studio: gnomadstudio.org ──────────────────────────────────────── INTRODUCTION ------------ Gnomad is a desktop AI assistant that lives in your menu bar (macOS) or system tray (Windows/Linux). It can: • Chat using cloud (DeepSeek) or local (Ollama) models • See your active app, window title, and clipboard (footer context strip) • Run real shell commands and file operations in a controlled workspace • Store skills and reference documents in a knowledge library Closing the window hides Gnomad to the tray—it does not quit the app unless you choose Quit from the tray menu. ──────────────────────────────────────── INSTALLATION ------------ macOS • Download the .dmg from GitHub Releases or the project site • Drag Gnomad to Applications • First open: right-click → Open if Gatekeeper blocks unsigned alpha builds Windows • Run the .msi or setup.exe installer • Launch from Start Menu; allow tray icon if prompted Linux • Debian/Ubuntu: sudo apt install ./gnomad_*_amd64.deb • Fedora/RHEL: sudo dnf install ./gnomad-*-1.x86_64.rpm • Other: chmod +x gnomad_*.AppImage && run it See LINUX_PACKAGES.md for distro-specific details. ──────────────────────────────────────── FIRST LAUNCH & ONBOARDING ------------------------- On first launch (when no API key and no Ollama URL are configured), a welcome wizard appears: 1. Choose provider — Cloud API (DeepSeek) or Local model (Ollama) 2. Configure — API key + model, or Ollama URL + model tag Keys are saved to your system keychain. Change setup anytime in Settings → Re-run setup wizard. Developers may use .env with DeepSeek_API_KEY; the UI shows Set from .env and locks that key slot. ──────────────────────────────────────── OPENING AND CLOSING GNOMAD -------------------------- Action | macOS | Windows / Linux Show / hide | Menu bar icon or ⌘⇧Space | Tray icon or Ctrl+Shift+Space Hide window | Close button or shortcut again | Same Quit | Tray → Quit Gnomad | Same Tray menu: Show Gnomad, Pop Out Window, Settings, Visit gnomadstudio.org, About, Quit. ──────────────────────────────────────── WINDOW MODES ------------ Use the four chips in the title bar (or View menu in windowed mode): Mode | Description Panel | Drops from menu bar / near tray; compact layout Pop out | Floating, movable window Window | Standard window with native menus Full | Fullscreen; click again to return to pop out ──────────────────────────────────────── MAIN INTERFACE OVERVIEW ----------------------- Title bar: Window modes, theme toggle, Knowledge (book), Settings (gear). Sidebar: New chat, history, knowledge shortcut; resize, collapse, flip side. Center: Welcome, suggestion chips, messages, shell output blocks. Composer: Input, attachments, terminal (local), provider/model, send. Context footer: Active app, window title, clipboard, permission banner (macOS). ──────────────────────────────────────── CHAT & COMPOSER --------------- 1. Type or click a suggestion chip 2. Optionally attach files 3. Choose Cloud/Local and model 4. Press Send or Enter While thinking: Click Stop to interrupt shell activity. Direct shell (local): Prefix with $ or use the terminal icon. ──────────────────────────────────────── CLOUD VS LOCAL AI ----------------- | Cloud (DeepSeek) | Local (Ollama) Requires | API key | Ollama URL + running server Models | Chat, Reasoner | llama3.2, mistral, custom tags Agent | Tool calling | tags + optional planner Network | Internet | Usually localhost Switch via composer or Settings → Model & API. ──────────────────────────────────────── CHANGING MODELS AND API KEYS ---------------------------- Composer: Provider and model dropdowns. Settings → Model & API: Cloud model or Ollama URL + model name. Settings → API keys: Add/change/remove DeepSeek key (keychain). .env keys are locked in UI. ──────────────────────────────────────── AGENT: SHELL & FILESYSTEM ------------------------- • Cloud: Tools for shell, files, workspace (up to 10 steps per message) • Local: gnomad-run tags, $ commands, optional command planner • Shell session: Persistent cwd; reset in Settings → Agent shell • Workspace: Settings → Agent access → Change folder • Trust: Standard (workspace + gates) or YOLO (broader FS) • Audit: {app_data}/gnomad/agent-audit.jsonl ──────────────────────────────────────── SAFETY: SUDO GATE & PATH GATE ----------------------------- Sudo Gate — Risky shell (sudo, rm -rf, etc.): read reason, Approve or Deny. Approval mints a signed HITL token bound to the exact command (single-use, ~2 min TTL). Passing approval without a token is rejected. Path Gate — Standard mode: files outside workspace need approval. Allow once mints a signed path token bound to the canonical path and scope (read/write). ──────────────────────────────────────── EMBEDDED GGUF (OPTIONAL BUILD) ------------------------------ When built with embedded-llm (npm run tauri:dev:embedded): 1. Settings → Agent access → GGUF path — point to a small .gguf (e.g. Qwen2.5-Coder 1.5B Q4) 2. Command planner uses GGUF in-process (no Ollama required for planner) 3. Experimental → Use GGUF for local chat — full local chat without Ollama 4. Experimental → Sandbox shell in YOLO — wrap shell in OS sandbox (macOS/Linux) ──────────────────────────────────────── TERMINAL VIEW (XTERM.JS) ------------------------ While the agent runs commands, live PTY output streams in the thinking panel. On command cards, click Terminal view to replay ANSI-colored output in an embedded terminal. ──────────────────────────────────────── UPDATES ------- Settings → Updates — choose Stable or Beta channel, then Check for updates. Requires signed release artifacts; see UPDATER.md. ──────────────────────────────────────── KNOWLEDGE & SKILLS LIBRARY -------------------------- Open via book icon or sidebar. Folders under gnomad/knowledge/: • skills/ — instructions (.md, .txt, .json) • agents/ — personas • preferences/ — user preferences • uploads/ — reference files Add files in the panel; INDEX.md updates automatically. ──────────────────────────────────────── CHAT HISTORY & SIDEBAR ---------------------- • New chat: Sidebar + or ⌘/Ctrl+N • Select / delete sessions in the list • Layout: Resize, collapse, drag to flip side Sessions stored locally on disk. ──────────────────────────────────────── SETTINGS REFERENCE ------------------ Section | Purpose Model & API | Provider, models, wizard API keys | Keychain secrets Agent access | Workspace, trust, planner, GGUF, experimental flags Updates | Stable/beta channel, check/install Agent shell | CWD, reset session Knowledge | Open library Permissions | Accessibility, elevation test; Wayland tray hint Theme: Sun/moon/monitor icon cycles Light → Dark → System. ──────────────────────────────────────── VOICE INPUT (BETA) ------------------ 1. Settings → Privacy → Enable microphone dictation 2. Click the mic button in the composer (push-to-talk — click again to stop) 3. Speech is converted to text by your OS/browser engine and appended to the message Audio may be processed by Apple, Google, or another vendor depending on platform — not sent to Gnomad servers. Disable anytime in Settings. ──────────────────────────────────────── KEYBOARD SHORTCUTS ------------------ Shortcut | Action ⌘⇧Space / Ctrl+Shift+Space | Show / hide ⌘N / Ctrl+N | New chat ⌘, / Ctrl+, | Settings ⌘Q / Ctrl+Q | Quit (windowed) ──────────────────────────────────────── PLATFORM-SPECIFIC NOTES ----------------------- macOS: Accessibility for automation; admin auth for elevation. Windows: Tray near notification area; elevated cmds in admin terminal. Linux: WebKitGTK + AppIndicator; optional xdotool, wl-paste, xclip. On Wayland, left-click the tray icon to open the menu (Settings shows a hint when Wayland is detected). ──────────────────────────────────────── TROUBLESHOOTING --------------- See TROUBLESHOOTING.md for the full guide. Quick fixes: Issue | Fix Cloud disabled | Add API key, or set DeepSeek_API_KEY / OPENAI_API_KEY in .env Local disabled | Set Ollama URL; run ollama serve Chat errors | Check network, cloud endpoint in Settings, or curl Ollama URL No tray (Linux) | Install appindicator packages Empty context (Linux) | Install clipboard/window tools macOS permissions | Re-grant Accessibility after updates ──────────────────────────────────────── PRIVACY & DATA -------------- • Chat and knowledge stay on your device • Cloud prompts go to DeepSeek per their terms • Local prompts go to your Ollama server • API keys in OS keychain • Clipboard included only when you send a message See PRIVACY.md for the full policy. ──────────────────────────────────────── Built with ❤️ by Gnomad Studio 🦙 ════════════════════════════════════════════════════════════════════════ Built with ❤️ by Gnomad Studio 🦙 https://gnomadstudio.org ════════════════════════════════════════════════════════════════════════