docs(agents): tea api needs a token, not a different verb

Corrects the bullet added in the previous commit. It read "tea api can read
but not write", which described the symptom rather than the rule.

`tea api` sends only the login's `token:` field and never signs requests with
the SSH key, so on an SSH-only login every authenticated call fails with
`{"message":"token is required"}` — writes and authenticated reads alike.
Anonymous reads against these public repos still succeed, which is why it
looked like a read/write split. Adding a token to the login makes the raw
endpoints work in both directions, confirmed by a POST to the issue labels
endpoint that applied and read back.

The `tea issues` / `tea pr` subcommands authenticate over SSH and keep working
with no token at all. That asymmetry is the confusing part, so it is now
stated outright.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/agents/issue-tracker.md

@@ -65,11 +65,16 @@ preference — move it.
   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`,
+- **`tea api` needs a token in the login; SSH auth is not enough.** It sends
-  `PATCH`, ...) return `{"message":"token is required"}`. GETs against these
+  only the login's `token:` field and does not sign requests with your SSH key,
-  public repos succeed anonymously, which makes the gap easy to miss: reads
+  so an SSH-key-only login gets `{"message":"token is required"}` on every call
-  work, writes do not. Use the `tea issues` / `tea pr` subcommands for anything
+  that needs auth. Reads against these public repos still succeed anonymously,
-  that changes state.
+  which hides the gap until the first write. Add a token to the login in
+  `~/.config/tea/config.yml` (Settings > Applications; `write:issue` covers
+  labels, comments and dependencies) and `tea api` works for reads and writes
+  alike. The `tea issues` / `tea pr` subcommands authenticate either way, so
+  they keep working with no token at all — that asymmetry is what makes this
+  confusing to diagnose.
 - **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

docs/agents/triage-labels.md

@@ -31,9 +31,11 @@ tea issues edit <n> --add-labels "Kind/Bug,Priority/High"
 tea api "repos/ShadowsOverWestgate/<repo>/issues/<n>"
 ```
 
-`tea api` writes (`--method POST`, `PATCH`, ...) fail with
+`tea api` sends only the login's `token:` and never your SSH key, so on an
-`{"message":"token is required"}`; only reads work anonymously. Label changes
+SSH-only login every authenticated call fails with
-go through `tea issues edit`.
+`{"message":"token is required"}` while anonymous reads still work. Add a token
+to `~/.config/tea/config.yml` if you want the raw endpoints. `tea issues edit`
+needs no token.
 
 ## Kind — what this is (pick exactly one)