difflicious 0.13.0__tar.gz → 0.14.0__tar.gz

{difflicious-0.13.0 → difflicious-0.14.0}/.github/workflows/check-version-bump.yml

@@ -1,14 +1,13 @@
 name: Check Version Bump
 
+# `pull_request` only. Registering `pull_request_target` as well ran the job a
+# second time with the base checked out as the head, so it compared main against
+# main and reported "Version was not bumped" on every genuine version bump.
 on:
   pull_request:
     paths:
       - 'src/difflicious/__init__.py'
       - 'CHANGELOG.md'
-  pull_request_target:
-    paths:
-      - 'src/difflicious/__init__.py'
-      - 'CHANGELOG.md'
 
 permissions:
   pull-requests: write

{difflicious-0.13.0 → difflicious-0.14.0}/.github/workflows/ci.yml

@@ -59,12 +59,12 @@ jobs:
     - name: Install pnpm
       uses: pnpm/action-setup@v4
       with:
-        version: 9
+        version: 11
 
     - name: Set up Node.js
       uses: actions/setup-node@v4
       with:
-        node-version: '18'
+        node-version: '22'
         cache: 'pnpm'
 
     - name: Install JavaScript dependencies

{difflicious-0.13.0 → difflicious-0.14.0}/.github/workflows/docker-publish.yml

@@ -78,3 +78,12 @@ jobs:
         labels: ${{ steps.meta.outputs.labels }}
         cache-from: type=gha
         cache-to: type=gha,mode=max
+
+    - name: Update Docker Hub description
+      if: github.event_name != 'pull_request'
+      uses: peter-evans/dockerhub-description@v4
+      with:
+        username: ${{ secrets.DOCKER_USERNAME }}
+        password: ${{ secrets.DOCKER_HUB_TOKEN }}
+        repository: ${{ github.repository }}
+        readme-filepath: ./README.md

{difflicious-0.13.0 → difflicious-0.14.0}/.gitignore

@@ -116,3 +116,11 @@ vendor/
 .coverage
 coverage.xml
 vendor/
+
+# Git worktrees live inside the repo so they are easy to find; git tracks them
+# via .git/worktrees, so the checkouts themselves must never be added.
+.worktrees/
+
+# Working notes. The rule is shared so everyone gets the same convention and
+# their own private file; the contents are never committed.
+.notes/

{difflicious-0.13.0 → difflicious-0.14.0}/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to difflicious will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2026-08-23
+
+### Themes & Interface
+
+The interface is rebuilt on a theme layer. Every design decision — colour,
+spacing, radius, border width, typography, shadow, motion, density — now lives in
+`static/css/themes/`, and a theme can be swapped without touching anything else.
+See [`docs/THEMING.md`](docs/THEMING.md).
+
+### Added
+- **Three themes** — `ledger` (default, warm paper and ochre), `slate` (cool
+  greys and indigo), `sorbet` (bright, rounded, turquoise). Each ships light and
+  dark variants as peers, not as a filter over one another
+- **Theme selection** — `--theme` or `DIFFLICIOUS_THEME`, listed with
+  `--list-themes`. A value that looks like a URL is loaded as a custom
+  stylesheet, named after its file
+- **Per-theme typefaces** — a theme declares its own display and UI faces; only
+  the selected theme's fonts are fetched
+- **Theme gallery** — thumbnails of every theme in both schemes in the theming
+  docs, and `scripts/screenshot.py --all-themes` to regenerate them
+
+### Fixed
+- **Dark-mode syntax highlighting** — Pygments ran with `noclasses=True`, baking
+  one theme's colours inline server-side where no stylesheet could override
+  them, while the theme is switched in the browser. Dark mode had been showing
+  light-theme code colours. The formatter is now class-based
+- **Syntax CSS was never injected** — a formatter had split `{{ syntax_css }}`
+  into `{ { … } }`, so the block rendered as literal text
+- **Dark-mode overrides fighting the theme** — around 250 lines of `!important`
+  rules with hardcoded colours, most of them matching classes the templates no
+  longer emit, prevented a theme change taking full effect
+- **Sticky file headers** — restored; they had been disabled by an `overflow`
+  rule on the file card
+- **Empty bar above every file header** — a masking strip had become the only
+  separation between cards, which were otherwise flush. Cards now have a real gap
+- **Whole expansion strip is clickable** — expanding context no longer requires
+  hitting a 28px pill, and the row is keyboard-operable
+- **JavaScript linting** — `lint:js` never checked two source files, because npm
+  runs scripts through a shell where `**` is not recursive
+- **Lockfile** — `playwright` was declared in `pyproject.toml` but missing from
+  `uv.lock`, so every `uv run` re-resolved and rewrote it
+
+### Changed
+- **pnpm 11** in CI, matching local development
+- **Git worktrees** may live in `.worktrees/` inside the repo; the file watcher
+  and test runners ignore them
+- **Docs** — completed plans and superseded specs archived under
+  `docs/internal/archive/`; the CSS style guide is retired in favour of
+  `docs/THEMING.md`
+- Removed the stray `package-lock.json`; the project is pnpm throughout
+
 ## [0.13.0] - 2026-04-14
 
 ### Release Automation & Infrastructure
