docs: expand documentation and bump version to 0.5.0

- New pages: Installation, Remote Sources, Guides, Troubleshooting
- Examples page restructured as a visual gallery with new screenshots
  (diff, highlight, log-scale before/after, archive, interactive SVG)
- Images moved to docs/images/; make_examples_images.sh added
- Use cases section added to README and home page
- API snippets tested; t_scan param made optional with default 0.0
- Home directory replaced with ~ in Scanning… messages
- make_docs_images.sh --size flag corrected to --canvas
- pre-commit: mypy hook uses --all-extras; docs/images/ excluded from large-file check

Author: deeplook

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
       - id: check-yaml
       - id: check-toml
       - id: check-added-large-files
+        exclude: ^docs/images/
       - id: check-merge-conflict
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -20,7 +21,7 @@ repos:
     hooks:
       - id: mypy
         name: mypy
-        entry: uv run mypy src
+        entry: uv run --all-extras mypy src
         language: system
         pass_filenames: false
         types: [python]

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-20
+
+### Documentation
+
+- Documentation greatly expanded: new dedicated pages for Installation, Examples, Remote Sources, Guides, and Troubleshooting; richer use-case descriptions; API page updated with tested code snippets; CLI reference reordered to match `dirplot -h`.
+
 ### Changed
 
 - **`read-meta` renamed to `meta`** — `dirplot read-meta` is now `dirplot meta`. The new command

CONTRIBUTING.md

@@ -23,6 +23,18 @@ uv run pytest tests/test_cli.py
 uv run pytest tests/test_drawing.py::test_cushion_shading -v
 ```
 
+## Archive test fixtures
+
+`tests/fixtures/` contains one pre-built archive per supported format. To regenerate them:
+
+```bash
+python scripts/make_fixtures.py
+```
+
+The script creates a small sample tree and archives it in every supported format. The RAR fixture is skipped automatically if the `rar` CLI is not found.
+
+The pytest `sample_archives` session fixture in `tests/conftest.py` regenerates the same files into a temporary directory at test-session start, so running the script is not required for CI or for running the test suite locally.
+
 ## Code Style
 
 This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [mypy](https://mypy.readthedocs.io/) for type checking. Pre-commit hooks run these automatically on each commit.

README.md

@@ -5,6 +5,7 @@
 [![Python](https://img.shields.io/pypi/pyversions/dirplot.svg)](https://pypi.org/project/dirplot/)
 [![Downloads](https://img.shields.io/pypi/dm/dirplot.svg)](https://pepy.tech/project/dirplot)
 [![License](https://img.shields.io/pypi/l/dirplot.svg)](https://pypi.org/project/dirplot/)
+[![Docs](https://img.shields.io/badge/docs-deeplook.github.io%2Fdirplot-blue)](https://deeplook.github.io/dirplot)
 [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/deeplook)
 
 **dirplot** creates nested treemap images for directory trees. It can display them in the system image viewer or inline in the terminal (iTerm2 and Kitty protocols, auto-detected). It also animates git history, watches live filesystems, and scans remote sources.
@@ -15,28 +16,18 @@ dirplot map .          # treemap of current directory, opens in system viewer
 dirplot map . --inline # display inline in terminal (iTerm2 / Kitty / Ghostty)
 ```
 
