From 1f565f2ea6d7a5d667466f72f573c0ee2a7cf9bc Mon Sep 17 00:00:00 2001
From: 7174Andy <hep003@ucsd.edu>
Date: Mon, 5 Jan 2026 18:45:50 -0800
Subject: [PATCH 1/5] init mkdocs

---
 docs/index.md  | 17 +++++++++++++++++
 mkdocs.yml     |  4 ++++
 pyproject.toml |  8 ++++++--
 3 files changed, 27 insertions(+), 2 deletions(-)
 create mode 100644 docs/index.md
 create mode 100644 mkdocs.yml

diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..000ea34
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..1319d13
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,4 @@
+site_name: My Docs
+site_url: https://7174Andy.github.io/spendwise
+theme:
+  name: material
diff --git a/pyproject.toml b/pyproject.toml
index 6f2a4db..1d06850 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -17,8 +17,12 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
-    "pytest>=8.4.2",
-    "ruff>=0.14.4",
+    "pytest",
+    "ruff",
+]
+
+docs = [
+    "mkdocs-material",
 ]
 
 [project.scripts]

From e815edc986fb15195d3ef5fa5fefdfa89d83597e Mon Sep 17 00:00:00 2001
From: 7174Andy <hep003@ucsd.edu>
Date: Mon, 5 Jan 2026 18:45:59 -0800
Subject: [PATCH 2/5] add workflows for docs deployment

---
 .github/workflows/docs.yml | 46 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..e965576
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,46 @@
+name: Deploy MkDocs to Github Pages
+
+on:
+    release:
+        types:
+            - published
+    push:
+        branches:
+            - main
+permissions:
+    contents: write
+
+jobs:
+    docs:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repo
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: Set up UV
+              uses: astral-sh/setup-uv@v6
+
+            - name: Install Dependencies
+              run: |
+                  uv sync --extra dev --extra docs
+
+            - name: Set up git user
+              run: |
+                  git config --global user.name "github-actions[bot]"
+                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+            - name: Build and upload docs (release)
+              if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                  uv run mike deploy --update-aliases --allow-empty --push "${{ github.event.release.tag_name }}" latest
+
+            - name: Build and upload docs (dev)
+              if: ${{ github.event_name == 'push' }}
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                  uv run mike deploy --update-aliases --allow-empty --push dev

From 981f9e333cb9ef4bb448aac136627af377054abe Mon Sep 17 00:00:00 2001
From: 7174Andy <hep003@ucsd.edu>
Date: Tue, 6 Jan 2026 11:39:32 -0800
Subject: [PATCH 3/5] add dark/light mode

---
 mkdocs.yml | 20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 1319d13..7d1db91 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,4 +1,22 @@
-site_name: My Docs
+site_name: Spendwise Documentation
 site_url: https://7174Andy.github.io/spendwise
 theme:
   name: material
+  palette:
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: deep orange
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - scheme: default
+      primary: deep orange
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+nav:
+  - Home: index.md
+  - Installation: installation.md

From a887273d37e5913ed54fb630555ea50b423d71f1 Mon Sep 17 00:00:00 2001
From: 7174Andy <hep003@ucsd.edu>
Date: Tue, 6 Jan 2026 11:39:38 -0800
Subject: [PATCH 4/5] add index

---
 docs/index.md | 87 ++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 75 insertions(+), 12 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 000ea34..639adbb 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,17 +1,80 @@
-# Welcome to MkDocs
+# Spendwise Expense Tracker
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+**Spendwise** is an open-source desktop application to track expenses by importing Bank of America PDF statements. It features intelligent merchant categorization, monthly spending statistics, and interactive heatmap visualizations to help you understand your spending patterns.
 
-## Commands
+## Features
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+- **PDF Statement Import** - Import Bank of America PDF statements with automatic transaction extraction
+- **Smart Categorization** - Intelligent merchant recognition with fuzzy matching (90% accuracy threshold)
+- **Transaction Management** - Add, edit, delete, and search transactions with pagination
+- **Monthly Statistics** - View net income and top spending categories by month
+- **Spending Heatmap** - Interactive calendar showing daily spending intensity with color-coded visualization
+- **Auto-Recategorization** - Update a merchant's category once, and similar transactions are automatically recategorized
 
