Docs: fix stale cross-repo links, link in-repo files relatively

.site/pyscript/tv/README.md

@@ -11,7 +11,7 @@ use `PSDisplay`, not native `SDLDisplay` / `usdl2`.
 
 From the [PyScript gallery](../index.html) or:
 
-- [tv_remote_menu](../micropython.html?modules=tv_remote_menu) — large-row menu, D-pad / Enter / Back
+- [tv_remote_menu](../../gallery/micropython.html?modules=tv_remote_menu) — large-row menu, D-pad / Enter / Back
 
 Desktop arrow keys stand in for the remote during development.
 
@@ -30,5 +30,5 @@ Mappings live in `displaydev._domkeys._DOM_NAMED_KEYS`. Unknown TV keys arrive a
 
 ## Related
 
-- [Where PWAs run — Smart TVs](https://github.com/PyDevices/pyscript-template/blob/main/docs/pwa-guide.md#where-pwas-run)
-- [PSDisplay](https://github.com/PyDevices/pydevices/blob/main/docs/displaydev.md#psdisplay)
+- [Where PWAs run — Smart TVs](https://github.com/PyDevices/pyscript-template/blob/main/docs/guides/make-it-installable.md#where-pwas-install)
+- [PSDisplay](https://github.com/PyDevices/pydevices/blob/main/docs/guides/displays.md#psdisplay)

.site/wokwi/README.md

@@ -2,7 +2,7 @@
 
 Browser project for [wokwi.com](https://wokwi.com): PyDevices core + `pygraphics` + Wokwi board config + [`testris`](../../lib/examples/testris.py) (a touch + joystick Tetris demo).
 
-**Wokwi reference:** [pydevices/docs/wokwi.md](https://github.com/PyDevices/pydevices/blob/main/docs/wokwi.md)
+**Wokwi reference:** [pydevices/docs/boards/wokwi.md](https://github.com/PyDevices/pydevices/blob/main/docs/boards/wokwi.md)
 
 Board config: [`wokwi_ili9341_ft6x36_esp32s3`](https://github.com/PyDevices/pydevices/tree/main/board_configs/busdisplay/spi/wokwi_ili9341_ft6x36_esp32s3)
 
@@ -21,7 +21,7 @@ Board config: [`wokwi_ili9341_ft6x36_esp32s3`](https://github.com/PyDevices/pyde
 
 ## Quick try (default)
 
-Use `main.py` as committed. On first boot, `mip` downloads PyDevices core + `pygraphics` from the
+Use [`main.py`](main.py) as committed. On first boot, `mip` downloads PyDevices core + `pygraphics` from the
 PyDevices MIP index (network required), then runs **testris** — a touch + joystick Tetris demo. You
 should see the game running — drive it with the on-screen touch keypad.
 

docs/guides/cast-to-a-tv.md

@@ -44,25 +44,25 @@ import lv_test_timer                  # or any app
 
 The picture is the panel's 720x720 in the middle of the TV's 1280x720, at
 about 24 fps. A P4 with no screen of its own casts the full 1280x720 at 18 fps
-([`cast/headless_cast.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/cast/headless_cast.py)). Sound the
+([`cast/headless_cast.py`](../../lib/examples/cast/headless_cast.py)). Sound the
 P4 plays goes with it as 48 kHz audio on the picture's clock, so a drum
 machine's hits land with its step light.
 
 From a desktop, `CastDisplay(..., audio=True)` puts the app's sound on the
-cast: [`miracast/board_config.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/miracast/board_config.py)
+cast: [`miracast/board_config.py`](../../lib/examples/miracast/board_config.py)
 does that, so whatever an app plays through `audiodev` comes out of the TV.
 `audio="song.mp3"` casts a file instead, or any input ffmpeg can open, a
 microphone included, given as a list of ffmpeg arguments.
 
 The P4 also controls the TV over its own network API (ECP, built into every
 Roku, with **Control by mobile apps** on). It can power the TV on, change the
 input or the volume, and press any key.
-[`cast/tv_cast.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/cast/tv_cast.py) turns the TV on and
-casts a melody. The [house panel](https://github.com/PyDevices/gallery/tree/main/lib/examples/house/) has a button that
+[`cast/tv_cast.py`](../../lib/examples/cast/tv_cast.py) turns the TV on and
+casts a melody. The [house panel](../../lib/examples/house) has a button that
 puts the whole panel on the TV.
 
-Examples: [`cast/`](https://github.com/PyDevices/gallery/blob/main/lib/examples/cast/README.md),
-[`miracast/board_config.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/miracast/board_config.py) for any
+Examples: [`cast/`](../../lib/examples/cast/README.md),
+[`miracast/board_config.py`](../../lib/examples/miracast/board_config.py) for any
 app.
 
 ## Miracast to a Windows laptop
@@ -77,7 +77,7 @@ This one talks back. Windows sends the laptop's mouse and keyboard to the
 board (Miracast's UIBC), and `CastDisplay` turns them into touch and key
 events. An app on the P4 can't tell them from its own touch screen: testris
 plays from the laptop's keyboard, and
-[`cast/laptop_input.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/cast/laptop_input.py) draws the
+[`cast/laptop_input.py`](../../lib/examples/cast/laptop_input.py) draws the
 cursor and a dot per click. The Wireless Display window has to have focus:
 it then takes the mouse pointer and the keys, and the Windows key gives them
 back.
@@ -106,17 +106,17 @@ on it.
   270 to 290 ms each PNG takes to encode.
 - **The remote as input.** All eleven buttons a channel can see arrive as key
   presses and releases, and a held button repeats. testris plays from the
-  couch through [`roku/board_config.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/roku/board_config.py).
+  couch through [`roku/board_config.py`](../../lib/examples/roku/board_config.py).
 - **Speech, a dashboard, and frames from any URL**: `say()`, `dashboard()`
   and `frames(url)`, which shows the PNG or JPEG a URL serves, over and over.
-  One example each in [`lib/examples/roku/`](https://github.com/PyDevices/gallery/tree/main/lib/examples/roku/).
+  One example each in [`lib/examples/roku/`](../../lib/examples/roku).
 - **Video**: `video(url)` plays HLS, which is how the next method reaches a
   TV.
 - **Sound**: `RokuAudioSink` streams an app's sound to the TV. The channel
   plays sound or shows frames, not both, and the TV buffers it, so it runs 3.5
   to 5.5 seconds behind. That suits music, not a game; for an app's sound with
   its picture, use Miracast. `SOUND_ON_TV` in
-  [`roku/board_config.py`](https://github.com/PyDevices/gallery/blob/main/lib/examples/roku/board_config.py) turns it on.
+  [`roku/board_config.py`](../../lib/examples/roku/board_config.py) turns it on.
 
 The library is plain sockets plus
 [`pngio`](https://github.com/PyDevices/micropython-pydevices/tree/main/modules/pngio)
@@ -149,7 +149,7 @@ portal's non-LVGL hero apps, polyhedron and radar_scope.
 HLS is video only. A Roku plays HLS audio only as AAC, and the firmware has no AAC
 encoder.
 
-On a desktop, the same `roku_hls/board_config.py` runs under CPython and
+On a desktop, the same [`roku_hls/board_config.py`](../../lib/examples/roku_hls/board_config.py) runs under CPython and
 ffmpeg makes the stream.
 
 ## Let AutoDisplay pick a cast display
@@ -173,7 +173,7 @@ display is never picked unless something asks for it, so nothing streams to a
 TV by surprise. `PYDEVICES_DISPLAY=hls` names one for a single run. On an
 earlier PyDevices there is no registry and the configs work as they always
 did. The registry itself is described in the
-[displaydev guide](https://github.com/PyDevices/pydevices/blob/main/docs/displaydev.md#experimental-your-own-backend).
+[displaydev guide](https://github.com/PyDevices/pydevices/blob/main/docs/guides/displays.md#experimental-your-own-backend).
 
 ## Run a cast example
 

docs/how-it-works/casting.md

@@ -1,6 +1,6 @@
 # How casting works
 
-The [cast README](https://github.com/PyDevices/gallery/blob/main/lib/examples/cast/README.md#how-it-works) covers the
+The [cast README](../../lib/examples/cast/README.md#how-it-works) covers the
 Miracast session (Wi-Fi Display over infrastructure, MICE and RTSP, in
 Python), and the C task that streams MPEG-TS over RTP with the audio on the
 same clock. The encoders and the muxer are firmware modules of their own:
@@ -10,4 +10,4 @@ and the PPA's colour conversion,
 [`ppa`](https://github.com/PyDevices/micropython-pydevices/tree/main/modules/ppa).
 The Companion channel's BrightScript is in
 [`tools/roku_companion_app`](https://github.com/PyDevices/pydevices-examples/blob/main/tools/roku_companion_app/README.md), and its
-Python side in [`lib/utils/roku_companion.py`](https://github.com/PyDevices/gallery/blob/main/lib/utils/roku_companion.py).
+Python side in [`lib/utils/roku_companion.py`](../../lib/utils/roku_companion.py).

lib/examples/blackjack/README.md

@@ -2,14 +2,14 @@
 
 Playing card classes for the PyDevices display stack, and a blackjack game built on them.
 
-Run either one from `lib/` (see [the examples README](../README.md)):
+Run either one from `lib/` (see [the examples README](../../../README.md#run-one-on-your-computer)):
 
 ```bash
 PYTHONPATH=.:lib:utils ../.venv/bin/python examples/blackjack/blackjack.py
 PYTHONPATH=.:lib:utils ../.venv/bin/python examples/blackjack/playing_cards_simpletest.py
 ```
 
-`playing_cards.py` draws with [pygraphics](https://github.com/PyDevices/pygraphics) onto a `displaybuf.DisplayBuffer`, and the examples read taps and clicks through `appdev`.  The classes are an example of what may be done with those pieces.  It is a work in-progress and is likely to change significantly.
+[`playing_cards.py`](playing_cards.py) draws with [pygraphics](https://github.com/PyDevices/pygraphics) onto a `displaybuf.DisplayBuffer`, and the examples read taps and clicks through `appdev`.  The classes are an example of what may be done with those pieces.  It is a work in-progress and is likely to change significantly.
 
 The ultimate goal is to have a set of classes for a [Standard 52-card deck](https://en.wikipedia.org/wiki/Standard_52-card_deck) that may be used to implement any card game that uses such a deck or portion thereof.  Games can use the full deck, or multiple decks, such as the example [blackjack](blackjack.py), or use a portion of a deck, such as Euchre, or a mutiple portions of decks, such as Pinochle.  Using dunder methods, it will be possible to compare one card to another, with each game having its own rules for comparison.  The logic of the game may say `if card1 > card2:`, and the rules of the game would automatically be applied.
 

lib/examples/sensor_hub/README.md

@@ -13,7 +13,7 @@ take over as the hub later.
 ## Run it on a board
 
 The board needs MicroPython with Wi-Fi, a `secrets.py`, and pydevices'
-`wifi.py`: frozen into the firmware, or copied to `/lib` when it isn't ([board bring-up](https://github.com/PyDevices/pydevices/blob/main/docs/board-bringup.md)),
+`wifi.py`: frozen into the firmware, or copied to `/lib` when it isn't ([board bring-up](https://github.com/PyDevices/pydevices/blob/main/docs/guides/bring-up-a-board.md)),
 and for the Bluetooth door, `bledev` and `aioble` (`mpftp mip -d COM5 aioble`).
 
 ```bash
@@ -87,7 +87,7 @@ pressure, light and motion to a hub every 2 s, and shows them on its screen.
 Its five DotStars are switched off at start.
 
 It runs stock MicroPython (`ESP32_GENERIC_S2`), brought up as in
-[board bring-up](https://github.com/PyDevices/pydevices/blob/main/docs/board-bringup.md)
+[board bring-up](https://github.com/PyDevices/pydevices/blob/main/docs/guides/bring-up-a-board.md)
 with the [`board_configs/busdisplay/spi/funhouse`](https://github.com/PyDevices/pydevices/tree/main/board_configs/busdisplay/spi/funhouse) package. Then:
 
 ```bash

lib/examples/tower_climb/README.md

@@ -18,15 +18,15 @@ climbers. Early work focused on:
 - Landing/collision physics stable enough for repeated jumps up procedurally
   placed branches
 - The shared periodic timer via ``appdev.App`` for display refresh
-  (see [app-and-board-config.md](https://github.com/PyDevices/pydevices/blob/main/docs/app-and-board-config.md) for the timer/display split)
+  (see [write-an-application.md](https://github.com/PyDevices/pydevices/blob/main/docs/guides/write-an-application.md) for the timer/display split)
 
 Gameplay bugs (flicker, respawn deaths, camera clamp at the crown, bot pathing)
 were fixed iteratively using the trace stream and bot playtests below rather than
 manual play alone.
 
 Levels are randomized each round (`_build_level()`). Pass `--seed N` for
 a reproducible RNG state when bisecting a layout. Developer hazard pacing is
-controlled by the `DIFFICULTY` constant at the top of `tower_climb.py`.
+controlled by the `DIFFICULTY` constant at the top of [`tower_climb.py`](tower_climb.py).
 
 ## Package layout