diff --git a/AGENTS.md b/AGENTS.md
index 6089e5b..6690ed7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -128,6 +128,23 @@ curl -s https://api.github.com/repos/anomalyco/opencode/releases/tags/v1.15.10 |
 - **Step scripts run under `/bin/sh` (dash), not bash.** Avoid bash-isms like `${VAR//a/b}` parameter-pattern substitution; use POSIX alternatives (`tr`, `sed`) or declare `shell: bash` on the step.
 - **`BUILDKIT_PROGRESS=plain`** is set at workflow level on `docker-publish-split.yml` so arm64-under-QEMU builds log each layer line-by-line. The default collapsed progress UI hides which step is stalled, which made diagnosing earlier hangs expensive.
 
+## Gitea API access (env token)
+
+`GITEA_ACCESS_TOKEN` + `GITEA_HOST` are passed into the container from the
+host `.env` via `docker-compose.yml` / `docker-compose.shared.yml`
+(`${GITEA_ACCESS_TOKEN:-}` / `${GITEA_HOST:-}`), primarily to enable the
+`gitea-mcp` server (see `generate-config.py`). They are **not** baked into
+the image. When configured, they are also available for **any** direct
+Gitea API interaction from inside the container — inspecting CI runs,
+checking published tags, listing commits — e.g.
+`curl -H "Authorization: token $GITEA_ACCESS_TOKEN" "$GITEA_HOST/api/v1/repos/joakimp/opencode-devbox/actions/runs?limit=5"`.
+Prefer this over a short-lived PAT file when the env token is present (the
+`ci-release-watcher` skill auto-detects it). Public-repo GET listings work
+unauthenticated (see the `resolve-versions` mempalace-toolkit note above), so
+the token matters mainly for private repos or rate-limit headroom; its
+lifecycle is host-managed, so there is nothing to revoke after use. Never
+echo the token value (including into logs).
+
 ## Testing changes
 
 The smoke test (`scripts/smoke-test.sh`) is the canonical check and runs automatically in CI. To run locally: