feat: Add image lightbox for documentation screenshots

Add clickable lightbox functionality to make documentation screenshots
viewable in full resolution. Works on all screen sizes with responsive
styling and touch gestures for mobile.

Features:
- Click any screenshot to view full resolution in modal overlay
- Desktop: hover effect shows images are clickable
- Mobile: touch-optimized close button and swipe-down gesture
- Close with X button, Escape key, or clicking outside image
- Smooth fade animations and image captions
- Works with Material for MkDocs instant navigation

Also updated CLAUDE.md to memorialize reproducibility principles:
AI assistants must never modify environments with pip/uv pip install.
All dependencies go through pyproject.toml and uv sync.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: wesm

CLAUDE.md

@@ -8,7 +8,14 @@ moneyflow is a terminal-based UI for power users to manage personal finance tran
 
 ### Using uv (REQUIRED)
 
-**IMPORTANT**: This project uses **uv** exclusively for all development workflows. Always use `uv run` for executing scripts and `uv pip` for package management. Never use pip, pipenv, poetry, or other package managers.
+**IMPORTANT**: This project uses **uv** exclusively for all development workflows. Always use `uv run` for executing scripts. Never use pip, pipenv, poetry, or other package managers.
+
+**CRITICAL FOR AI ASSISTANTS (Claude Code, etc.)**:
+- ❌ **NEVER run `pip install` or `uv pip install` to modify the user's environment**
+- ❌ **NEVER run `uv tool install` for project dependencies**
+- ✅ All dependencies MUST be declared in `pyproject.toml` and installed via `uv sync`
+- ✅ Use `uv run <command>` to run tools in the project's virtual environment
+- 💡 This ensures **reproducibility** - anyone can clone the repo and run `uv sync` to get the exact same environment
 
 ```bash
 # Install uv if not already installed

docs/javascripts/lightbox.js

@@ -0,0 +1,107 @@
+/**
+ * Simple image lightbox for documentation screenshots
+ * Works on all screen sizes (desktop, tablet, mobile)
+ */
+
+(function() {
+  'use strict';
+
+  // Create lightbox elements
+  function createLightbox() {
+    const overlay = document.createElement('div');
+    overlay.id = 'lightbox-overlay';
+    overlay.innerHTML = `
+      <div class="lightbox-content">
+        <img id="lightbox-image" src="" alt="">
+        <button id="lightbox-close" aria-label="Close lightbox">&times;</button>
+        <div class="lightbox-caption"></div>
+      </div>
+    `;
+    document.body.appendChild(overlay);
+
+    // Close on overlay click (not on image or caption)
+    overlay.addEventListener('click', (e) => {
+      if (e.target === overlay || e.target.id === 'lightbox-close') {
+        closeLightbox();
+      }
+    });
+
+    // Close on Escape key
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && overlay.classList.contains('active')) {
+        closeLightbox();
+      }
+    });
+
+    // Support touch gestures for mobile
+    let touchStartY = 0;
+    overlay.addEventListener('touchstart', (e) => {
+      touchStartY = e.touches[0].clientY;
+    });
+
+    overlay.addEventListener('touchend', (e) => {
+      const touchEndY = e.changedTouches[0].clientY;
+      const swipeDistance = touchStartY - touchEndY;
+
+      // Swipe down to close (must swipe at least 100px)
+      if (swipeDistance < -100) {
+        closeLightbox();
+      }
+    });
+
+    return overlay;
+  }
+
+  // Open lightbox with image
+  function openLightbox(imgSrc, altText) {
+    const overlay = document.getElementById('lightbox-overlay') || createLightbox();
+    const lightboxImg = document.getElementById('lightbox-image');
+    const caption = overlay.querySelector('.lightbox-caption');
+
+    lightboxImg.src = imgSrc;
+    lightboxImg.alt = altText;
+    caption.textContent = altText;
+
+    overlay.classList.add('active');
+    document.body.style.overflow = 'hidden'; // Prevent scrolling
+  }
+
+  // Close lightbox
+  function closeLightbox() {
+    const overlay = document.getElementById('lightbox-overlay');
+    if (overlay) {
+      overlay.classList.remove('active');
+      document.body.style.overflow = ''; // Restore scrolling
+    }
+  }
+
+  // Make images clickable
+  function initLightbox() {
+    // Target all content images (screenshots)
+    const images = document.querySelectorAll('.md-content img');
+
+    images.forEach(img => {
+      // Skip if already processed
+      if (img.classList.contains('lightbox-enabled')) return;
+
+      // Add class and click handler
+      img.classList.add('lightbox-enabled');
+      img.title = img.alt + ' (click to enlarge)';
+
+      img.addEventListener('click', (e) => {
+        e.preventDefault();
+        openLightbox(img.src, img.alt);
+      });
+    });
+  }
+
+  // Initialize on page load
+  document.addEventListener('DOMContentLoaded', initLightbox);
+
+  // Re-initialize on Material for MkDocs instant navigation
+  if (typeof document$ !== 'undefined') {
+    document$.subscribe(() => {
+      initLightbox();
+    });
+  }
+})();

docs/stylesheets/extra.css

@@ -162,6 +162,119 @@
   display: none;
 }
 
+/* Lightbox styles - all screen sizes */
+/* Make images appear clickable */
+.md-content img.lightbox-enabled {
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+/* Desktop hover effect */
+@media (min-width: 76.1875em) {
+  .md-content img.lightbox-enabled:hover {
+    transform: scale(1.02);
+    box-shadow: 0 6px 16px rgba(0,0,0,0.2);
+  }
+}
+
+/* Lightbox overlay */
+#lightbox-overlay {
+  display: none;
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: rgba(0, 0, 0, 0.95);
+  z-index: 10000;
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+#lightbox-overlay.active {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  opacity: 1;
+}
+
+/* Lightbox content container */
+.lightbox-content {
+  position: relative;
+  max-width: 95%;
+  max-height: 95%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+/* Lightbox image */
+#lightbox-image {
+  max-width: 100%;
+  max-height: 85vh;
+  object-fit: contain;
+  border-radius: 4px;
+  box-shadow: 0 8px 32px rgba(0,0,0,0.5);
+}
+
+/* Close button */
+#lightbox-close {
+  position: absolute;
+  top: -40px;
+  right: 0;
+  background: none;
+  border: none;
+  color: white;
+  font-size: 40px;
+  cursor: pointer;
+  padding: 0;
+  width: 40px;
+  height: 40px;
+  line-height: 1;
+  opacity: 0.8;
+  transition: opacity 0.2s ease;
+}
+
+#lightbox-close:hover,
+#lightbox-close:active {
+  opacity: 1;
+}
+
+/* Caption */
+.lightbox-caption {
+  color: white;
+  text-align: center;
+  margin-top: 1rem;
+  font-size: 0.9rem;
+  max-width: 90%;
+}
+
+/* Mobile-specific adjustments */
+@media (max-width: 76.1875em) {
+  #lightbox-overlay {
+    background-color: rgba(0, 0, 0, 0.98);
+  }
+
+  #lightbox-image {
+    max-height: 90vh;
+  }
+
+  #lightbox-close {
+    top: 10px;
+    right: 10px;
+    font-size: 50px;
+    width: 50px;
+    height: 50px;
+    background-color: rgba(0, 0, 0, 0.5);
+    border-radius: 50%;
+  }
+
+  .lightbox-caption {
+    font-size: 0.8rem;
+    padding: 0 1rem;
+  }
+}
+
 /* Mobile optimizations */
 @media (max-width: 76.1875em) {
   /* Smaller hero title on mobile */

mkdocs.yml

@@ -54,6 +54,9 @@ extra_css:
   - stylesheets/extra.css
   - stylesheets/terminal.css
 
+extra_javascript:
+  - javascripts/lightbox.js
+
 extra:
   social:
     - icon: fontawesome/brands/github