wesm · wesm · Nov 15, 2025 · Nov 15, 2025 · Nov 15, 2025 · Nov 15, 2025
@@ -38,6 +38,17 @@ jobs:
           uv pip install --system mkdocs-material mkdocs-material-extensions
           npm install -g markdownlint-cli
 
+      - name: Sync project dependencies
+        run: |
+          uv sync
+
+      - name: Generate screenshots
+        run: |
+          uv run python scripts/generate_screenshots.py
+        env:
+          # Use headless mode for CI
+          TERM: xterm-256color
+
       - name: Check for arrow-based pseudo-lists
         run: |
           .github/scripts/check-arrow-lists.sh
@@ -53,5 +64,6 @@ jobs:
       - name: Summary
         run: |
           echo "✅ Documentation builds successfully" >> $GITHUB_STEP_SUMMARY
+          echo "🎬 Screenshots generated for build verification" >> $GITHUB_STEP_SUMMARY
           echo "📁 Built site is in site/ directory (not deployed)" >> $GITHUB_STEP_SUMMARY
           echo "ℹ️  Deployment only happens from stable branch" >> $GITHUB_STEP_SUMMARY
@@ -31,12 +31,24 @@ jobs:
         run: |
           uv pip install --system mkdocs-material mkdocs-material-extensions
 
+      - name: Sync project dependencies
+        run: |
+          uv sync
+
+      - name: Generate screenshots
+        run: |
+          uv run python scripts/generate_screenshots.py
+        env:
+          # Use headless mode for CI
+          TERM: xterm-256color
+
       - name: Build and deploy
         run: |
           mkdocs gh-deploy --force
 
       - name: Summary
         run: |
           echo "📚 Documentation deployed to GitHub Pages from stable branch" >> $GITHUB_STEP_SUMMARY
+          echo "🎬 Screenshots generated and included in build" >> $GITHUB_STEP_SUMMARY
           echo "🌐 Site will be available at: https://moneyflow.dev" >> $GITHUB_STEP_SUMMARY
           echo "⚠️  Only released features (from stable branch) are published" >> $GITHUB_STEP_SUMMARY
diff --git a/.gitignore b/.gitignore
@@ -49,6 +49,10 @@ htmlcov/
 .DS_Store
 site/
 