-## Project layout
+## Installation
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+Spendwise is installed as a Python package. It is strongly recommended to install the package via [uv](https://docs.astral.sh/uv/).
+
+Latest versions of Spendwise can be seen in the [Release](https://github.com/7174Andy/expense-tracker/releases) page.
+
+### Requirements
+
+- Python 3.11 or higher
+- macOS, Linux, or Windows
+
+### Quick Install
+
+First, install `uv` if you haven't already:
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+Then, install Spendwise Tracker:
+
+```bash
+uv tool install spendwise-tracker
+```
+
+Run the GUI after installation:
+
+```bash
+expense-tracker
+```
+
+## Quick Start
+
+### Importing Transactions
+
+1. Click the **Import Statement** button in the Transactions tab
+2. Select a Bank of America PDF statement
+3. Transactions are automatically parsed and categorized
+
+### Managing Transactions
+
+- **View**: Browse transactions with pagination (100 per page)
+- **Search**: Use the search bar to filter transactions by keyword
+- **Add**: Click "Add Expense" to manually enter a transaction
+- **Edit**: Double-click a transaction or select and click "Edit"
+- **Delete**: Select a transaction and click "Delete"
+
+### Viewing Statistics
+
+1. Navigate to the **Statistics** tab
+2. Use the `<` and `>` buttons to browse months with transaction data
+3. View monthly net income and top spending category
+
+### Analyzing Spending Patterns
+
+1. Navigate to the **Heatmap** tab
+2. View daily spending amounts on an interactive calendar
+3. Darker colors indicate higher spending
+4. Click on any day to filter transactions by that date
+
+## License
+
+Spendwise is released under MIT License.

From dfa92779e29e5b555fb70488fc455183a5b1389a Mon Sep 17 00:00:00 2001
From: 7174Andy <hep003@ucsd.edu>
Date: Tue, 6 Jan 2026 11:39:43 -0800
Subject: [PATCH 5/5] add installation guide

---
 docs/installation.md | 198 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)
 create mode 100644 docs/installation.md

diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..40a62ee
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,198 @@
+# Installation Guide
+
+This guide will walk you through installing, verifying, and uninstalling Spendwise Tracker.
+
+## Requirements
+
+Before installing Spendwise Tracker, ensure your system meets the following requirements:
+
+- **Python**: Version 3.11 or higher
+- **Operating System**: macOS, Linux, or Windows
+- **uv**: Package installer (installation instructions below)
+
+## Installing uv
+
+Spendwise Tracker is distributed as a Python package and is best installed using [uv](https://docs.astral.sh/uv/), a fast Python package installer and resolver.
+
+### macOS and Linux
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Windows
+
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+After installation, you may need to restart your terminal or add uv to your PATH.
+
+## Installing Spendwise Tracker
+
+Once you have `uv` installed, you can install Spendwise Tracker using the `uv tool install` command:
+
+```bash
+uv tool install spendwise-tracker
+```
+
+This command will:
+
+1. Download the latest version of Spendwise Tracker from PyPI
+2. Install it in an isolated environment
+3. Make the `expense-tracker` command available in your terminal
+
+### Installing a Specific Version
+
+To install a specific version, use:
+
+```bash
+uv tool install spendwise-tracker==0.1.0
+```
+
+Check the [Releases](https://github.com/7174Andy/expense-tracker/releases) page for available versions.
+
+## Verifying the Installation
+
+After installation, verify that Spendwise Tracker is working correctly:
+
+### 1. Check the Command
+
+Verify that the `expense-tracker` command is available:
+
+```bash
+expense-tracker --version
+```
+
+This should display the installed version number.
+
+### 2. Launch the Application
+
+Start the application to ensure the GUI launches properly:
+
+```bash
+expense-tracker
+```
+
+The Spendwise Tracker GUI window should open. If the application starts successfully, the installation is complete!
+
+### 3. Verify Database Location
+
+On first launch, Spendwise Tracker will create its database files in a platform-specific location:
+
+- **macOS**: `~/Library/Application Support/spendwise-tracker/`
+- **Linux/Unix**: `~/.local/share/spendwise-tracker/`
+- **Windows**: `%LOCALAPPDATA%\spendwise-tracker\`
+
+You can verify these directories exist after launching the application once.
+
+## Troubleshooting
+
+### Command Not Found
+
+If you get a "command not found" error after installation:
+
+1. **Check if uv's bin directory is in your PATH**:
+
+   ```bash
+   echo $PATH  # macOS/Linux
+   echo %PATH% # Windows
+   ```
+
+2. **Add uv's bin directory to your PATH**:
+
+   - **macOS/Linux**: Add to `~/.bashrc` or `~/.zshrc`:
+     ```bash
+     export PATH="$HOME/.local/bin:$PATH"
+     ```
+   - **Windows**: uv typically adds itself to PATH automatically during installation
+
+3. **Restart your terminal** and try again
+
+### Python Version Issues
+
+If you encounter Python version errors:
+
+```bash
+# Check your Python version
+python --version
+```
+
+Or:
+
+```bash
+python3 --version
+```
+
+Ensure Python 3.11 or higher is installed. If not, install or update Python before proceeding.
+
+### Permission Errors
+
+On macOS/Linux, if you encounter permission errors, ensure you're not using `sudo`. The `uv tool install` command should work without elevated privileges.
+
+## Updating Spendwise Tracker
+
+To update to the latest version:
+
+```bash
+uv tool upgrade spendwise-tracker
+```
+
+To update to a specific version:
+
+```bash
+uv tool install spendwise-tracker==0.2.0 --force
+```
+
+## Uninstalling Spendwise Tracker
+
+### Uninstall the Application
+
+To remove Spendwise Tracker from your system:
+
+```bash
+uv tool uninstall spendwise-tracker
+```
+
+This will remove the application but **will not delete your data**.
+
+### Remove User Data
+
+If you also want to delete your transaction data and merchant categories, manually remove the data directory:
+
+#### macOS
+
+```bash
+rm -rf ~/Library/Application\ Support/spendwise-tracker/
+```
+
+#### Linux/Unix
+
+```bash
+rm -rf ~/.local/share/spendwise-tracker/
+```
+
+#### Windows
+
+```powershell
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\spendwise-tracker"
+```
+
+!!! warning "Data Loss Warning"
+Deleting the data directory will permanently remove all your transactions, merchant categories, and settings. This action cannot be undone. Make sure to back up your data if needed before proceeding.
+
+## Next Steps
+
+Now that you have Spendwise Tracker installed, check out:
+
+- [Quick Start Guide](quickstart.md) - Learn how to use the application
+- [User Guide](user-guide.md) - Detailed feature documentation
+- [FAQ](faq.md) - Common questions and answers
+
+## Getting Help
+
+If you encounter issues not covered in this guide:
+
+1. Check the [GitHub Issues](https://github.com/7174Andy/expense-tracker/issues) page
+2. Review the [FAQ](faq.md) documentation
+3. Open a new issue with details about your problem