diff --git a/docs/dev/development.md b/docs/dev/development.md
index 3ce307d..de2437b 100644
--- a/docs/dev/development.md
+++ b/docs/dev/development.md
@@ -217,6 +217,12 @@ job, or to catch up a mirror that failed after its release was published. `ci.ym
 resolve fails there rather than at the release. The scripts live under `.gitea/`, which
 `dist export` does not copy, so none of this reaches an instance.
 
+Both jobs write with the job token, which needs `permissions: wiki: write` - Gitea gives the wiki
+a token scope of its own, and `contents: write` does not cover it (the API answers 403). If the
+repository's Actions settings ever cap the token below that, the mirror fails until the cap is
+lifted. A wiki that has never had a page has no repository to clone yet; `wiki-push.sh` then
+creates the first page through the API and clones afterwards.
+
 ### How much of the stack the suite reaches
 
 Coverage is measured in CI - `pytest --cov`, config in `tools/.coveragerc`, HTML and XML