-![dirplot output](https://raw.githubusercontent.com/deeplook/dirplot/main/docs/dirplot.png)
+![dirplot output](https://raw.githubusercontent.com/deeplook/dirplot/main/docs/images/dirplot.png)
 
-## Where to start
+## Use cases
 
-| I want to… | Go to |
-|---|---|
-| Scan a local directory or archive | [Quick start](#quick-start) |
-| Scan a GitHub repo, S3 bucket, SSH host, or container | [Remote access & examples](docs/EXAMPLES.md) |
-| Scan Google Drive | [Google Drive](docs/EXAMPLES.md#google-drive) |
-| Animate git history or watch live filesystems | [Git History Animation](docs/EXAMPLES.md#git-history-animation) |
-| Use dirplot from Python | [Python API](docs/API.md) |
-| Run in Docker | [Running via Docker](docs/CLI.md#running-dirplot-via-docker) |
-| Fix an error | [Troubleshooting](docs/CLI.md#troubleshooting) |
-
-## How to run dirplot
-
-| Method | Command | Notes |
-|---|---|---|
-| Installed CLI | `dirplot map .` | After `pip install` / `uv tool install` |
-| No install (uv) | `uvx dirplot map .` | Runs the latest release ephemerally |
-| Python API | `from dirplot import build_tree, create_treemap` | See [API.md](docs/API.md) |
-| Docker | `docker run --rm dirplot dirplot map … --output -` | See [Docker](docs/CLI.md#running-dirplot-via-docker) |
+- **Find what's eating your disk** — map `~/Downloads`, `~/.cache`, or `node_modules` across a monorepo to spot the culprits at a glance.
+- **Inspect before you install** — visualise a Python wheel, JAR, or RPM without unpacking it.
+- **Understand a codebase instantly** — map a legacy project or a large GitHub repo to grasp its structure before reading a single line.
+- **Compare releases** — diff two archive versions or two git tags to see exactly what grew, shrank, or disappeared.
+- **Scan remote filesystems** — map an SSH host, S3 bucket, Docker container, or Kubernetes pod without copying anything locally.
+- **AI & data exploration** — map a vector database, model weights directory, or agent memory folder (`~/.claude/projects/`).
+- **Sysadmin at a glance** — map `/var/log` to see which services generate the most logs, or scan a container image's filesystem layers.
+- **Animate history** — watch a repository or live filesystem evolve over time as a timelapse.
 
 ## Features
 
@@ -85,59 +76,25 @@ pip install dirplot
 ## Quick start
 
 ```bash
-dirplot map .                                                    # current directory
-dirplot map . --inline                                           # display in terminal (iTerm2/Kitty)
-dirplot map . --output treemap.png --no-show                     # save to file
-dirplot map . --log-scale 4 --inline                             # log scale (4× ratio), inline
-dirplot map github://pallets/flask                               # GitHub repo
-dirplot map gdrive://                                            # Google Drive root (requires gog)
-dirplot map docker://my-container:/app                           # Docker container
-dirplot map project.zip                                          # archive file
-tree src/ | dirplot map                                          # pipe tree output
-
-dirplot git . -o snapshot.png                                    # static snapshot of HEAD
-dirplot git .@v1.0 --inline                                      # inline snapshot at tag
-dirplot git . -o history.mp4 --range main                        # full git history
-dirplot git . -o history.mp4 --period 30d                        # last 30 days
-dirplot git github://owner/repo -o h.mp4 --period 7d             # GitHub, last week
-
-dirplot hg /path/to/repo -o history.png --range 0:tip            # full hg history
-dirplot hg /path/to/repo@tip -o history.png                      # static, tip only
-
-dirplot watch . --snapshot treemap.png                           # live watch, snapshot on each change
-dirplot watch . --event-log events.jsonl                         # record events for replay
-dirplot replay events.jsonl -o timelapse.mp4 --total-duration 30 # render recording as MP4
-
-dirplot demo                                                     # run examples, save to ./demo/
-
-dirplot metrics .                                                # scan metrics: counts, size, top extensions
-dirplot metrics . --sort-by size                                 # sort extensions by total bytes
-dirplot metrics . --top 5 --json                                 # top-5 entries as JSON
-dirplot map . --metrics --no-show                                # treemap + metrics in one pass
-
-dirplot diff .                                                   # uncommitted changes (git/hg)
-dirplot diff . --changed-only                                      # only show changed files
-dirplot diff .@HEAD~5 .@HEAD                                     # last 5 commits
-dirplot diff old/ new/                                           # compare two directories
-dirplot diff old/ new/ --output diff.png --no-show               # save to file
-dirplot diff github://owner/repo@v1 github://owner/repo@v2       # compare two GitHub tags
-dirplot diff archive_v1.tar.gz archive_v2.zip                    # compare two archives
+dirplot map .                                # current directory, opens in viewer
+dirplot map . --inline                       # display in terminal (iTerm2/Kitty/Ghostty)
+dirplot map . --output treemap.png --no-show # save to file
+dirplot map . --log-scale 4                  # log scale when one file dominates
+dirplot map github://pallets/flask           # GitHub repo
+dirplot map project.zip                      # archive — no unpacking needed
+
+dirplot diff .                               # uncommitted changes
+dirplot diff .@HEAD~5 .@HEAD                 # last 5 commits
+
+dirplot metrics .                            # file counts, sizes, top extensions
+dirplot git . --range main --output h.mp4    # full git history as MP4
 ```
 
-**Docker** — build once, then pipe output to the host:
-
-```bash
-docker build -t dirplot .
-docker run --rm dirplot dirplot map github://steipete/birdclaw --output - | imgcat
-```
+See the [full documentation](https://deeplook.github.io/dirplot) for the complete command reference.
 
 ## Documentation
 
-- [CLI reference](docs/CLI.md) — all commands, flags, and usage examples
-- [Remote access & examples](docs/EXAMPLES.md) — SSH, S3, GitHub, Docker, Kubernetes, git history animation
-- [Archive formats](docs/ARCHIVES.md) — supported formats and dependencies
-- [Python API](docs/API.md) — programmatic usage
-- [Troubleshooting](docs/CLI.md#troubleshooting) — common issues and fixes
+Full documentation is available at **[deeplook.github.io/dirplot](https://deeplook.github.io/dirplot)**.
 
 ## Development
 

docs/API.md

@@ -1,5 +1,7 @@
 # Python API
 
+← [Home](index.md)
+
 > **Note:** The programmatic Python API is still evolving and may change between releases without notice. Pin a specific version if you depend on it. The CLI interface is stable.
 
 The public API centres on `build_tree`, `create_treemap`, and `create_treemap_svg`:
@@ -59,17 +61,17 @@ from dirplot.scanner import tree_metrics, tree_metrics_dict
 root = build_tree(Path("/path/to/project"))
 
 # Human-readable string (same as CLI output)
-print(tree_metrics(root, t_scan=0.0))
+print(tree_metrics(root))
 
 # Sort extensions by total bytes instead of file count
-print(tree_metrics(root, t_scan=0.0, sort_by="size"))
+print(tree_metrics(root, sort_by="size"))
 
 # Limit to top 5 entries per list
-print(tree_metrics(root, t_scan=0.0, top_n=5))
+print(tree_metrics(root, top_n=5))
 
 # Structured dict — suitable for JSON serialisation or downstream processing
 import json
-data = tree_metrics_dict(root, t_scan=0.0)
+data = tree_metrics_dict(root)
 print(json.dumps(data, indent=2))
 ```
 
@@ -100,7 +102,7 @@ print(json.dumps(data, indent=2))
 
 ## Remote backends
 
-Each remote backend exposes a `build_tree_*` function that returns the same `Node` type accepted by `create_treemap`. See [EXAMPLES.md](EXAMPLES.md) for full per-backend documentation and authentication details.
+Each remote backend exposes a `build_tree_*` function that returns the same `Node` type accepted by `create_treemap`. See [EXAMPLES.md](examples.md) for full per-backend documentation and authentication details.
 
 ```python
 # GitHub
@@ -130,4 +132,9 @@ root = build_tree_docker("my-container", "/app", depth=5)
 # Kubernetes
 from dirplot.k8s import build_tree_pod
 root = build_tree_pod("my-pod", "/app", namespace="staging", container="main", depth=5)
+
+# Google Drive (requires gog CLI: brew install gogcli && gog auth)
+from dirplot.gdrive import build_tree_gdrive
+root = build_tree_gdrive(depth=3)                                          # Drive root
+root = build_tree_gdrive("1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms", depth=5)  # specific folder
 ```

docs/ARCHIVES.md

@@ -1,4 +1,6 @@
-# Archive file support
+# Archive Formats
+
+← [Home](index.md)
 
 dirplot can read local archive files as treemap inputs without unpacking them.
 The archive is treated as a virtual directory: its members form the node tree
@@ -123,21 +125,6 @@ xattr -d com.apple.quarantine /opt/homebrew/bin/rar
 
 After that the binary runs normally.
 
-## Test fixtures
-
-`tests/fixtures/` contains one pre-built archive per format. They are
-generated by:
-
-```bash
-python scripts/make_fixtures.py
-```
-
-The script creates a small sample tree and archives it in every supported format. The RAR fixture is skipped automatically if the `rar` CLI is not found.
-
-The pytest `sample_archives` session fixture in `tests/conftest.py` regenerates
-the same files into a temporary directory at test-session start, so running the
-script is not required for CI or for running the test suite locally.
-
 ## Intentionally unsupported formats
 
 **`.deb` (Debian/Ubuntu packages)** — a `.deb` file is an `ar` archive whose