Docs: the five-section template, with the release runbook split and re-checked

.github/workflows/reusable-publish-release-packages.yml

@@ -71,8 +71,8 @@ on:
         default: false
         type: boolean
     outputs:
-      # What a caller's own PyPI job needs; see "Production PyPI" in
-      # docs/publishing-automation.md for the job that reads them.
+      # What a caller's own PyPI job needs; see
+      # docs/guides/publish-to-pypi.md for the job that reads them.
       pypi-publish:
         description: >-
           'true' when the caller should upload to production PyPI: pypi-publish

AGENTS.md

@@ -1,9 +1,9 @@
 # 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)).
+- `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 ([the release chain](docs/how-it-works/release-chain.md), [roll back a release](docs/guides/roll-back-a-release.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).
+- Repository layout and file-naming conventions, including the `MICROPYPATH` / `PYTHONPATH` search paths: [repo-layout](docs/reference/repo-layout.md). Heading emoji and docstring style: [heading emoji](docs/reference/heading-emoji.md), [docstrings](docs/guides/write-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)).

CONTRIBUTING.md

@@ -10,16 +10,16 @@ instructions — read that first.
 Org-wide standards every shipped design is measured against — starting
 with completeness ("any pairing the protocols permit that the design does
 not deliver is a defect in the design, not a feature request") — live in
-[`docs/design-principles.md`](docs/design-principles.md).
+[`docs/how-it-works/design-principles.md`](docs/how-it-works/design-principles.md).
 
 ## Where things live
 
 Repo directory and root-file layout (`src/`, `lib/`, `tests/`,
-`requirements-dev.txt`, …): see [`docs/repo-layout.md`](docs/repo-layout.md).
+`requirements-dev.txt`, …): see [`docs/reference/repo-layout.md`](docs/reference/repo-layout.md).
 
 The full repository map — every repo, grouped by tier, with what each one owns —
 is generated from `data/repos_db.json` and published at
-[pydevices/docs/ecosystem.md](https://github.com/PyDevices/pydevices/blob/main/docs/ecosystem.md) and on the
+[pydevices/docs/how-it-works/ecosystem.md](https://github.com/PyDevices/pydevices/blob/main/docs/how-it-works/ecosystem.md) and on the
 [org profile](https://github.com/PyDevices). Do not restate it here; it drifts.
 
 If you're not sure which repo an issue or PR belongs to, open it on
@@ -62,5 +62,5 @@ regenerate; don't hand-edit generated files anywhere else.
 ## Doc style: emoji
 
 Docs across PyDevices use a small, fixed set of emoji as landmarks on
-section headings — see [`docs/doc-style.md`](docs/doc-style.md) for the
+section headings — see [`docs/reference/heading-emoji.md`](docs/reference/heading-emoji.md) for the
 full table and rules of thumb before adding or changing heading emoji.

README.md

@@ -21,8 +21,8 @@ the parts they'd otherwise duplicate.
   PyPI, report health) shared by seven publishing repositories. Callers pin a
   `publishing-vN` tag, never a branch; those tags are immutable by policy and
   by an active GitHub tag ruleset on this repository that blocks moving or
-  deleting one. See [`docs/publishing-automation.md`](docs/publishing-automation.md)
-  for the runbook and [`docs/workflows.md`](docs/workflows.md) for the full
+  deleting one. See [Release a package](docs/guides/release-a-package.md)
+  for the runbook and [Workflows](docs/reference/workflows.md) for the full
   workflow inventory.
 - **[`RELEASE_HEALTH.md`](RELEASE_HEALTH.md)** — one row per published
   distribution (version, TestPyPI/assets/MIP/PyPI outcome, last-updated,
@@ -41,18 +41,16 @@ the parts they'd otherwise duplicate.
   landing page is published. [`scripts/generate_sites.py`](scripts/generate_sites.py)
   renders it into the org portal, into per-repo `.site/` trees, into
   [`profile/README.md`](profile/README.md), and into
-  [pydevices/docs/ecosystem.md](https://github.com/PyDevices/pydevices/blob/main/docs/ecosystem.md).
+  [pydevices/docs/how-it-works/ecosystem.md](https://github.com/PyDevices/pydevices/blob/main/docs/how-it-works/ecosystem.md).
   **Edit the database, not the generated markup** — run the generator by hand
   from a full workspace checkout (`python3 dotgithub/scripts/generate_sites.py`)
   after editing it; it validates the database first and is idempotent.
 - **Roadmap** — [`ROADMAP.md`](ROADMAP.md): what's planned for the shared
   automation. Every repository keeps its own.
-- **History** — [`docs/history.md`](docs/history.md): how the organization
-  came to be, and a dated chronology of every repository.
-- **Org docs** — [`docs/`](docs/) covers repo layout, doc style and
-  docstring conventions, how the ReadTheDocs sites build, GitHub presence
-  (Discussions/Issues/Pages/licensing), publishing automation, and the
-  operations runbook.
+- **Docs** — [`docs/`](docs/index.md) covers setting up a checkout, releasing
+  a package, rolling back and fixing a release, building the Read the Docs
+  sites, the repository layout and docstring conventions, and where things
+  live on GitHub.
 
 Board / Detect inventory docs live in
 [pydevices/docs](https://github.com/PyDevices/pydevices/tree/main/docs)

ROADMAP.md

@@ -4,4 +4,10 @@ Where the org's shared release automation and community files are heading.
 Bugs, and things you need that don't work yet, go to
 [issues](https://github.com/PyDevices/.github/issues).
 
-Nothing is planned beyond what the issues track.
+- **Real dependencies for MIP packages.** The index builder folds a required
+  package's files into the package that requires it and records no install-time
+  dependencies. The plan is for the index to carry real ones, so installing one
+  package brings in what it needs without duplicating files.
+- **Type stubs for every published package.** The libraries keep types in
+  docstrings because annotations cost memory on a microcontroller. The plan is
+  to ship `.pyi` stubs so editors and type checkers on a desktop see real types.

docs-site/install.md

@@ -2,7 +2,7 @@
 
 How you install PyDevices depends on where your code will run. The exact
 commands and the system packages each channel needs are in the
-[install workflows](https://github.com/PyDevices/pydevices/blob/main/docs/install-workflows.md)
+[install guide](https://github.com/PyDevices/pydevices/blob/main/docs/get-started/install.md)
 of the `pydevices` repository; this page is the short version.
 
 ::::{tab-set}
@@ -17,7 +17,7 @@ mip.install("palettes", index="https://PyDevices.github.io/mip")
 
 A board's `board_config` installs the same way and wires up the display and
 touch for that board. The board's page in the
-[device matrix](https://github.com/PyDevices/pydevices/blob/main/docs/device-matrix.md)
+[device matrix](https://github.com/PyDevices/pydevices/blob/main/docs/boards/device-matrix.md)
 names the package to ask for.
 :::
 
@@ -57,5 +57,5 @@ python -c "from board_config import display_drv; display_drv.fill_rect(50, 50, 1
 
 If a window opens with a red square in it, the stack is working. If it does
 not, the
-[troubleshooting page](https://github.com/PyDevices/pydevices/blob/main/docs/troubleshooting.md)
+[troubleshooting page](https://github.com/PyDevices/pydevices/blob/main/docs/guides/troubleshooting.md)
 is the next stop.

docs-site/newcomers.md

@@ -30,7 +30,7 @@ Each project's manual has its own newcomer's guide.
 
 The board you own has a `board_config` that sets up its display and touch, so
 the program you ran on the desktop starts the same way on the board. The
-[device matrix](https://github.com/PyDevices/pydevices/blob/main/docs/device-matrix.md)
+[device matrix](https://github.com/PyDevices/pydevices/blob/main/docs/boards/device-matrix.md)
 lists the boards, and [mpftp](https://github.com/PyDevices/mpftp) copies files
 to them and gives you a REPL from your editor.
 

docs/get-started/first-release.md

@@ -0,0 +1,25 @@
+# Cut your first release
+
+You release a package by merging a pull request. Pick a repository that
+publishes (see [what each repository publishes](../reference/release-workflows.md#what-each-repository-publishes))
+and start with a development version. It reaches TestPyPI, the release's
+attached files and, for a repository that requests it, the library index, but not the MIP index or production PyPI.
+
+```bash
+gh workflow run prepare-release.yml --repo PyDevices/<repository> -f version=X.Y.Z.dev1
+```
+
+Within a minute the repository has a pull request named `Release X.Y.Z.dev1`
+on a `release/vX.Y.Z.dev1` branch. It changes `VERSION` and adds a section to
+`CHANGELOG.md`. Check the version, read the changelog section, wait for CI,
+then merge it.
+
+Merging tags `vX.Y.Z.dev1`, creates the GitHub Release, and starts the
+publish run. When the run finishes, the package is on TestPyPI and the
+release's row in [`RELEASE_HEALTH.md`](../../RELEASE_HEALTH.md) shows each
+stage's outcome with a link to the run.
+
+The [release guide](../guides/release-a-package.md) covers a final release,
+a retry and the manual fallback, and
+[the release chain](../how-it-works/release-chain.md) explains why each step
+exists.

docs/get-started/set-up.md

@@ -0,0 +1,43 @@
+# Set up a checkout
+
+Work on this repository from a clone. The scripts and tests need nothing
+beyond Python 3 and `ruff`.
+
+```bash
+git clone https://github.com/PyDevices/.github.git dotgithub
+cd dotgithub
+python3 -m unittest discover -s tests -v    # the publishing-script tests
+python3 -m pip install ruff
+ruff check scripts/ tests/                   # lint, as CI runs it
+```
+
+Those two commands are what the `unittest` and `ruff` jobs in
+[`checks.yml`](../../.github/workflows/checks.yml) run. The same file lints
+every workflow with actionlint, parses each reusable workflow as YAML, checks
+that the reusables' `publishing-vN` references agree, and builds the
+[main documentation project](../guides/build-and-publish-docs.md) with warnings
+as errors, so a pull request here sees all of them.
+
+## Regenerate the org sites
+
+[`data/repos_db.json`](../../data/repos_db.json) is the one source for the
+repository map: each repository's tier, description, buttons and the place its
+landing page is published. Edit it, never the pages it produces, then run the
+generator:
+
+```bash
+python3 scripts/generate_sites.py
+```
+
+The generator writes into sibling repositories (the portal, the per-repository
+`.site/` trees, the organization profile and the `pydevices` ecosystem page),
+so clone the repositories it writes to (`PyDevices.github.io`, `pydevices`,
+`gallery` and `mip`) side by side, and name this one `dotgithub` on disk, the
+folder name the generator looks for:
+
+```bash
+git clone https://github.com/PyDevices/.github.git dotgithub
+```
+
+A clean run produces no diff; `checks.yml` runs it against fresh clones and
+fails on any change.