Distillation

Date: September 10, 2026

• 🔴 (12:02) User specified that installation detection must always check Homebrew first because stored install information may be stale; this rule appears in packages/cli/src/lib/upgrade.ts at line 454.
• 🟡 (12:02) packages/cli/src/lib/upgrade.ts documents that upgrade installation detection begins around line 443 and falls back to detectLegacyInstallationMethod() at line 468 after the Homebrew-first check.
• 🟡 (12:03) fetchLatestFromNpm() in packages/cli/src/lib/upgrade.ts requests ${NPM_REGISTRY_URL}/latest through fetchWithUpgradeError, sends Accept: application/json, and identifies the remote as "npm registry".
• 🟡 (12:03) When the npm registry response is not OK, fetchLatestFromNpm() throws new UpgradeError("network_error", \Failed to fetch from npm: ${response.status}`)`.
• 🟡 (12:03) fetchLatestFromNpm() parses the response with parseUpgradeJson(response, undefined, "npm registry returned invalid metadata").
• 🟡 (12:03) Source-aware version discovery can throw new UpgradeError("network_error", \No version found in ${source}`)` when fetched metadata contains no usable version.
• 🟡 (12:03) GitHub fetching can report UpgradeError message Failed to fetch from GitHub: HTTP ${response.status}.
• 🟡 (12:03) Full binary download constructs its URL with getBinaryDownloadUrl(version, source); the relevant source: UpgradeSource parameter defaults to PRIMARY_UPGRADE_SOURCE.