diff --git a/.github/workflows/deploy-mip-index-to-pages.yml b/.github/workflows/deploy-mip-index-to-pages.yml
index 6d0b4e839..b8a5dc54d 100644
--- a/.github/workflows/deploy-mip-index-to-pages.yml
+++ b/.github/workflows/deploy-mip-index-to-pages.yml
@@ -141,7 +141,7 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v5
 
-  # The committed package list (packages.json + the README block) describes
+  # The committed package list (packages.json + the block in docs/reference/packages.md) describes
   # the index that just went live, and the site page is regenerated from it
   # and redeployed; see refresh-package-list.yml. contents: write is granted
   # to this job only, for that commit; pages: write for the redeploy.
diff --git a/.github/workflows/process-mip-publication-request.yml b/.github/workflows/process-mip-publication-request.yml
index 1cc3b26b1..f54161824 100644
--- a/.github/workflows/process-mip-publication-request.yml
+++ b/.github/workflows/process-mip-publication-request.yml
@@ -68,7 +68,7 @@ jobs:
         id: deployment
         uses: actions/deploy-pages@v5
 
-  # The committed package list (packages.json + the README block) describes
+  # The committed package list (packages.json + the block in docs/reference/packages.md) describes
   # the index that just went live; see refresh-package-list.yml. It sits on
   # top of the lockfile commit the reusable workflow pushed.
   refresh-package-list:
diff --git a/.github/workflows/refresh-package-list.yml b/.github/workflows/refresh-package-list.yml
index 641338220..44aff8b9f 100644
--- a/.github/workflows/refresh-package-list.yml
+++ b/.github/workflows/refresh-package-list.yml
@@ -104,7 +104,7 @@ jobs:
         run: |
           git config user.name 'github-actions[bot]'
           git config user.email 'github-actions[bot]@users.noreply.github.com'
-          git add packages.json README.md .site/index.html
+          git add packages.json docs/reference/packages.md .site/index.html
           if git diff --cached --quiet -- .site/index.html; then
             echo "page-changed=false" >> "$GITHUB_OUTPUT"
           else
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cd6451b38..8b6ce0d84 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,12 +1,12 @@
 # Contributing
 
