bdbarnett · Oct 28, 2026 · Oct 28, 2026 · Oct 28, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,132 +1,9 @@
-# AGENTS.md — Cloud agent workspace layout
-
-Instructions for AI agents and humans working in the **PyDevices cloud
-workspace** (Cursor Cloud Agent VM). This complements
-[CONTRIBUTING.md](CONTRIBUTING.md), [docs/github-presence.md](docs/github-presence.md),
-and the shared directory convention in [docs/repo-layout.md](docs/repo-layout.md).
-
-On a developer laptop, repos usually live as siblings under a single parent
-(e.g. `~/gh/pydevices/`). The cloud VM mirrors that layout under
-`/home/ubuntu/gh/` using symlinks into `/agent/repos/`.
-
-**Automatic setup:** `.cursor/environment.json` in this repo runs
-`scripts/cloud-workspace-install.sh`, `scripts/cloud-python-deps.sh`, and
-`scripts/cloud-pydevices-examples-dev-env.sh` on each cloud VM boot (all idempotent).
-After a successful install, agents should start real work immediately — no
-separate “workspace configuration” chat.
-
-`cloud-workspace-install.sh`:
-- Creates `/agent/repos` when missing and shallow-clones any absent PyDevices
-  siblings (Cursor’s `repositoryDependencies` expands GitHub token scope; it
-  does not always materialize those checkouts).
-- Builds `~/gh/pydevices/` symlinks, shallow-clones MicroPython/CircuitPython,
-  inits `lvgl-bindings/lvgl`, and replaces an empty `lvgl-python/lvgl`
-  placeholder with the canonical symlink.
-- Exits non-zero if required repos or LVGL are still missing.
-
-`cloud-python-deps.sh`:
-- Installs `python3-venv` / `libsdl2-dev` via apt when the VM snapshot omits
-  them, recreates broken `.venv` leftovers, then installs pydevices-examples
-  (`requirements-dev.txt` + `pygame-ce` + `pydevices-lvgl`), `ruff` for
-  `palettes`/`pdwidgets`, and a `pydevices_siblings.pth` so examples import
-  canonical product sources from `pydevices` plus the sibling
-  `palettes`, `pdwidgets`, and `pygraphics` sources.
-
-`cloud-pydevices-examples-dev-env.sh`:
-- Installs pydevices-examples `requirements.txt` (TestPyPI runtime stack for CPython).
-- `micropython -m mip install`s desktop `board_config`, `palettes`, and `pdwidgets` into
-  `~/.micropython/lib` (`--no-mpy -t lib -i` PyDevices index for CP-shared source
-  installs; omit `--no-mpy` for MicroPython-only `.mpy` — see
-  pydevices `docs/install-workflows.md`).
-- Appends a `pydevices-examples-env.sh` hook to `~/.bashrc` exporting `PATH`
-  (`pydevices-examples/bin`) plus `PYTHONPATH` / `MICROPYPATH` entries for
-  `pydevices-examples/lib/utils` and the canonical `pydevices` product paths.
-  Run examples from `pydevices-examples/lib/`.
-
-Use the **`pydevices-cloud-handoff`** skill (`/pydevices-cloud-handoff`) when
-handing work from Cursor desktop to Cloud Agents.
-
-## Top-level layout
-
-```
-/home/ubuntu/gh/
-└── pydevices/
-    ├── micropython           a clone at the tag micropython-pydevices pins, the patch series applied
-    ├── circuitpython         a clone at the pinned CircuitPython tag
-    ├── micropython-pydevices -> /agent/repos/micropython-pydevices
-    ├── audiodsp, pygraphics, lvgl-* ...  -> /agent/repos/<name>   (displayif, audioif, cameraif and usbhost are in micropython-pydevices/modules/)
-    ├── dotgithub             -> /agent/repos/.github   (this repo)
-    ├── pydevices  -> /agent/repos/pydevices
-    ├── mpftp                 -> /agent/repos/mpftp
-    ├── PyDevices.github.io   -> /agent/repos/PyDevices.github.io
-    ├── palettes              -> /agent/repos/palettes
-    ├── pdwidgets             -> /agent/repos/pdwidgets
-    ├── pydevices-examples             -> /agent/repos/pydevices-examples
-    ├── android-template     -> /agent/repos/android-template
-    └── pyscript-template    -> /agent/repos/pyscript-template
-```
-
-**Not cloned locally:** `mip` — GitHub Actions owns sync and
-release there; agents should not add it to this workspace unless explicitly
-asked.
-
-## Workspace interior
-
-Every repository is a sibling at the workspace root, linked in from
-`/agent/repos/`, not duplicated, and the two interpreter checkouts sit beside
-them. That is the layout micropython-pydevices' presets assume (their paths
-resolve two levels up from `manifests/`), and the one every build script in
-the org defaults to: from `micropython/ports/<port>`, upstream's own `make`
-with `VARIANT_DIR=`, `BOARD_DIR=` and `FROZEN_MANIFEST=` pointing into
-`micropython-pydevices`; for CircuitPython, the same `build_mp.py` with
-`--interpreter circuitpython`, which builds each repo's `micropython.mk` as a
-user C module.
-
-Upstream trees (`micropython/`, `circuitpython/`) are **read-only clones** in
-this workspace. The MicroPython one carries a single local commit, the
-PyDevices overlay, written by `micropython-pydevices/tools/prepare-micropython.sh`;
-do not commit anything else inside them.
-
-### Upstream clones
-
-`scripts/cloud-workspace-install.sh` clones both at the pinned tags (blob-filtered,
-so `git apply` still works) and runs `prepare-micropython.sh`. The lvgl-bindings
-`lvgl` submodule is initialised there too, and `lvgl-python/lvgl` is a symlink to
-it (one LVGL tree, never two):
-
-```bash
-cd /home/ubuntu/gh/pydevices
-git -C lvgl-bindings submodule update --init --depth 1 lvgl
-rm -rf lvgl-python/lvgl          # only if empty placeholder
-ln -s ../lvgl-bindings/lvgl lvgl-python/lvgl
-```
-
-## Symlink safety
-
-When removing paths under `pydevices/`, delete **symlinks only**
-(`rm path` on the link), never `rm -rf` through a symlink into
-`/agent/repos/*` unless the intent is to destroy an owned repo.
-
-## GitHub auth — opening PRs on sibling repos
-
-Cloud Agents started from **`PyDevices/.github`** get an integration credential that can **push** branches into `/agent/repos/*` checkouts. When creating PRs on sibling repositories, use `gh pr create` with standard `GH_TOKEN` environment authentication:
-
-```bash
-gh pr create -R PyDevices/<repo> --base main --head <branch> --title "…" --body "…"
-```
-
-## Multi-Repository Command Iteration
-
-See [`.agents/rules/multi_repo_command_rule.md`](../.agents/rules/multi_repo_command_rule.md)
-at the workspace root — the single home for this rule.
-
-## Known Environment Bugs
-
-- **Checkpoints swallowing tool responses**: If an agent issues a tool call exactly as a context checkpoint fires, the response can be silently lost, causing the agent to appear hung. If this happens, ask the agent to "try again". Tracked upstream at [google-antigravity/antigravity-cli#793](https://github.com/google-antigravity/antigravity-cli/issues/793).
-
-## Related docs
-
-- [micropython-pydevices](https://github.com/PyDevices/micropython-pydevices) —
-  presets, variants, boards and the patch series the builds use
-- [lvgl-bindings CONTRIBUTING.md, Releasing](https://github.com/PyDevices/lvgl-bindings/blob/main/CONTRIBUTING.md#releasing) —
-  binding regeneration and `lvgl-python` release dispatch
+# AGENTS.md
+
+- Tests: `python3 -m unittest discover -s tests -v` from the repo root. Lint is `ruff check scripts/ tests/`.
+- `publishing-vN` tags are immutable: a bad one is fixed with a new `vN+1`, never by moving or deleting the tag. The reusable workflows are called by that tag, not a branch ([publishing automation](docs/publishing-automation.md), [operations runbook](docs/operations-runbook.md)).
+- Don't hand-edit `RELEASE_HEALTH.md` or `release-health/data.json`; the release-health workflow rewrites them on every release report.
+- Edit `data/repos_db.json`, never the generated markup, then run `python3 scripts/generate_sites.py`. It writes into the sibling repositories (`profile/README.md`, per-repo `.site/` trees, the pydevices ecosystem page), so run it with the repos checked out side by side ([README](README.md)).
+- `.cursor/environment.json` lists the repos Cursor's cloud environment clones; keep it in step by hand when a public repository is added or retired.
+- Repository layout and file-naming conventions, including the `MICROPYPATH` / `PYTHONPATH` search paths: [repo-layout](docs/repo-layout.md). Doc and docstring style: [doc-style](docs/doc-style.md), [docstrings](docs/docstrings.md).
+- Other repositories' generated files are overwritten by their sync scripts, so change the generator, not the copy ([CONTRIBUTING.md](CONTRIBUTING.md#generated-files-and-sync-targets)).
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/scripts/cloud-python-deps.sh b/scripts/cloud-python-deps.sh
@@ -9,7 +9,7 @@
 #   - pydevices-examples  (flagship)  -> requirements-dev.txt + pygame-ce + native audio/LVGL bindings
 #   - palettes   pdwidgets   -> ruff
 #
-# Safe to run on every cloud VM boot (environment.json install). See AGENTS.md.
+# Safe to run on every cloud VM boot (environment.json install).
 # Intentionally does NOT `set -e`: a single optional install (e.g. TestPyPI
 # pydevices-lvgl) must never abort VM startup for the whole team. Required
 # failures (no ensurepip after apt) still exit non-zero at the end.

diff --git a/scripts/cloud-workspace-install.sh b/scripts/cloud-workspace-install.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # Idempotent PyDevices cloud workspace layout: ~/gh/pydevices symlinks into /agent/repos.
-# See AGENTS.md. Safe to run on every cloud VM boot (environment.json install).
+# Safe to run on every cloud VM boot (environment.json install).
 #
 # Self-heals when Cursor did not materialize sibling checkouts under /agent/repos
 # (common for repo-file environments: repositoryDependencies expands the GitHub