diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md
index 6313d66..b60b3bd 100644
--- a/docs/agents/issue-tracker.md
+++ b/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`,
-  `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.
+- **`tea api` needs a token in the login; SSH auth is not enough.** It sends
+  only the login's `token:` field and does not sign requests with your SSH key,
+  so an SSH-key-only login gets `{"message":"token is required"}` on every call
+  that needs auth. Reads against these public repos still succeed anonymously,
+  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
diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md
index 195268a..a863026 100644
--- a/docs/agents/triage-labels.md
+++ b/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
-`{"message":"token is required"}`; only reads work anonymously. Label changes
-go through `tea issues edit`.
+`tea api` sends only the login's `token:` and never your SSH key, so on an
+SSH-only login every authenticated call fails with
+`{"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)