@@ -31,7 +82,7 @@ Automated version management and release processes to streamline development wor
 
 ### Presentation Layer Separation
 
-Enforced explicit contracts between the data, service, template, CSS, and JS layers. Full design rationale in [`docs/presentation-layer-separation.md`](docs/presentation-layer-separation.md).
+Enforced explicit contracts between the data, service, template, CSS, and JS layers. Full design rationale in [`docs/internal/archive/presentation-layer-separation.md`](docs/internal/archive/presentation-layer-separation.md).
 
 ### Changed
 - **Removed dual state** — deleted `state.js` and `file-operations.js`; `diffStore` is now the single source of truth for expansion state
@@ -45,7 +96,13 @@ Enforced explicit contracts between the data, service, template, CSS, and JS lay
 - **File content animation** — removed vertical scale transform; transition is now a plain opacity fade
 - **Ctrl+C shutdown** — SIGINT now triggers `os._exit(0)` matching the existing SIGTERM handler, so a single keypress exits cleanly regardless of open SSE connections
 
-## [1.0.0] - 2026-02-06
+## [1.0.0] - 2026-02-06 — never released
+
+> **This release does not exist.** It was published in error and withdrawn: there
+> is no `v1.0.0` tag, and no 1.0.0 on PyPI. Development continued from 0.11.0.
+> The entry is kept so the mistake is on the record rather than an unexplained
+> gap, but nothing below shipped under this version number — the changes went out
+> in 0.11.0 and later.
 
 ### Stable Release
 

{difflicious-0.13.0 → difflicious-0.14.0}/CLAUDE.md

@@ -147,10 +147,11 @@ Difflicious supports the following environment variables for configuration:
 | `DIFFLICIOUS_PORT` | `5000` | Port to run the web server on |
 | `DIFFLICIOUS_HOST` | `127.0.0.1` | Host to bind the web server to |
 | `DIFFLICIOUS_FONT` | `jetbrains-mono` | Programming font (see `--list-fonts`) |
+| `DIFFLICIOUS_THEME` | `ledger` | Colour theme (see `--list-themes`) |
 | `DIFFLICIOUS_DISABLE_GOOGLE_FONTS` | `false` | Disable Google Fonts CDN |
 | `DIFFLICIOUS_AUTO_RELOAD` | `true` | Enable auto-reload on file changes |
 | `DIFFLICIOUS_WATCH_DEBOUNCE` | `1.0` | Debounce time (seconds) for file watcher |
-| `DIFFLICIOUS_WATCH_IGNORE` | `.git` | Patterns to ignore for file watching |
+| `DIFFLICIOUS_WATCH_IGNORE` | `.git,.worktrees` | Patterns to ignore for file watching |
 | `DIFFLICIOUS_DEBUG` | `false` | Enable verbose debug logging in browser console |
 
 **Example usage:**
