diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index 6c15f20..1ae498c 100644
--- a/docs/agents/issue-tracker.md
+++ b/docs/agents/issue-tracker.md
@@ -59,6 +59,26 @@ 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.
+- **Org-level labels (`Kind/*`, `Priority/*`, `Reviewed/*`, `Status/*`)**: `tea
+  issues edit --add-labels` / `--remove-labels` do **not** apply these on tea
+  0.14.0, the version nixpkgs pins. Name resolution searches only this repo's
+  own label set, so an org label matches nothing and the command exits 0,
+  prints the issue, and changes nothing — no error, no warning. Repo-local
+  labels (`wayfinder:*`, `ready-for-agent`) are unaffected. PRs no-op the same
+  way. Upstream fixed it in v0.15 (`modules/task/labels.go` now also queries
+  `ListOrgLabels`), so this expires when tea is bumped; until then apply org
+  labels in the web UI. Note `tea labels` lists repo labels only, so it will
+  not show you the org set either — `tea api orgs/ShadowsOverWestgate/labels`
+  does.
+- **Verify every label change by re-reading it.** `tea issues ls -o json` has a
+  `labels` field; use it. A label command exiting 0 is not evidence it applied,
+  and assuming otherwise has already cost one investigation several wrong turns.
+  `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.