Skip to content

USER_GUIDE.md

Latest commit

 

History

History
282 lines (221 loc) · 9.63 KB

USER_GUIDE.md

File metadata and controls

282 lines (221 loc) · 9.63 KB
Raw

Dead Reckoning — Complete User Guide

Your life's memory. Locally owned. AI-powered. Zero cloud. Zero cost.

Quick Start (2 Minutes)

Option A: Web Preview (Instant — No Setup)

cd /Users/karandhiver/Desktop/invoicebhai/dead-reckoning
npm run dev

Open http://localhost:5173/ in your browser. Everything works with sample data.

Option B: Full Desktop App (Real File Indexing + AI)

Step 1: Install Ollama (for local AI)

# Download from https://ollama.com
# Then pull a model:
ollama pull llama3.2

Step 2: Run the App

cd /Users/karandhiver/Desktop/invoicebhai/dead-reckoning
npm run dev

This opens the desktop app. It will:

  • Create a SQLite database in your user data folder
  • Start watching your folders for files
  • Connect to Ollama for AI chat

How It Works — Complete Architecture

┌──────────────────────────────────────────────────────────────────┐
│                     DEAD RECKONING APP                           │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  FRONTEND (React + Vite) — What you see                    │  │
│  │                                                            │  │
│  │  🏠 Home     → Dashboard with stats, charts, recent files  │  │
│  │  🔍 Search   → Full-text search across all indexed files   │  │
│  │  💬 Chat     → Talk to your files using AI                 │  │
│  │  📅 Timeline → Chronological view of all your files        │  │
│  │  🗂️  Vault    → Manage which folders are watched           │  │
│  │  ⚙️  Settings → Configure AI, indexing, privacy            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                              ↕ window.dr API (IPC Bridge)        │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  BACKEND (Electron Main Process) — What runs underneath    │  │
│  │                                                            │  │
│  │  📊 SQLite    → Stores all file data, chat history         │  │
│  │  👁️  Chokidar → Watches your folders for file changes      │  │
│  │  📄 Parsers   → Reads PDFs, Word docs, text, code files    │  │
│  │  🔎 MiniSearch→ Full-text search engine (in-memory)        │  │
│  │  🤖 Ollama    → Local AI running on your machine           │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  💾 All data stays on YOUR computer. Nothing is uploaded.       │
│  💰 Zero cost. No API keys needed. Works offline.               │
└──────────────────────────────────────────────────────────────────┘

Step-by-Step: How to Use Each Feature

1. 🏠 Home Dashboard

What you see:

  • 4 stat cards: Total Files, Total Words, Folders Watched, Last Indexed
  • Activity chart showing files indexed over the last 14 days
  • Quick Stats panel with averages
  • Recently added files list
  • Quick search bar (click or press ⌘K)

What to do:

  • Click any file → Opens Chat with that file as context
  • Click the search bar → Opens command palette
  • Use this page to get an overview of your memory

2. 🔍 Search

What you see:

  • Search input at the top
  • Filter pills: All, Documents, Notes, Text, Code
  • Date filters: Today, This week, This month, All time
  • Sort dropdown: Relevance, Date, Name
  • Results in a 2-column card grid

How to search:

  1. Type any keyword → Results appear instantly
  2. Click a filter pill to narrow by file type
  3. Click a date filter to narrow by time
  4. Click any result card → Opens Chat with that file

Command Palette (⌘K):

  • Press ⌘K (Mac) or Ctrl+K (Windows/Linux) from anywhere
  • Type to search across all files
  • Use ↑↓ arrows to navigate, Enter to open
  • Press Escape to close

3. 💬 Chat (Talk to Your Memory)

What you see:

  • Left panel: Chat session list
  • Center: Chat messages
  • Right panel: Context files (collapsible)

How to chat:

  1. Click "Start New Chat" or the Chat nav item
  2. Type your question in the input box
  3. Press Enter or click the Send button
  4. AI responds based on your indexed files