-This repository is the **generated MIP package index** for PyDevices — see
-the note at the top of the README. There is nothing to contribute here
-directly:
+This repository is the **generated MIP package index** for PyDevices
+([how it's built](docs/how-it-works/index.md)). There is nothing to contribute
+here directly:
 
 - **Package bugs** belong to the package's own repository
-  (github.com/PyDevices/<repo>/issues — the README's package list links
-  each one).
+  (github.com/PyDevices/<repo>/issues — the
+  [package list](docs/reference/packages.md) links each one).
 - **Index problems** (a wrong or missing version, a failed publication):
   open an issue on this repository.
 - **Publishing changes** happen in the component repos and
diff --git a/README.md b/README.md
index 8c7554dca..df6028b67 100644
--- a/README.md
+++ b/README.md
@@ -1,260 +1,43 @@
-# PyDevices MIP package index
+![The index's web page, with a live MicroPython demo running in the browser](docs/images/index-page.png)
 
-> **This index is generated — do not edit package trees by hand.**
-> `pydevices-lock.json` is the source of truth: component repositories
-> publish through a serialized dispatch queue
-> (`process-mip-publication-request.yml`), each publication pins an exact
-> source tag in the lockfile, and every deploy re-syncs **all** locked
-> sources before publishing. Anything under the package directories is
-> build output, and `packages.json` plus the "Packages in this index"
-> block below are regenerated after every deploy; the only meaningful
-> edits here are to the lockfile via the queue, the workflows,
-> `scripts/`, and this documentation.
+# PyDevices package index
 
+A `mip` package index for MicroPython: every PyDevices library, plus all of micropython-lib, as precompiled `.mpy` files or plain `.py` source.
 
-This micropython-lib fork builds an installable package index containing both
-precompiled `.mpy` bytecode and raw `.py` source at:
+## Install
 
-```text
-https://PyDevices.github.io/mip
-```
-
-This repository documents the package manager itself. Product repositories
-document which product or board package to choose.
-
-## Install from a network-enabled MicroPython device
+On a board with a network connection:
 
 ```python
 import mip
-
-mip.install("package-name", index="https://PyDevices.github.io/mip")
-```
-
-`mip` installs into the interpreter's default library destination unless `target`
-is supplied. Use `mpy=False` to request portable `.py` source instead of
-MicroPython bytecode.
-
-```python
-mip.install(
-    "package-name",
-    index="https://PyDevices.github.io/mip",
-    target="lib",
-    mpy=False,
-)
+mip.install("palettes", index="https://PyDevices.github.io/mip")
 ```
 
-## Install with the MicroPython command line
-
-Hosted MicroPython ports can run the package manager as a module:
+From your computer, onto a board on USB (the board needs no network):
 
 ```bash
-micropython -m mip install \
-  --index https://PyDevices.github.io/mip \
-  package-name
+mpremote mip install --index https://PyDevices.github.io/mip palettes
 ```
 
-Use `--target lib` for an explicit workspace destination and `--no-mpy` for a
-source-only tree.
+## Try it
 
-## Install onto a connected device with mpremote
+With the unix port of MicroPython, install a package into `lib/` and use it:
 
 ```bash
-mpremote connect /dev/ttyUSB0 mip install \
-  --index https://PyDevices.github.io/mip \
-  package-name
-```
-
-`mpremote mip` resolves and transfers the package from the host, so the board
-does not need its own network connection.
-
-## Install a raw GitHub package
-
-`mip` also accepts GitHub files and directories. Pass the index when a raw
-package has named dependencies that should resolve here:
-
-```python
-mip.install(
-    "github:OWNER/REPOSITORY/path/to/package",
-    index="https://PyDevices.github.io/mip",
-)
+micropython -m mip install --index https://PyDevices.github.io/mip --target lib palettes
 ```
 
-The live index intentionally exposes only each package's current `latest`
-manifest. Releases replace the current entry rather than accumulating a public
-history of versioned manifests.
-
-## Packages in this index
-
-<!-- PACKAGES: START -->
-These are the PyDevices packages this index publishes, each built from the
-source tag pinned in `pydevices-lock.json`; the micropython-lib packages the
-index also carries are upstream's.
-
-| Package | Version | Description | Source |
-| --- | --- | --- | --- |
-| `pydevices` | 0.7.7 | Portable display, audio, event, and timing foundations for PyDevices | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `pydevices-desktop` | 0.7.7 | Complete PyDevices desktop stack and board configuration | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `bledev` | 0.7.7 | Portable async Bluetooth Low Energy for PyDevices, over aioble on boards | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `midiports` | 0.7.7 | MIDI ports for adafruit_midi: USB device, UART, and a computer's own MIDI ports. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-core` | 0.7.7 | usb.core and usb.util: talk to USB devices from a host board, in PyUSB's shape. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-device-audio` | 0.7.7 | USB audio (UAC2) sound card on machine.USBDevice's streaming endpoints. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-device-msc` | 0.7.7 | USB mass storage device (Bulk-Only Transport, SCSI) over a MicroPython block device. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-device-video` | 0.7.7 | USB video (UVC) webcam on machine.USBDevice's streaming endpoints. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-hid` | 0.7.7 | CircuitPython's usb_hid on MicroPython, over usb-device-hid, for adafruit_hid. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-host-audio` | 0.7.7 | Play to a USB speaker or record from a USB microphone on this board's host port, over usb.core, alone or as audiodev outputs and inputs. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-host-cdc` | 0.7.7 | Talk to a USB serial device (CDC-ACM) on this board's host port, over usb.core. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-host-hid` | 0.7.7 | Keys, mouse buttons and movement from a keyboard or mouse plugged into this board's USB host port, named the way adafruit_hid names them. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-host-msc` | 0.7.7 | Mount a USB flash drive plugged into this board's host port, over usb.core. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-host-net` | 0.7.7 | Internet over USB: a phone's USB tethering on this board's host port, as a network interface. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `usb-host-video` | 0.7.7 | Stream a webcam plugged into this board's USB host port, over usb.core. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `hmilink` | 0.7.7 | Any screen as a device's front panel: one document, ops, telemetry and events over any transport. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
-| `palettes` | 0.0.14 | Color palette toolkit for PyDevices (wheel, cube, material_design) | [PyDevices/palettes @ v0.0.14](https://github.com/PyDevices/palettes/releases/tag/v0.0.14) |
-| `pdwidgets` | 0.0.24 | Cross-platform widget toolkit for PyDevices | [PyDevices/pdwidgets @ v0.0.24](https://github.com/PyDevices/pdwidgets/releases/tag/v0.0.24) |
-| `pygraphics` | 0.1.1 | Pure-Python pygraphics for MicroPython/CircuitPython/CPython (FrameBuffer, Draw, fonts); import as pygraphics | [PyDevices/pygraphics @ v0.1.1](https://github.com/PyDevices/pygraphics/releases/tag/v0.1.1) |
-| `audioinstruments` | 0.4.1 | 55 synthio instruments for PyDevices (drum machines and synthesizers); import as audioinstruments | [PyDevices/audiocomponents @ v0.4.1](https://github.com/PyDevices/audiocomponents/releases/tag/v0.4.1) |
-| `audioeffects` | 0.4.1 | Effect classes for PyDevices audio (delay, drive, dynamics, eq, modulation, pitch, reverb); import as audioeffects | [PyDevices/audiocomponents @ v0.4.1](https://github.com/PyDevices/audiocomponents/releases/tag/v0.4.1) |
-
 ```python
-import mip
+from palettes import get_palette
 
-mip.install("pydevices", index="https://PyDevices.github.io/mip")
-mip.install("pydevices-desktop", index="https://PyDevices.github.io/mip")
-mip.install("bledev", index="https://PyDevices.github.io/mip")
-mip.install("midiports", index="https://PyDevices.github.io/mip")
-mip.install("usb-core", index="https://PyDevices.github.io/mip")
-mip.install("usb-device-audio", index="https://PyDevices.github.io/mip")
-mip.install("usb-device-msc", index="https://PyDevices.github.io/mip")
-mip.install("usb-device-video", index="https://PyDevices.github.io/mip")
-mip.install("usb-hid", index="https://PyDevices.github.io/mip")
-mip.install("usb-host-audio", index="https://PyDevices.github.io/mip")
-mip.install("usb-host-cdc", index="https://PyDevices.github.io/mip")
-mip.install("usb-host-hid", index="https://PyDevices.github.io/mip")
-mip.install("usb-host-msc", index="https://PyDevices.github.io/mip")
-mip.install("usb-host-net", index="https://PyDevices.github.io/mip")
-mip.install("usb-host-video", index="https://PyDevices.github.io/mip")
-mip.install("hmilink", index="https://PyDevices.github.io/mip")
-mip.install("palettes", index="https://PyDevices.github.io/mip")
-mip.install("pdwidgets", index="https://PyDevices.github.io/mip")
-mip.install("pygraphics", index="https://PyDevices.github.io/mip")
-mip.install("audioinstruments", index="https://PyDevices.github.io/mip")
-mip.install("audioeffects", index="https://PyDevices.github.io/mip")
+wheel = get_palette(name="wheel", length=360, color_depth=16)
+print("red, green, blue as RGB565: 0x%04X 0x%04X 0x%04X" % (wheel[0], wheel[120], wheel[240]))
 ```
 
-<sub>Generated by `scripts/update_package_list.py` from the index itself;
-`packages.json` carries the same data. Both are rewritten after every
-deploy -- do not edit by hand.</sub>
-<!-- PACKAGES: END -->
-
-## Usage (Standard Upstream Packages)
-
-To install standard, upstream `micropython-lib` standard library or ecosystem packages, there are four main options. For more information see the [Package management documentation](https://docs.micropython.org/en/latest/reference/packages.html) documentation.
-
-
-### On a network-enabled device
-
-As of MicroPython v1.20 (and nightly builds since October 2022), boards
-with WiFi and Ethernet support include the `mip` package manager.
-
-```py
->>> import mip
->>> mip.install("package-name")
-```
-
-### Using `mpremote` from your PC
-
-`mpremote` is the officially-supported tool for interacting with a MicroPython
-device and, since v0.4.0, support for installing micropython-lib packages is
-provided by using the `mip` command.
-
-```bash
-$ mpremote connect /dev/ttyUSB0 mip install package-name
-```
-
-See the [mpremote documentation](https://docs.micropython.org/en/latest/reference/mpremote.html).
-
-### Freeze into your firmware
-
-If you are building your own firmware, all packages in this repository include
-a `manifest.py` that can be included into your board manifest via the
-`require()` command. See [Manifest files](https://docs.micropython.org/en/latest/reference/manifest.html#require) for
-more information.
-
-### Copy the files manually
-
-Many micropython-lib packages are just single-file modules, and you can
-quickly get started by copying the relevant Python file to your device. For
-example, to add the `base64` library, you can directly copy
-`python-stdlib/base64/base64.py` to the `lib` directory on your device.
-
-This can be done using `mpremote`, for example:
-
-```bash
-$ mpremote connect /dev/ttyUSB0 cp python-stdlib/base64/base64.py :/lib
+```text
+red, green, blue as RGB565: 0xF800 0x07E0 0x001F
 ```
 
-For packages that are implemented as a package directory, you'll need to copy
-the directory instead. For example, to add `collections.defaultdict`, copy
-`collections/collections/__init__.py` and
-`collections-defaultdict/collections/defaultdict.py` to a directory named
-`lib/collections` on your device.
-
-Note that unlike the other three approaches based on `mip` or `manifest.py`,
-you will need to manually resolve dependencies. You can inspect the relevant
-`manifest.py` file to view the list of dependencies for a given package.
-
-## Contributing
-
-We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
-as our forum, and [Discord](https://micropython.org/discord) for chat. These
-are great places to ask questions and advice from the community or to discuss your
-MicroPython-based projects.
-
-The [MicroPython Wiki](https://github.com/micropython/micropython/wiki) is
-also used for micropython-lib.
-
-For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython-lib/issues/new).
-
-We welcome pull requests to add new packages, fix bugs, or add features.
-Please be sure to follow the
-[Contributor's Guidelines & Code Conventions](CONTRIBUTING.md). Note that
-MicroPython is licensed under the [MIT license](LICENSE) and all contributions
-should follow this license.
-
-### Future plans (and new contributor ideas)
-
-* Develop a set of example programs using these packages.
-* Develop more MicroPython packages for common tasks.
-* Expand unit testing coverage.
-* Add support for referencing remote/third-party repositories.
-
-What's planned next is in [ROADMAP.md](ROADMAP.md).
-
-## Notes on terminology
-
-The terms *library*, *package*, and *module* are overloaded and lead to some
-confusion. The interpretation used in by the MicroPython project is that:
-
-A *library* is a collection of installable packages, e.g. [The Python Standard
-  Library](https://docs.python.org/3/library/), or micropython-lib.
-
-A *package* can refer to two things. The first meaning, "library package", is
-something that can be installed from a library, e.g. via `mip` (or `pip` in
-CPython/PyPI). Packages provide *modules* that can be imported. The ambiguity
-here is that the module provided by the package does not necessarily have to
-have the same name, e.g. the `pyjwt` package provides the `jwt` module. In
-CPython, the `pyserial` package providing the `serial` module is another
-common example.
-
-A *module* is something that can be imported. For example, "the *os* module".
-
-A module can be implemented either as a single file, typically also called
-a *module* or "single-file module", or as a *package* (the second meaning),
-which in this context means a directory containing multiple `.py` files
-(usually at least an `__init__.py`).
+[Docs](https://github.com/PyDevices/mip/blob/PyDevices/docs/index.md) · [Examples](https://pydevices.github.io/pydevices-examples/gallery/) · [Roadmap](ROADMAP.md)
 
-In micropython-lib, we also have the concept of an *extension package* which
-is a library package that extends the functionality of another package, by
-adding additional files to the same package directory. These packages have
-hyphenated names. For example, the `collections-defaultdict` package extends
-the `collections` package to add the `defaultdict` class to the `collections`
-module.
+Made by [PyDevices](https://pydevices.com).
diff --git a/docs/changelog.md b/docs/changelog.md
new file mode 100644
index 000000000..539872eb4
--- /dev/null
+++ b/docs/changelog.md
@@ -0,0 +1,3 @@
+# Changelog
+
+The index itself has no releases. Each package's changes are in its own repository's changelog: the [package list](reference/packages.md) links the release every package was built from. Changes to how the index is built are in the [commit history](https://github.com/PyDevices/mip/commits/PyDevices).
diff --git a/docs/get-started/install.md b/docs/get-started/install.md
new file mode 100644
index 000000000..b2a318ab6
--- /dev/null
+++ b/docs/get-started/install.md
@@ -0,0 +1,59 @@
+# Install a package
+
+Every install names the index with `https://PyDevices.github.io/mip`. The [package list](../reference/packages.md) has every name you can install.
+
+## On a board with a network connection
+
+MicroPython 1.20 and later include `mip` on boards with Wi-Fi or Ethernet. Connect to your network, then:
+
+```python
+import mip
+
+mip.install("package-name", index="https://PyDevices.github.io/mip")
+```
+
+The package goes into the interpreter's default library folder unless you pass `target`. You get `.mpy` bytecode by default; pass `mpy=False` for portable `.py` source:
+
+```python
+mip.install(
+    "package-name",
+    index="https://PyDevices.github.io/mip",
+    target="lib",
+    mpy=False,
+)
+```
+
+## From your computer, onto a board on USB
+
+`mpremote` fetches the package on your computer and copies it to the board, so the board doesn't need a network:
+
+```bash
+mpremote connect /dev/ttyUSB0 mip install \
+  --index https://PyDevices.github.io/mip \
+  package-name
+```
+
+See the [mpremote documentation](https://docs.micropython.org/en/latest/reference/mpremote.html) for how to name your board's port.
+
+## With the unix or Windows port
+
+A MicroPython build for your computer can run the package manager as a module:
+
+```bash
+micropython -m mip install \
+  --index https://PyDevices.github.io/mip \
+  package-name
+```
+
+Add `--target lib` to choose the folder and `--no-mpy` for source only.
+
+## From GitHub
+
+`mip` also takes a GitHub file or folder. Pass the index too, so the package's dependencies resolve from here:
+
+```python
+mip.install(
+    "github:OWNER/REPOSITORY/path/to/package",
+    index="https://PyDevices.github.io/mip",
+)
+```
diff --git a/docs/guides/install-micropython-lib-packages.md b/docs/guides/install-micropython-lib-packages.md
new file mode 100644
index 000000000..e89714c63
--- /dev/null
+++ b/docs/guides/install-micropython-lib-packages.md
@@ -0,0 +1,44 @@
+# Install micropython-lib packages
+
+This index carries micropython-lib's packages too, so `mip.install("base64", index="https://PyDevices.github.io/mip")` works. You can also get them from upstream's own index, by freezing them into firmware, or by copying files. Upstream's [package management documentation](https://docs.micropython.org/en/latest/reference/packages.html) has more.
+
+## From upstream's index
+
+Leave out `index` and `mip` uses micropython-lib's own:
+
+```python
+import mip
+mip.install("package-name")
+```
+
+With `mpremote`, from your computer:
+
+```bash
+mpremote connect /dev/ttyUSB0 mip install package-name
+```
+
+## Freeze into your firmware
+
+If you build your own firmware, every package here has a `manifest.py` you can pull into your board's manifest with `require()`. See [Manifest files](https://docs.micropython.org/en/latest/reference/manifest.html#require).
+
+## Copy the files by hand
+
+Many packages are a single file. From a clone of this repository, to add `base64`, copy `python-stdlib/base64/base64.py` to `lib` on your board:
+
+```bash
+mpremote connect /dev/ttyUSB0 cp python-stdlib/base64/base64.py :/lib
+```
+
+A package that is a folder needs the folder. For `collections.defaultdict`, copy `collections/collections/__init__.py` and `collections-defaultdict/collections/defaultdict.py` into `lib/collections` on the board.
+
+Copying by hand doesn't resolve dependencies. A package's `manifest.py` lists what else it needs.
+
+## Package, module, library
+
+micropython-lib uses these words carefully.
+
+A *library* is a collection of installable packages, like micropython-lib or the Python standard library.
+
+A *package* is something you install, with `mip` (or `pip` in CPython). It provides *modules* you import, and the names can differ: the `pyjwt` package provides the `jwt` module. "Package" also means a folder of `.py` files with an `__init__.py`, which is one way to write a module.
+
+An *extension package* adds files to another package's folder. These have hyphenated names: `collections-defaultdict` adds `defaultdict` to the `collections` module.
diff --git a/docs/how-it-works/index.md b/docs/how-it-works/index.md
new file mode 100644
index 000000000..8bdf576d7
--- /dev/null
+++ b/docs/how-it-works/index.md
@@ -0,0 +1,15 @@
+# How the index is built
+
+The index is a fork of [micropython-lib](https://github.com/micropython/micropython-lib) whose build publishes upstream's packages and PyDevices' packages together, to GitHub Pages at `https://PyDevices.github.io/mip`. Every package is built twice: as `.mpy` bytecode, and as `.py` source for `mpy=False`.
+
+## Nobody edits the package trees
+
+[`pydevices-lock.json`](../../pydevices-lock.json) is the source of truth. It pins each PyDevices package to an exact release tag in the repository that owns it. Everything under the package folders is build output.
+
+When a repository releases, it sends a publication request. Requests run one at a time through [`process-mip-publication-request.yml`](../../.github/workflows/process-mip-publication-request.yml), and each one updates the package's pin in the lockfile. Every deploy then syncs all the pinned sources again before it publishes, so one release can't leave another package stale. The lockfile also says which repository may publish each package, and a request from any other repository is refused.
+
+After each deploy, [`scripts/update_package_list.py`](../../scripts/update_package_list.py) reads the live index back and rewrites `packages.json` and the [package list](../reference/packages.md), so the list always matches what's actually being served.
+
+## Only the latest version
+
+The index lists each package's current version and nothing older. A release replaces the entry instead of adding another.
diff --git a/docs/images/index-page.png b/docs/images/index-page.png
new file mode 100644
index 000000000..e1ec2567c
Binary files /dev/null and b/docs/images/index-page.png differ
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 000000000..e12c037b5
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,25 @@
+# PyDevices package index
+
+A `mip` package index at `https://PyDevices.github.io/mip`. It carries every PyDevices library and all of micropython-lib, each as precompiled `.mpy` files or plain `.py` source.
+
+## Get started
+
+- [Install a package](get-started/install.md): from a board, from your computer, or from the unix port.
+
+## Guides
+
+- [Install micropython-lib packages](guides/install-micropython-lib-packages.md): from upstream's index, by freezing them into firmware, or by copying files.
+
+## Reference
+
+- [Packages in this index](reference/packages.md): every PyDevices package, its version and where it comes from.
+
+## How it works
+
+- [How the index is built](how-it-works/index.md): the lockfile, the publication queue, and why only the latest version is listed.
+
+## Changelog
+
+- [Changelog](changelog.md)
+
+Also: [Roadmap](../ROADMAP.md), [Contributing](../CONTRIBUTING.md).
diff --git a/docs/reference/packages.md b/docs/reference/packages.md
new file mode 100644
index 000000000..ecb2e6f4a
--- /dev/null
+++ b/docs/reference/packages.md
@@ -0,0 +1,63 @@
+# Packages in this index
+
+The list below is rewritten after every deploy, and the same data is in [`packages.json`](../../packages.json). The index also carries all of micropython-lib; [installing those](../guides/install-micropython-lib-packages.md) works the same way.
+
+<!-- PACKAGES: START -->
+These are the PyDevices packages this index publishes, each built from the
+source tag pinned in `pydevices-lock.json`; the micropython-lib packages the
+index also carries are upstream's.
+
+| Package | Version | Description | Source |
+| --- | --- | --- | --- |
+| `pydevices` | 0.7.7 | Portable display, audio, event, and timing foundations for PyDevices | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `pydevices-desktop` | 0.7.7 | Complete PyDevices desktop stack and board configuration | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `bledev` | 0.7.7 | Portable async Bluetooth Low Energy for PyDevices, over aioble on boards | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `midiports` | 0.7.7 | MIDI ports for adafruit_midi: USB device, UART, and a computer's own MIDI ports. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-core` | 0.7.7 | usb.core and usb.util: talk to USB devices from a host board, in PyUSB's shape. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-device-audio` | 0.7.7 | USB audio (UAC2) sound card on machine.USBDevice's streaming endpoints. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-device-msc` | 0.7.7 | USB mass storage device (Bulk-Only Transport, SCSI) over a MicroPython block device. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-device-video` | 0.7.7 | USB video (UVC) webcam on machine.USBDevice's streaming endpoints. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-hid` | 0.7.7 | CircuitPython's usb_hid on MicroPython, over usb-device-hid, for adafruit_hid. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-host-audio` | 0.7.7 | Play to a USB speaker or record from a USB microphone on this board's host port, over usb.core, alone or as audiodev outputs and inputs. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-host-cdc` | 0.7.7 | Talk to a USB serial device (CDC-ACM) on this board's host port, over usb.core. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-host-hid` | 0.7.7 | Keys, mouse buttons and movement from a keyboard or mouse plugged into this board's USB host port, named the way adafruit_hid names them. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-host-msc` | 0.7.7 | Mount a USB flash drive plugged into this board's host port, over usb.core. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-host-net` | 0.7.7 | Internet over USB: a phone's USB tethering on this board's host port, as a network interface. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `usb-host-video` | 0.7.7 | Stream a webcam plugged into this board's USB host port, over usb.core. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `hmilink` | 0.7.7 | Any screen as a device's front panel: one document, ops, telemetry and events over any transport. | [PyDevices/pydevices @ v0.7.7](https://github.com/PyDevices/pydevices/releases/tag/v0.7.7) |
+| `palettes` | 0.0.14 | Color palette toolkit for PyDevices (wheel, cube, material_design) | [PyDevices/palettes @ v0.0.14](https://github.com/PyDevices/palettes/releases/tag/v0.0.14) |
+| `pdwidgets` | 0.0.24 | Cross-platform widget toolkit for PyDevices | [PyDevices/pdwidgets @ v0.0.24](https://github.com/PyDevices/pdwidgets/releases/tag/v0.0.24) |
+| `pygraphics` | 0.1.1 | Pure-Python pygraphics for MicroPython/CircuitPython/CPython (FrameBuffer, Draw, fonts); import as pygraphics | [PyDevices/pygraphics @ v0.1.1](https://github.com/PyDevices/pygraphics/releases/tag/v0.1.1) |
+| `audioinstruments` | 0.4.1 | 55 synthio instruments for PyDevices (drum machines and synthesizers); import as audioinstruments | [PyDevices/audiocomponents @ v0.4.1](https://github.com/PyDevices/audiocomponents/releases/tag/v0.4.1) |
+| `audioeffects` | 0.4.1 | Effect classes for PyDevices audio (delay, drive, dynamics, eq, modulation, pitch, reverb); import as audioeffects | [PyDevices/audiocomponents @ v0.4.1](https://github.com/PyDevices/audiocomponents/releases/tag/v0.4.1) |
+
+```python
+import mip
+
+mip.install("pydevices", index="https://PyDevices.github.io/mip")
+mip.install("pydevices-desktop", index="https://PyDevices.github.io/mip")
+mip.install("bledev", index="https://PyDevices.github.io/mip")
+mip.install("midiports", index="https://PyDevices.github.io/mip")
+mip.install("usb-core", index="https://PyDevices.github.io/mip")
+mip.install("usb-device-audio", index="https://PyDevices.github.io/mip")
+mip.install("usb-device-msc", index="https://PyDevices.github.io/mip")
+mip.install("usb-device-video", index="https://PyDevices.github.io/mip")
+mip.install("usb-hid", index="https://PyDevices.github.io/mip")
+mip.install("usb-host-audio", index="https://PyDevices.github.io/mip")
+mip.install("usb-host-cdc", index="https://PyDevices.github.io/mip")
+mip.install("usb-host-hid", index="https://PyDevices.github.io/mip")
+mip.install("usb-host-msc", index="https://PyDevices.github.io/mip")
+mip.install("usb-host-net", index="https://PyDevices.github.io/mip")
+mip.install("usb-host-video", index="https://PyDevices.github.io/mip")
+mip.install("hmilink", index="https://PyDevices.github.io/mip")
+mip.install("palettes", index="https://PyDevices.github.io/mip")
+mip.install("pdwidgets", index="https://PyDevices.github.io/mip")
+mip.install("pygraphics", index="https://PyDevices.github.io/mip")
+mip.install("audioinstruments", index="https://PyDevices.github.io/mip")
+mip.install("audioeffects", index="https://PyDevices.github.io/mip")
+```
+
+<sub>Generated by `scripts/update_package_list.py` from the index itself;
+`packages.json` carries the same data. Both are rewritten after every
+deploy -- do not edit by hand.</sub>
+<!-- PACKAGES: END -->
diff --git a/scripts/update_package_list.py b/scripts/update_package_list.py
index b76667e81..0a1157719 100755
--- a/scripts/update_package_list.py
+++ b/scripts/update_package_list.py
@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
 """Regenerate the list of PyDevices packages this index publishes.
 
-Writes packages.json and rewrites the PACKAGES block in README.md. The set of
-packages is derived from pydevices-lock.json (every profile the publication
-sync builds), and the data for each -- version, description, license -- comes
-from the index's own index.json, never from PyPI or TestPyPI.
+Writes packages.json and rewrites the PACKAGES block in
+docs/reference/packages.md. The set of packages is derived from
+pydevices-lock.json (every profile the publication sync builds), and the
+data for each -- version, description, license -- comes from the index's own
+index.json, never from PyPI or TestPyPI.
 
 Stdlib only. The refresh-package-list workflow runs it after every deploy --
 a publication or a docs push -- against the index that was just deployed; by
@@ -553,7 +554,9 @@ def main() -> int:
         "or an http(s) URL, fetched (default: the live index). No fallback between the two.",
     )
     parser.add_argument("--lockfile", type=Path, default=REPO_ROOT / "pydevices-lock.json")
-    parser.add_argument("--readme", type=Path, default=REPO_ROOT / "README.md")
+    parser.add_argument(
+        "--readme", type=Path, default=REPO_ROOT / "docs" / "reference" / "packages.md"
+    )
     parser.add_argument("--output", type=Path, default=REPO_ROOT / "packages.json")
     parser.add_argument(
         "--self-check",