+# Generated documentation assets
+docs/assets/screenshots/*.svg
+docs/assets/screenshots/*.png
+
 # Nix
 result
 result-*
diff --git a/PUBLISHING.md b/PUBLISHING.md
@@ -83,9 +83,9 @@ git push && git push --tags
 ```
 
 This automates:
-- Generating latest screenshots
-- Committing to moneyflow-assets with squashed history
+
 - Updating stable branch to release tag
+- Pushing to GitHub (triggers docs deployment with screenshot generation)
 
 ---
 
@@ -123,6 +123,7 @@ TestPyPI allows re-uploads for testing.
 ### uvx can't find command after install
 
 Check entry point in pyproject.toml:
+
 ```toml
 [project.scripts]
 moneyflow = "moneyflow.app:main"
@@ -134,6 +135,6 @@ moneyflow = "moneyflow.app:main"
 
 Your package will be available at:
 
-- **PyPI**: https://pypi.org/project/moneyflow/
+- **PyPI**: <https://pypi.org/project/moneyflow/>
 - **Install**: `pip install moneyflow`
 - **Run**: `uvx moneyflow`
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 A keyboard-driven terminal UI for managing personal finance transactions. Built for users who prefer efficiency and
 direct control over their financial data.
 
-![moneyflow main screen](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/home-screen.svg)
+![moneyflow main screen](https://moneyflow.dev/assets/screenshots/home-screen.svg)
 
 **Supported Platforms:**
 

diff --git a/docs/assets/screenshots/.gitkeep b/docs/assets/screenshots/.gitkeep
diff --git a/docs/guide/editing.md b/docs/guide/editing.md
@@ -65,7 +65,7 @@ This workflow gives you precise control over merchant names while making it easy
 
 Select multiple transactions to edit them all at once:
 
-![Multi-select transactions with checkmarks](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/drill-down-detail-multi-select.svg)
+![Multi-select transactions with checkmarks](../assets/screenshots/drill-down-detail-multi-select.svg)
 
 1. Press ++space++ on each transaction you want to edit
    - A `✓` checkmark appears
@@ -90,7 +90,7 @@ Select multiple transactions to edit them all at once:
 From any aggregate view (Merchants, Categories, Groups, Accounts), press ++m++, ++c++, or ++h++ to edit ALL
 transactions in that group:
 
-![Bulk edit merchant modal](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/drill-down-bulk-edit-merchant.svg)
+![Bulk edit merchant modal](../assets/screenshots/drill-down-bulk-edit-merchant.svg)
 
 ### Example: Rename a merchant (all transactions)
 
@@ -100,7 +100,7 @@ transactions in that group:
 4. Type "Amazon" and press ++enter++
 5. ALL transactions for that merchant are renamed
 
-![Edit category selection](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/drill-down-edit-category.svg)
+![Edit category selection](../assets/screenshots/drill-down-edit-category.svg)
 
 ### Multi-Select Groups (NEW!)
 

diff --git a/docs/guide/filters.md b/docs/guide/filters.md
@@ -53,4 +53,4 @@ More advanced filtering capabilities (by amount range, date range, merchant patt
 are planned for future releases.
 
 For now, use [Search](navigation.md#search) to filter by text matching,
-and [Time Navigation](navigation.md#time-navigation) to filter by date.
+and [Time Navigation](navigation.md#time-as-an-aggregate-dimension) to filter by date.
diff --git a/docs/guide/monarch.md b/docs/guide/monarch.md
@@ -47,15 +47,15 @@ moneyflow
 
 On first run, you'll be prompted to select a backend:
 
-![Backend selection](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/backend-select.svg)
+![Backend selection](../assets/screenshots/backend-select.svg)
 
 Select **Monarch Money**.
 
 ### 2. Enter Monarch Money Credentials
 
 You'll see the credential setup screen:
 
-![Credential setup screen](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/monarch-credentials.svg)
+![Credential setup screen](../assets/screenshots/monarch-credentials.svg)
 
 Enter:
 

diff --git a/docs/guide/navigation.md b/docs/guide/navigation.md
@@ -17,41 +17,41 @@ amount spent.
 <tr>
 <td width="50%">
 <strong>Merchant View</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/cycle-1-merchants.svg" width="100%"
+<img src="../assets/screenshots/cycle-1-merchants.svg" width="100%"
 alt="Merchants view">
 </td>
 <td width="50%">
 <strong>Category View</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/cycle-2-categories.svg" width="100%"
+<img src="../assets/screenshots/cycle-2-categories.svg" width="100%"
 alt="Categories view">
 </td>
 </tr>
 <tr>
 <td width="50%">
 <strong>Group View</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/cycle-3-groups.svg" width="100%" alt="Groups view">
+<img src="../assets/screenshots/cycle-3-groups.svg" width="100%" alt="Groups view">
 </td>
 <td width="50%">
 <strong>Account View</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/cycle-4-accounts.svg" width="100%" alt="Accounts view">
+<img src="../assets/screenshots/cycle-4-accounts.svg" width="100%" alt="Accounts view">
 </td>
 </tr>
 <tr>
 <td width="50%">
 <strong>TIME View (by Years)</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/cycle-5-time-years.svg" width="100%"
+<img src="../assets/screenshots/cycle-5-time-years.svg" width="100%"
 alt="Time view by years">
 </td>
 <td width="50%">
 <strong>TIME View (by Months)</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/time-view-months.svg" width="100%"
+<img src="../assets/screenshots/time-view-months.svg" width="100%"
 alt="Time view by months">
 </td>
 </tr>
 <tr>
 <td width="50%">
 <strong>TIME View (by Days)</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/time-view-days.svg" width="100%"
+<img src="../assets/screenshots/time-view-days.svg" width="100%"
 alt="Time view by days">
 </td>
 <td width="50%">
@@ -120,13 +120,13 @@ To return to an aggregate view, press `g` or `Escape`.
 - Multi-select for bulk operations
 - View full transaction details
 
-![Detail view with indicators](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/detail-view-flags.svg)
+![Detail view with indicators](../assets/screenshots/detail-view-flags.svg)
 
 ## Drill-Down
 
 From any aggregate view, press `Enter` on a row to drill into it and see the individual transactions that make up that aggregate.
 
-![Merchant view with Amazon highlighted](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/merchants-view.svg)
+![Merchant view with Amazon highlighted](../assets/screenshots/merchants-view.svg)
 
 **Example workflow:**
 
@@ -135,7 +135,7 @@ From any aggregate view, press `Enter` on a row to drill into it and see the ind
 3. **Press `Enter`** - Drill down to see transactions
 4. **View results** - All Amazon transactions displayed
 
-![Drilled down into Amazon - transaction detail view](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/drill-down-detail.svg)
+![Drilled down into Amazon - transaction detail view](../assets/screenshots/drill-down-detail.svg)
 
 The breadcrumb shows your current path: `Merchants > Amazon`
 
@@ -161,9 +161,9 @@ This allows you to analyze the same transactions from multiple perspectives with
 6. **Press `g` again** - Returns to detail view
    - Shows all Amazon transactions ungrouped
 
-![Drilled into Merchant, grouped by Category](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/merchants-drill-by-category.svg)
+![Drilled into Merchant, grouped by Category](../assets/screenshots/merchants-drill-by-category.svg)
 
-![Drilled into Amazon, grouped by Account](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/drill-down-group-by-account.svg)
+![Drilled into Amazon, grouped by Account](../assets/screenshots/drill-down-group-by-account.svg)
 
 Sub-grouping helps answer analytical questions like:
 
@@ -189,7 +189,7 @@ You can drill down from sub-grouped views to add another level of filtering, cre
 4. **View results** - Breadcrumb shows: `Merchants > Amazon > Groceries`
    - Now viewing only Amazon grocery transactions
 
-![Multi-level drill-down breadcrumb](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/drill-down-multi-level.svg)
+![Multi-level drill-down breadcrumb](../assets/screenshots/drill-down-multi-level.svg)
 
 This powerful feature lets you combine multiple filters to answer very specific questions about your spending.
 
@@ -267,12 +267,12 @@ From TIME view, press `Enter` on any year, month, or day to drill down and see o
 <tr>
 <td width="50%">
 <strong>Drilled Into Year</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/time-drill-down-year.svg" width="100%"
+<img src="../assets/screenshots/time-drill-down-year.svg" width="100%"
 alt="Drilled into specific year">
 </td>
 <td width="50%">
 <strong>Drilled Into Month</strong><br>
-<img src="https://raw.githubusercontent.com/wesm/moneyflow-assets/main/time-drill-down-month.svg" width="100%"
+<img src="../assets/screenshots/time-drill-down-month.svg" width="100%"
 alt="Drilled into specific month">
 </td>
 </tr>
@@ -331,7 +331,7 @@ moneyflow --mtd                 # Fetch month-to-date only
 
 Press `/` to search and filter transactions by text matching across merchant names, categories, and transaction notes.
 
-![Search modal](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/search-modal.svg)
+![Search modal](../assets/screenshots/search-modal.svg)
 
 **Using search:**
 
@@ -340,7 +340,7 @@ Press `/` to search and filter transactions by text matching across merchant nam
 3. **Press `Enter`** - Applies the search filter
 4. **Press `Escape`** - Clears search and returns to previous view
 
-![Search results for "coffee"](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/merchants-search.svg)
+![Search results for "coffee"](../assets/screenshots/merchants-search.svg)
 
 Search filters persist as you navigate between different views. The breadcrumb displays "Search: your query" to remind
 you that search is active. To clear a search, press `/` again and submit an empty search, or press `Escape` if search

diff --git a/docs/guide/ynab.md b/docs/guide/ynab.md
@@ -44,15 +44,15 @@ moneyflow
 
 On first run, you'll be prompted to select a backend:
 
-![Backend selection](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/backend-select.svg)
+![Backend selection](../assets/screenshots/backend-select.svg)
 
 Select **YNAB**.
 
 ### 2. Enter YNAB Credentials
 
 You'll see the credential setup screen:
 
-![Credential setup screen](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/ynab-credentials.svg)
+![Credential setup screen](../assets/screenshots/ynab-credentials.svg)
 
 Enter:
 

diff --git a/docs/index.md b/docs/index.md
@@ -7,7 +7,7 @@
 
 ## Terminal UI for personal finance power users
 
-![moneyflow terminal UI](https://raw.githubusercontent.com/wesm/moneyflow-assets/main/home-screen.svg)
+![moneyflow terminal UI](assets/screenshots/home-screen.svg)
 
 ```bash
 # Install and run

diff --git a/scripts/README.md b/scripts/README.md
@@ -9,15 +9,12 @@ Automatically generate all documentation screenshots using Textual's pilot API a
 ### Quick Start
 
 ```bash
-# Generate all screenshots (saves to ../moneyflow-assets/)
+# Generate all screenshots (saves to docs/assets/screenshots/)
 uv run python scripts/generate_screenshots.py
 
 # Generate and convert to PNG
 uv run python scripts/generate_screenshots.py --png
 
-# Use custom font
-uv run python scripts/generate_screenshots.py --font "JetBrains Mono"
-
 # Custom output directory
 uv run python scripts/generate_screenshots.py --output-dir ~/my-screenshots
 ```
@@ -27,10 +24,12 @@ uv run python scripts/generate_screenshots.py --output-dir ~/my-screenshots
 The script generates all screenshots referenced in the documentation:
 
 **Setup Screens:**
+
 - `backend-select.svg` - Backend selection screen
 - `monarch-credentials.svg` - Monarch credential setup
 
 **Demo Mode Screens:**
+
 - `home-screen.svg` - Main home screen
 - `cycle-1-merchants.svg` - Merchants aggregation view
 - `cycle-2-categories.svg` - Categories aggregation view
@@ -50,20 +49,18 @@ The script generates all screenshots referenced in the documentation:
 
 ### Workflow
 
-After generating screenshots:
+Screenshots are generated automatically during the docs deployment workflow when pushing to the `stable` branch.
+
+For local development:
 
 ```bash
-# Navigate to moneyflow-assets repo
-cd ../moneyflow-assets
+# Generate screenshots locally
+uv run python scripts/generate_screenshots.py
 
-# Review changes
-git status
-git diff
+# Preview docs with screenshots
+mkdocs serve
 
-# Commit and push
-git add *.svg *.png
-git commit -m "Update documentation screenshots"
-git push
+# Screenshots are gitignored and will be regenerated in CI
 ```
 
 ### Requirements
@@ -109,18 +106,8 @@ async def screenshot_new_feature(self, filename: str, description: str):
 
 ### Troubleshooting
 
-**"Output directory does not exist"**
-```bash
-# Clone the moneyflow-assets repo as a sibling
-git clone git@github.com:wesm/moneyflow-assets.git ../moneyflow-assets
-```
-
-**Font not rendering in SVG**
-- Make sure the font is installed on your system
-- SVG viewers may fall back to default monospace if font is unavailable
-- PNG conversion requires the font to be installed
+#### PNG conversion fails
 
-**PNG conversion fails**
 ```bash
 # Install cairosvg
 uv pip install cairosvg
@@ -135,4 +122,4 @@ brew install cairo pango gdk-pixbuf libffi
 - `test-build.sh` - Test package build locally
 - `publish-testpypi.sh` - Publish to TestPyPI for testing
 - `publish-pypi.sh` - Publish to production PyPI
-- `post-publish.sh` - Post-publish automation (screenshots, assets, stable branch)
+- `post-publish.sh` - Post-publish automation (update stable branch, trigger docs deployment)