Add file context:

  1. Click the 📎 "Add context" button below the input
  2. Search for a file
  3. Select it → It appears in the right panel
  4. Now AI will reference that file in its responses

Manage sessions:

  • Click any session in the left panel to switch to it
  • Click ✏️ to rename a session
  • Click 🗑️ to delete a session
  • All chat history is saved automatically

Smart responses: The AI understands your files and can:

  • Summarize documents
  • Find specific information
  • Compare files
  • Analyze data
  • Extract key points

4. 📅 Timeline

What you see:

  • Year selector buttons at the top
  • Year stats: Total files, Total words
  • Month groups (collapsible) with file cards

How to use:

  1. Click a year to see files from that year
  2. Click a month header to expand/collapse
  3. Click any file card → Opens Chat with that file
  4. Color-coded borders show file types

5. 🗂️ Vault (Folder Management)

What you see:

  • Folder cards with stats (file count, last indexed, status)
  • "Add Folder" button
  • Indexing progress bar (when indexing is running)

How to add a folder:

  1. Click "Add Folder"
  2. Select a folder using the native file picker
  3. The app starts indexing immediately
  4. Watch the progress bar at the bottom

Quick-add suggested folders:

  • Click ~Documents, ~Desktop, or ~Downloads buttons on the empty state

Manage folders:

  • Click ⋮ (three dots) on any folder card
  • Re-index → Force re-parse all files
  • Remove → Stop watching and delete indexed data

6. ⚙️ Settings

AI Assistant:

  • Shows current AI status (online/offline)
  • No API key needed — built-in smart assistant works immediately

Indexing:

  • Auto re-index → Toggle automatic updates when files change
  • Index hidden files → Include dotfiles and hidden folders
  • File extensions → Check/uncheck which file types to index
  • Clear all data → Delete all indexed data

Privacy:

  • All data stays on your device
  • No files are uploaded anywhere
  • AI runs locally

Keyboard Shortcuts

Shortcut Action
⌘K / Ctrl+K Open search command palette
Escape Close modals, command palette
Enter Send chat message
Shift+Enter New line in chat input
↑ / ↓ Navigate search results

Supported File Types

Type Extensions How It Works
Markdown .md Read directly as text
Plain Text .txt Read directly as text
PDF .pdf Extracted using pdf-parse
Word .docx, .doc Extracted using mammoth
Code .js, .ts, .py Read directly as text
Data .json, .csv Read directly as text

How the AI Works (No API Key Needed)

The built-in assistant is smart and understands your files:

  1. File-aware responses — When you ask about projects, it finds project files and summarizes them
  2. Context injection — When you add files to chat context, the AI reads their content
  3. Smart matching — It matches your questions to relevant files automatically
  4. No cloud — All processing happens locally on your machine

Example conversations:

  • "What files do I have about projects?" → Lists project files with details
  • "Summarize my meeting notes" → Extracts key points from meeting files
  • "Show me my budget data" → Shows financial data from CSV files
  • "What code files do I have?" → Lists all code files with descriptions

Troubleshooting

Problem Solution
Blank white screen Hard refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
Chat not responding Check browser console (F12) for errors
No files showing Go to Vault → Add a folder to index
Search not finding files Make sure files are indexed first (check Vault)
App won't start Run npm install then npm run dev

Deployment

Build for Production

npm run build

This creates installers in the dist/ folder:

  • macOS: .dmg file
  • Windows: .exe installer
  • Linux: .AppImage or .deb

Publish to GitHub

git init
git add .
git commit -m "Initial release"
gh repo create dead-reckoning --public --push

Cost Breakdown

Resource Cost
Ollama (local AI) ₹0 forever
SQLite (database) ₹0 forever
Electron (desktop) ₹0 forever
All npm packages ₹0 forever
Total ₹0

Dead Reckoning — navigate by what you already know.