diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index 6c15f20..878bb7a 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -59,6 +59,12 @@ preference — move it.
   `tea pr create`.
 - **Apply / remove labels**: `tea api --method PATCH` on the issue, or
   `tea api repos/ShadowsOverWestgate/sow-tools/issues/<number>/labels` endpoints.
+  `tea issues edit --add-labels` works too, org-level labels (`Kind/*`,
+  `Priority/*`) included, but a read-back straight afterwards can still show
+  the old set — `tea issues ls` has returned stale labels for several seconds
+  after an edit that succeeded. Never conclude an edit failed from a single
+  immediate list; re-read after a pause, or use the `labels` endpoints above,
+  whose response *is* the resulting label set and needs no second call.
 - **Close**: `tea issues close <number>`
 
 `tea` infers the repo from the git remote when run inside the clone.