@@ -216,8 +217,8 @@ DIFFLICIOUS_AUTO_RELOAD=false difflicious
 - ✅ **Docker Support**: Production-ready containerization with Alpine Linux
 - ✅ **Real-time Updates**: Server-Sent Events implementation for live status monitoring
 - ✅ **Modular Frontend**: ES6 module architecture for maintainable JavaScript
-- 🚧 **Word-level Diffs**: Advanced word-diff parsing (future enhancement)
-- 🚧 **Keyboard Shortcuts**: Accessibility and power-user features (planned)
+- ✅ **Theming**: Three built-in themes, selectable at startup, with light and dark variants
+- ✅ **Sticky File Headers**: File headers pin to the top while scrolling a diff
 
 ## Security Requirements (IMPLEMENTED)
 
@@ -301,7 +302,7 @@ All API endpoints return JSON responses with consistent error handling via the b
 **Modifying Styles:**
 1. Add Tailwind utilities in templates for layout/spacing
 2. Add custom styles in `static/css/styles.css` for components
-3. Use CSS variables for all colors (see CSS Style Guide)
+3. Use tokens for all colours (see `docs/THEMING.md`)
 4. Rebuild Tailwind: `pnpm run tailwind:build`
 5. Test both light and dark themes
 
@@ -314,93 +315,54 @@ All API endpoints return JSON responses with consistent error handling via the b
 - **Security**: All git command execution must use proper subprocess sanitization
 - **Type Hints**: All new Python code should include type hints (enforced by mypy via cilicious.sh)
 - **Docstrings**: All public functions/classes should have docstrings
-- **CSS Guidelines**: Follow the CSS Style Guide for all styling changes (see below)
+- **CSS Guidelines**: Follow `docs/THEMING.md` for all styling changes (see below)
 - **Testing**: All tests must pass via cilicious.sh (both Python pytest and JavaScript Jest)
 - **Linting**: Code must pass all linters via cilicious.sh (ruff, black, eslint)
 
-## CSS Architecture & Guidelines
+## CSS Architecture & Theming
 
-**IMPORTANT:** Difflicious uses a semantic CSS variable system. Always follow these guidelines:
+**IMPORTANT:** Every design decision — colour, spacing, radius, border width,
+typography, shadow, motion, density — lives in `src/difflicious/static/css/themes/`.
+Read `docs/THEMING.md` before making any styling change.
 
-### Core Principles
+### The rule
 
-1. **CSS Variables for Colors** - ALWAYS use CSS variables, NEVER hardcode hex values
-2. **Tailwind for Utilities Only** - Layout, spacing, typography (NOT colors)
-3. **Semantic Class Names** - Describe purpose, not appearance
-4. **Both Themes** - Always test light AND dark themes
-
-### Quick Reference
-
-**✅ DO:**
-```css
-.component {
-    background: var(--surface-secondary);
-    color: var(--text-primary);
-    border: 1px solid var(--border-default);
-}
-```
-
-```html
-<span class="status-badge status-badge-added">added</span>
-```
-
-**❌ DON'T:**
-```css
-.component {
-    background: #f8fafc;  /* Hardcoded! */
-    color: green;         /* Won't respect theme! */
-}
 ```
-
-```html
-<span class="bg-green-100 text-green-800">  <!-- Don't use Tailwind colors! -->
+themes/_contract.css  →  theme-independent scales, density knobs, aliases
+themes/<name>.css     →  palette + semantic roles for one theme
+styles.css            →  structure and layout only; consumes tokens
+templates             →  semantic classes only; never Tailwind colour utilities
 ```
 
-### Common Color Variables
+`styles.css` contains no literal colours, radii or shadows. If a value needs to
+be tunable, add a token to the contract and reference it — do not inline it.
 
-- `--surface-primary` - Page background
-- `--surface-secondary` - Cards, panels
-- `--text-primary` - Main text
-- `--text-secondary` - Secondary text
-- `--border-default` - Standard borders
-- `--semantic-success-bg-subtle` - Success badges/states
-- `--semantic-danger-bg-subtle` - Error badges/states
+### Never reference another theme's palette
 
-### Component Classes Available
+Tokens prefixed `--theme-<name>-*` are private to the theme that declares them.
+The contract, `styles.css` and templates may only use semantic roles
+(`--surface-*`, `--text-*`, `--border-*`, `--accent-*`, `--diff-*`), which every
+theme declares. Pointing at `--theme-paper-500` resolves to nothing under any
+theme but Ledger.
 
-- `.status-badge .status-badge-{added|deleted|renamed|modified}` - Status indicators
-- `.file-stat .file-stat-{addition|deletion}` - File change counts
+### Themes
 
-### Tailwind Usage
+`ledger` (default), `slate`, `sorbet`. Select with `--theme` or
+`DIFFLICIOUS_THEME`; `--list-themes` shows them. A value that looks like a URL is
+loaded as a custom stylesheet named after its file.
 
-**Use Tailwind for:**
-- Layout: `flex`, `grid`, `space-x-4`
-- Spacing: `p-4`, `m-2`, `px-3`
-- Typography: `text-sm`, `font-mono`
-- Display: `block`, `hidden`
+### Both themes, every time
 
-**DON'T use Tailwind for:**
-- Colors (use CSS variables)
-- Dark mode (use `[data-theme="dark"]`)
-- Complex components (use semantic classes)
+Light and dark are peers. Every semantic token is declared in both blocks of a
+theme file, and every UI change must be checked in both.
 
-### CSS File Rebuilding
+### Rebuilding Tailwind
 
-When modifying Tailwind config or input CSS:
 ```bash
 pnpm run tailwind:build
 ```
 
-### Complete Documentation
-
-For comprehensive CSS guidelines, see: `docs/CSS-STYLE-GUIDE.md`
-
-This includes:
-- Complete list of CSS variables by category
-- How to create new component classes
-- Dark mode implementation details
-- Common patterns and examples
-- Best practices and migration guide
+Tailwind is for layout, spacing and typography only — never colours or dark mode.
 
 ## Project Structure
 
@@ -484,9 +446,12 @@ difflicious/
 │   └── js/                   # JavaScript tests
 │
 ├── docs/                     # Documentation
-│   ├── CSS-STYLE-GUIDE.md    # CSS conventions
+│   ├── THEMING.md            # Themes and design tokens
 │   ├── TROUBLESHOOTING.md    # Common issues
-│   └── javascript-modularization-plan.md
+│   ├── internal/             # Working notes, reports, session logs
+│   │   └── archive/          # Completed plans and superseded specs
+│   ├── screenshots/          # README screenshots
+│   └── site/                 # GitHub Pages content
 │
 ├── pyproject.toml            # Python project configuration
 ├── uv.lock                   # uv lockfile
@@ -541,9 +506,13 @@ The application is designed for multiple distribution channels:
 - `INSTALLATION.md` - Installation and usage guide (PyPI, Docker, configuration)
 
 **Technical Guides:**
-- `docs/CSS-STYLE-GUIDE.md` - Comprehensive CSS architecture and conventions
+- `docs/THEMING.md` - Themes, design tokens, and how to add a theme
 - `docs/TROUBLESHOOTING.md` - Common issues and solutions
-- `docs/javascript-modularization-plan.md` - Frontend architecture decisions
+
+**Archive:**
+- `docs/internal/archive/` - Completed plans and superseded specs, kept for
+  context only. Do not treat anything there as a description of current
+  behaviour; see `docs/internal/archive/README.md` for the index.
 
 **Keep these files synchronized when making architectural changes!**
 

{difflicious-0.13.0 → difflicious-0.14.0}/INSTALLATION.md

@@ -13,7 +13,7 @@ This guide covers installing and running difflicious locally for developers.
 ## Quick Start
 
 For the fastest path to running difflicious, follow the quick-start steps in
