Install docs: omip is the way in

README.md

@@ -9,11 +9,17 @@ The `mip` index for OmniPython's libraries, board configs and drivers, at **http
 On a board with Wi-Fi, in the REPL:
 
 ```python
-import mip
-mip.install("pydevices", index="https://pydevices.github.io/lib")
+import omip
+omip.install("pydevices")
 ```
 
-From a computer, onto a board on USB:
+`omip` gets the board online if it isn't, and brings what a package needs from micropython-lib. If `import omip` fails, your firmware doesn't have it yet, so copy it on from a computer:
+
+```bash
+mpremote mip install github:PyDevices/pydevices/lib/omip.py
+```
+
+From a computer, onto a board on USB, with no Wi-Fi at all:
 
 ```bash
 mpremote mip install --index https://pydevices.github.io/lib pydevices

docs/get-started/install.md

@@ -1,17 +1,45 @@
 # Install a package
 
-Every install names the index: `https://pydevices.github.io/lib`. [What's in the index](../reference/packages.md) lists the packages.
+[What's in the index](../reference/packages.md) lists the packages.
 
 ## On a board with Wi-Fi
 
-Connect to your network, then in the REPL:
+In the REPL:
+
+```python
+import omip
+omip.install("pydevices")
+```
+
+If the board is offline, `omip` joins the network in `secrets.py` or `settings.toml`, and with neither it asks you, saving what you type only if you say so. It looks for the package here and then on micropython-lib, and brings what the package needs from both. It takes the arguments of `mip.install`, so `omip.install("pydevices", mpy=False)` gets `.py` source instead of `.mpy` files for your board's bytecode version.
+
+If it can't finish, `omip` raises `OSError`. A program with no one at the REPL passes `prompt=False`, so it never waits for an answer.
+
+### Getting omip
+
+Firmware that freezes pydevices has it, once its pydevices release does. On any other MicroPython firmware, copy the one file on from a computer:
+
+```bash
+mpremote mip install github:PyDevices/pydevices/lib/omip.py
+```
+
+Or, on a board that's already online:
 
 ```python
 import mip
-mip.install("pydevices", index="https://pydevices.github.io/lib")
+mip.install("github:PyDevices/pydevices/lib/omip.py")
 ```
 
-You get `.mpy` files for the MicroPython bytecode version your board runs, or `.py` source with `mpy=False`.
+On CircuitPython, copy [`omip.py`](https://github.com/PyDevices/pydevices/blob/main/lib/omip.py) to `lib/` on the CIRCUITPY drive. To let `import mip` work there too, copy [`mip.py`](https://github.com/PyDevices/pydevices/blob/main/board_configs/cp/mip.py) beside it; don't put that file on MicroPython, whose own `mip` it would hide. Installing on the board needs a writable drive, which `omip` explains if it isn't, and `aioble` and the other micropython-lib packages are left out, because CircuitPython's libraries come from `circup`.
+
+## With plain mip
+
+Every `mip` install names the index, and you connect to your network first:
+
+```python
+import mip
+mip.install("pydevices", index="https://pydevices.github.io/lib")
+```
 
 ## From a computer, onto a board on USB
 
@@ -37,7 +65,7 @@ mip.install("esp32-s3-touch-lcd-7", index="https://pydevices.github.io/lib")
 
 ## Packages from micropython-lib
 
-Packages that come from [micropython-lib](https://github.com/micropython/micropython-lib) (`aioble`, `sdcard`, `bmi270`, `usb-device-*`) aren't copied here. `mip` takes every file of a package from the one index it was given, so install those from the default index first, then ours:
+Packages that come from [micropython-lib](https://github.com/micropython/micropython-lib) (`aioble`, `sdcard`, `bmi270`, `usb-device-*`) aren't copied here. A package that needs one names it under `upstream` in its JSON, and `omip` brings it. `mip` and `mpremote` ignore that key, because they take every file of a package from the one index they were given, so with them install those from the default index first, then ours:
 
 ```python
 mip.install("aioble")

docs/how-it-works/index.md

@@ -8,7 +8,7 @@ A release in any of the source repositories sends this repository a request nami
 
 ## pins.json, then a build
 
-[`publish.yml`](../../.github/workflows/publish.yml) records each request in [`pins.json`](../../pins.json) as soon as it arrives. It then rebuilds every package from the releases pinned there with pydevices' `tools/libbuild.py`, and deploys the result to GitHub Pages.
+[`publish.yml`](../../.github/workflows/publish.yml) records each request in [`pins.json`](../../pins.json) as soon as it arrives. It then rebuilds every package from the releases pinned there with pydevices' `tools/libbuild.py`, and deploys the result to GitHub Pages. Before it deploys, the build checks that no package name here is also one of micropython-lib's, because `omip` looks here first and a match would hide theirs. If micropython-lib's index can't be read, the build warns and carries on.
 
 When a package moves to a new repository, its entry in `pins.json` names the new one and lists the old under `formerly`. A pydevices release made before the move still names the old repository in its `lib-lock.json`; the build takes the package from the new one at the pinned tag.
 

docs/reference/packages.md

@@ -12,4 +12,4 @@ The packages come from these repositories:
 
 A board config's package is named after its folder in [board_configs](https://github.com/PyDevices/pydevices/tree/main/board_configs), and a driver's after its folder in [drivers](https://github.com/PyDevices/pydevices/tree/main/drivers).
 
-Packages from micropython-lib aren't here; [install those first](../get-started/install.md#packages-from-micropython-lib) from the default index.
+Packages from micropython-lib aren't here, and no package here has a name micropython-lib uses: the build fails if one does, so neither can hide the other. `omip` brings them; with `mip`, [install those first](../get-started/install.md#packages-from-micropython-lib) from the default index.