fix: annotate POST render endpoints read-only and irreversible POSTs destructive

docs/adr/0003-generated-tool-catalog.md

@@ -24,7 +24,13 @@ Coverage target: every operation in the instance swagger gets a tool. Gitea
   false` everywhere we control. Owner, repo and username path parameters get
   name patterns.
 - Annotations: `readOnlyHint` for GET, `destructiveHint` for DELETE and for
-  PUT/PATCH that replace state, `idempotentHint` for GET/PUT/DELETE.
+  PUT/PATCH that replace state, `idempotentHint` for GET/PUT/DELETE. A small
+  explicit override set in `catalog/build.py` corrects POST operations: the
+  render endpoints (`/markdown`, `/markdown/raw`, `/markup`) and the read-only
+  `file-contents` POST are read-only and idempotent; irreversible or
+  wide-reaching POSTs (PR merge, merge upstream, repo transfer and its
+  accept/reject, user and org rename, cron run, mirror sync, adopt unadopted
+  repository) are destructive.
 - Every tool also accepts optional `sudo` (admin acts as another user).
 - One extra hand-written tool, `gitea_api_request`, reaches endpoints added in
   newer Gitea versions than the pinned spec.