-the [README](../README.md#installation--quick-start). This guide focuses on
+the [README](README.md#installation--quick-start). This guide focuses on
 detailed configuration, Docker workflows, and troubleshooting.
 
 ## PyPI Installation
@@ -287,10 +287,10 @@ docker logs <container-id>
 docker images insipid/difflicious
 ```
 
-For more troubleshooting help, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+For more troubleshooting help, see [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
 
 ## Next Steps
 
-- Check [troubleshooting](TROUBLESHOOTING.md) for common issues
-- Read the main [README](../README.md) for features
-- Explore [DEVELOPING.md](../DEVELOPING.md) for development setup and workflow
+- Check [troubleshooting](docs/TROUBLESHOOTING.md) for common issues
+- Read the main [README](README.md) for features
+- Explore [DEVELOPING.md](DEVELOPING.md) for development setup and workflow

{difflicious-0.13.0 → difflicious-0.14.0}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: difflicious
-Version: 0.13.0
-Summary: A sleek web-based git diff visualization tool for developers
+Version: 0.14.0
+Summary: A local web diff viewer for git diffs of a working directory
 Project-URL: Homepage, https://github.com/insipid/difflicious
 Project-URL: Repository, https://github.com/insipid/difflicious
 Project-URL: Issues, https://github.com/insipid/difflicious/issues
@@ -38,34 +38,62 @@ Description-Content-Type: text/markdown
 
 # Difflicious
 
-[![PyPI version](https://img.shields.io/pypi/v/difflicious.svg)](https://pypi.org/project/difflicious/)
-[![Python versions](https://img.shields.io/pypi/pyversions/difflicious.svg)](https://pypi.org/project/difflicious/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<div align="center">
+  <img src="docs/site/assets/logo.png" width="160" alt="Difflicious">
+  <p><em>A local diff viewer for comparing your working directory to any branch, not just HEAD.<br>
+  No forge, no push — just run it in your repo.</em></p>
+</div>
 
-A local web application for reviewing git diffs. Run it in your working directory and view your changes in a browser with side-by-side visualization, syntax highlighting, and context expansion.
+---
 
 ## Screenshots
 
-| Light mode | Dark mode |
-|------------|-----------|
-| ![Light mode](docs/screenshots/light.png) | ![Dark mode](docs/screenshots/dark.png) |
+<p align="center">
+  <img src="docs/screenshots/light.png" width="49%" alt="Light mode">
+  <img src="docs/screenshots/dark.png" width="49%" alt="Dark mode">
+</p>
+
+## Usage
+
+The quickest way — no install required:
+
+```bash
+uvx difflicious
+```
+
+Or with Docker:
+
+```bash
+docker run -it --rm -v "$PWD:/workspace" -p 5000:5000 insipid/difflicious
+```
 
-> To regenerate: `uv run python scripts/screenshot.py`
-> Prerequisites: `uv add --dev playwright && uv run playwright install chromium`
+Then open `http://localhost:5000` in your browser.
 
 ## Installation
 
+For regular use, install from PyPI:
+
 ```bash
 pip install difflicious
 difflicious
 ```
 
-Open `http://localhost:5000` in your browser.
-
 See [INSTALLATION.md](INSTALLATION.md) for Docker, source installation, and full configuration options.
 
+If you prefer not to install globally, add one of these to your shell profile:
+
+```bash
+# via uvx
+difflicious() { uvx difflicious "$@"; }
+
+# via Docker (uses DIFFLICIOUS_PORT if set, otherwise 5000)
+difflicious() { docker run -it --rm -v "$PWD:/workspace" -p "${DIFFLICIOUS_PORT:-5000}:${DIFFLICIOUS_PORT:-5000}" insipid/difflicious "$@"; }
+```
+
 ## Features
 
+Like your favourite forge, and then some:
+
 - Side-by-side diff view with line numbering
 - Syntax highlighting for 100+ languages (via Pygments)
 - Context expansion to see more surrounding code
@@ -73,19 +101,23 @@ See [INSTALLATION.md](INSTALLATION.md) for Docker, source installation, and full
 - Light and dark themes
 - Live auto-reload on file changes (SSE)
 - Font customization via `DIFFLICIOUS_FONT` environment variable
+- Compare against any branch — defaults to remote HEAD, configurable per session
+- Toggle staged and unstaged changes independently
+- UI state is persistent — collapsed files, hidden files, and view settings are remembered in the browser across sessions
 
 ## Configuration
 
-Set environment variables to configure behavior:
+All options can be set via environment variable or CLI flag:
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `DIFFLICIOUS_PORT` | `5000` | Port to listen on |
-| `DIFFLICIOUS_HOST` | `127.0.0.1` | Host to bind to |
-| `DIFFLICIOUS_FONT` | `jetbrains-mono` | Code font (see `--list-fonts`) |
-| `DIFFLICIOUS_DISABLE_GOOGLE_FONTS` | `false` | Use system fonts only |
-| `DIFFLICIOUS_AUTO_RELOAD` | `true` | Auto-reload on file changes |
-| `DIFFLICIOUS_DEBUG` | `false` | Verbose debug logging |
+| Environment variable | CLI flag | Default | Description |
+|----------------------|----------|---------|-------------|
+| `DIFFLICIOUS_PORT` | `--port`, `-p` | `5000` | Port to listen on |
+| `DIFFLICIOUS_HOST` | `--host`, `-h` | `127.0.0.1` | Host to bind to |
+| `DIFFLICIOUS_FONT` | — | `jetbrains-mono` | Code font (`--list-fonts` to browse) |
+| `DIFFLICIOUS_DISABLE_GOOGLE_FONTS` | — | `false` | Use system fonts only |
+| `DIFFLICIOUS_AUTO_RELOAD` | `--auto-reload` / `--no-auto-reload` | `true` | Auto-reload on file changes |
+| `DIFFLICIOUS_WATCH_DEBOUNCE` | `--watch-debounce` | `1.0` | File watcher debounce delay (seconds) |
+| `DIFFLICIOUS_DEBUG` | `--debug` | `false` | Verbose debug logging |
 
 See [INSTALLATION.md](INSTALLATION.md) for full configuration details.
 
@@ -100,13 +132,14 @@ See [INSTALLATION.md](INSTALLATION.md) for full configuration details.
 - [INSTALLATION.md](INSTALLATION.md) — installation options, configuration, environment variables
 - [DEVELOPING.md](DEVELOPING.md) — development setup, testing, code conventions
 - [CHANGELOG.md](CHANGELOG.md) — version history
-- [docs/CSS-STYLE-GUIDE.md](docs/CSS-STYLE-GUIDE.md) — CSS conventions and design tokens
 - [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — common issues
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## License
+---
 
-MIT License — see [LICENSE](LICENSE) file for details.
+[![PyPI version](https://img.shields.io/pypi/v/difflicious.svg)](https://pypi.org/project/difflicious/)
+[![Python versions](https://img.shields.io/pypi/pyversions/difflicious.svg)](https://pypi.org/project/difflicious/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

{difflicious-0.13.0 → difflicious-0.14.0}/PLAN.md

@@ -64,7 +64,7 @@ A lightweight local web application for developers to visualize git diffs with a
 - Implement advanced display options (more git data)
 - Add keyboard shortcuts and accessibility
 - Polish UI/UX with responsive design
-- **Sticky file headers** - File headers that stick to top during scroll (attempted but needs further investigation with CSS positioning in Alpine.js/Tailwind context)
+- ~~Sticky file headers~~ - implemented; headers pin while scrolling a diff
 
 ## Current Status (as of Version 0.10.0)
 - ✅ Phase 1: Project Setup & Core Backend - COMPLETE

difflicious-0.14.0/README.md

@@ -0,0 +1,107 @@
+# Difflicious
+
+<div align="center">
+  <img src="docs/site/assets/logo.png" width="160" alt="Difflicious">
+  <p><em>A local diff viewer for comparing your working directory to any branch, not just HEAD.<br>
+  No forge, no push — just run it in your repo.</em></p>
+</div>
+
+---
+
+## Screenshots
+
+<p align="center">
+  <img src="docs/screenshots/light.png" width="49%" alt="Light mode">
+  <img src="docs/screenshots/dark.png" width="49%" alt="Dark mode">
+</p>
+
+## Usage
+
+The quickest way — no install required:
+
+```bash
+uvx difflicious
+```
+
+Or with Docker:
+
+```bash
+docker run -it --rm -v "$PWD:/workspace" -p 5000:5000 insipid/difflicious
+```
+
+Then open `http://localhost:5000` in your browser.
+
+## Installation
+
+For regular use, install from PyPI:
+
+```bash
+pip install difflicious
+difflicious
+```
+
+See [INSTALLATION.md](INSTALLATION.md) for Docker, source installation, and full configuration options.
+
+If you prefer not to install globally, add one of these to your shell profile:
+
+```bash
+# via uvx
+difflicious() { uvx difflicious "$@"; }
+
+# via Docker (uses DIFFLICIOUS_PORT if set, otherwise 5000)
+difflicious() { docker run -it --rm -v "$PWD:/workspace" -p "${DIFFLICIOUS_PORT:-5000}:${DIFFLICIOUS_PORT:-5000}" insipid/difflicious "$@"; }
+```
+
+## Features
+
+Like your favourite forge, and then some:
+
+- Side-by-side diff view with line numbering
+- Syntax highlighting for 100+ languages (via Pygments)
+- Context expansion to see more surrounding code
+- Search and filter across files
+- Light and dark themes
+- Live auto-reload on file changes (SSE)
+- Font customization via `DIFFLICIOUS_FONT` environment variable
+- Compare against any branch — defaults to remote HEAD, configurable per session
+- Toggle staged and unstaged changes independently
+- UI state is persistent — collapsed files, hidden files, and view settings are remembered in the browser across sessions
+
+## Configuration
+
+All options can be set via environment variable or CLI flag:
+
+| Environment variable | CLI flag | Default | Description |
+|----------------------|----------|---------|-------------|
+| `DIFFLICIOUS_PORT` | `--port`, `-p` | `5000` | Port to listen on |
+| `DIFFLICIOUS_HOST` | `--host`, `-h` | `127.0.0.1` | Host to bind to |
+| `DIFFLICIOUS_FONT` | — | `jetbrains-mono` | Code font (`--list-fonts` to browse) |
+| `DIFFLICIOUS_DISABLE_GOOGLE_FONTS` | — | `false` | Use system fonts only |
+| `DIFFLICIOUS_AUTO_RELOAD` | `--auto-reload` / `--no-auto-reload` | `true` | Auto-reload on file changes |
+| `DIFFLICIOUS_WATCH_DEBOUNCE` | `--watch-debounce` | `1.0` | File watcher debounce delay (seconds) |
+| `DIFFLICIOUS_DEBUG` | `--debug` | `false` | Verbose debug logging |
+
+See [INSTALLATION.md](INSTALLATION.md) for full configuration details.
+
+## Technology
+
+- **Backend**: Flask, GitPython, Pygments, unidiff
+- **Frontend**: Alpine.js, Tailwind CSS
+- **Real-time**: Server-Sent Events
+
+## Documentation
+
+- [INSTALLATION.md](INSTALLATION.md) — installation options, configuration, environment variables
+- [DEVELOPING.md](DEVELOPING.md) — development setup, testing, code conventions
+- [CHANGELOG.md](CHANGELOG.md) — version history
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — common issues
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+[![PyPI version](https://img.shields.io/pypi/v/difflicious.svg)](https://pypi.org/project/difflicious/)
+[![Python versions](https://img.shields.io/pypi/pyversions/difflicious.svg)](https://pypi.org/project/difflicious/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)