docs/agents/issue-tracker.md

@@ -57,28 +57,27 @@ preference — move it.
   so any non-interactive shell (every agent) hangs forever without
   `</dev/null`. Same trap on `tea issues create --description` and
   `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.
+- **Apply / remove labels**: `tea issues edit <number> --add-labels "Kind/Bug"`
+  (and `--remove-labels`). This handles org-level labels (`Kind/*`,
+  `Priority/*`, `Reviewed/*`, `Status/*`) from tea 0.15 onwards. On 0.14 it did
+  not: name resolution searched only this repo's own label set, so an org label
+  matched nothing and the command exited 0, printed the issue, and changed
+  nothing. Upstream fixed it in v0.15 (`modules/task/labels.go` also queries
+  `ListOrgLabels`). Note `tea labels` lists repo labels only and will not show
+  you the org set — `tea api orgs/ShadowsOverWestgate/labels` does.
+- **`tea api` can read but not write.** Writing methods (`--method POST`,
+  `PATCH`, ...) return `{"message":"token is required"}`. GETs against these
+  public repos succeed anonymously, which makes the gap easy to miss: reads
+  work, writes do not. Use the `tea issues` / `tea pr` subcommands for anything
+  that changes state.
+- **Verify every label change by re-reading it.** A label command exiting 0 is
+  not evidence it applied — that is exactly how the 0.14 silent no-op above hid
+  for so long, and assuming otherwise has already cost one investigation
+  several wrong turns. Read the resulting set back with
+  `tea api repos/ShadowsOverWestgate/sow-tools/issues/<number>` and check its
+  `labels` field, or `tea issues ls -o json`. The read-back reflects the write
+  immediately; if it comes back empty, the write genuinely failed. Do not
+  explain an empty read-back away as replication lag.
 - **Close**: `tea issues close <number>`
 
 `tea` infers the repo from the git remote when run inside the clone.

docs/agents/triage-labels.md

@@ -24,11 +24,17 @@ this.
 tea issues create --title "..." --description "..." --labels "Kind/Bug" </dev/null
 tea pr create --title "..." --description "..." --labels "Kind/Feature" </dev/null
 
-# add a label to something that already exists
-tea api --method POST "repos/ShadowsOverWestgate/<repo>/issues/<n>/labels" \
-  --data '{"labels":["Kind/Bug","Priority/High"]}'
+# add a label to something that already exists (needs tea >= 0.15 for org labels)
+tea issues edit <n> --add-labels "Kind/Bug,Priority/High"
+
+# read the result back — exit 0 is not evidence the label applied
+tea api "repos/ShadowsOverWestgate/<repo>/issues/<n>"
 ```
 
+`tea api` writes (`--method POST`, `PATCH`, ...) fail with
+`{"message":"token is required"}`; only reads work anonymously. Label changes
+go through `tea issues edit`.
+
 ## Kind — what this is (pick exactly one)
 
 | Label                | Use it when                                                     |