installer: name why GitHub's API refused, and retry a refused token once without it

docs/GUIDE.md

@@ -119,7 +119,7 @@ curl -fsSL https://agentfield.ai/get/codeaf | VERSION=<tag> bash
 | `--no-modify-path` | Print the PATH line without editing a shell file or linking into a folder on PATH. |
 | `--no-start` or `CODEAF_NO_START=1` | Do not ask to start codeaf when the install ends. |
 | `--verbose` | Print each GET. |
-| `GITHUB_TOKEN` or `GH_TOKEN` | Raise GitHub's anonymous API limit. |
+| `GITHUB_TOKEN` or `GH_TOKEN` | Raise GitHub's API limit; a token GitHub refuses is set aside for one anonymous try. |
 
 The script needs `curl` or `wget`, plus `sha256sum` or `shasum`. It downloads
 `checksums.txt` and refuses a sha256 mismatch. Unless `--no-modify-path` is set, it

docs/changes/unreleased/1890-installer-names-api-refusal.md

@@ -0,0 +1,24 @@
+---
+kind: fixed
+title: the installer says why GitHub's API refused, and retries once without a token GitHub refused
+pr: 1890
+surface: [build, docs]
+invalidates:
+  - >-
+    One sentence was believed to cover every refusal from GitHub's API:
+    `GitHub's API could not be reached or refused (a rate limit, or a repository
+    you cannot read?); pin VERSION=<tag>, or export GITHUB_TOKEN`. It is retired.
+    The installer now names a used-up rate limit with the local time it lifts, a
+    rejected token, refused access, a repository it cannot find, a server fault or
+    an unreachable host, and never tells someone who exported a token to export one.
+  - >-
+    A token GitHub refused ended the install. A 401, 403 or 429 on a token-bearing
+    lookup now sets the token aside and asks the same lookup once without it,
+    because the anonymous quota is a separate bucket; the install goes on with the
+    note `GitHub refused GITHUB_TOKEN (…); continuing without it`.
+---
+
+`http_get` used to keep only the status code, so the reason GitHub gives in the
+same response (`x-ratelimit-remaining`, `x-ratelimit-reset`, the body's
+`message`) was discarded. It now keeps the headers and body, and a pure function
+of the three picks the sentence. Downloads still never carry the token.

internal/manual/chat/running-from-the-terminal.md

@@ -197,6 +197,33 @@ in the repository, and the `telemetry` switch in `/settings` turns them off.
 running the install line again works too. With `automatic updates` on, a codeaf
 installed this way also installs each new stable release itself as it opens.
 
+## The installer stopped — GitHub API rate limit used up, curl install fails with 403, 401 Bad credentials, GitHub rejected GITHUB_TOKEN, token refused, repository you cannot read
+
+The installer names GitHub's refusal. These are example messages; `HH:MM ZONE`
+stands for the reset time GitHub supplies:
+
+- `GitHub's API rate limit for this address is used up until HH:MM ZONE; export GITHUB_TOKEN to use your own, or pin VERSION=<tag>`
+- `GitHub rejected GITHUB_TOKEN (401: Bad credentials), and the request without it failed too (401: Bad credentials); replace or unset GITHUB_TOKEN, or pin VERSION=<tag>`
+- `GitHub refused GITHUB_TOKEN access to Agent-Field/codeaf (403: Resource not accessible by personal access token), and the request without it failed too (403: Resource not accessible by personal access token); check what GITHUB_TOKEN may read, or pin VERSION=<tag>`
+
+A token GitHub refuses with 401, 403 or 429 is set aside for the rest of the run,
+and the same lookup is asked once without it. If that works, installation
+continues with a note: `GitHub refused GITHUB_TOKEN (its rate limit is used up until HH:MM ZONE); continuing without it`.
+Other token failures get no retry. `GITHUB_TOKEN` supplies the token when
+non-empty; otherwise `GH_TOKEN` does, and the message names `GH_TOKEN` instead.
+Downloads never carry the token.
+
+The reset time comes from GitHub's header in this machine's local time, with
+no zone suffix if the machine supplies none. Without a renderable reset, a
+numeric Retry-After header gives `for about a minute` or `for about M minutes`;
+with neither it says `for up to an hour`. A 403 without quota evidence means
+access was refused. A 404 can also mean a repository you cannot read. Some wget
+builds discard error bodies or headers, so a refusal can lack its message or
+quota details.
+
+Pinning a complete release tag bypasses the API lookup for any of these failures:
+`curl -fsSL https://agentfield.ai/get/codeaf | VERSION=<tag> bash`.
+
 ## What is devaf — dev build beside codeaf — side by side — two versions — install under a different file name — --name
 
 `devaf` is the file name for a codeaf dev-channel build, not another product.

internal/manual/chat_test.go

@@ -30,6 +30,12 @@ func TestTheChatManualAnswersTheQuestionsPeopleAsk(t *testing.T) {
 		question string
 		page     string
 	}{
+		// Installer refusals must reach the page that explains both API attempts.
+		{"installer says github api rate limit is used up", "running-from-the-terminal"},
+		{"install script says GitHub rejected GITHUB_TOKEN bad credentials", "running-from-the-terminal"},
+		{"curl install fails with 403 from github", "running-from-the-terminal"},
+		{"why did the installer continue without my GH_TOKEN", "running-from-the-terminal"},
+
 		// C12: Key troubleshooting must reach the self-contained restart section.
 		{"I changed or unset my API key in the shell but codeaf still uses the old one", "starting-codeaf"},
 		{"your key was not accepted for this model", "starting-codeaf"},