docs: document how to change the CLI icon

AGENTS.md

@@ -102,3 +102,7 @@ After updating `SKILL_CONTENT`:
 2. Run `tdc skill update claude-code` (and any other installed agents) to propagate changes to installed skill files
 
 A CI check (`npm run check:skill-sync`) runs on pull requests and will fail if `skills/comms-cli/SKILL.md` is out of sync with `content.ts`.
+
+## Changing the CLI icon
+
+Follow [docs/icon.md](docs/icon.md). Never rename or delete files in `icons/`: OAuth clients registered by released versions keep the `logo_uri` they sent, so every path a release has used must keep serving the icon.

CODEBASE.md

@@ -23,7 +23,7 @@ come from `@doist/cli-core`.
 ├─ scripts/               # sync-skill.js, check-skill-sync.js, postinstall.js
 ├─ dist/                  # Build output (tsc). Never edit.
 ├─ skills/comms-cli/      # Generated SKILL.md (from src/lib/skills/content.ts)
-├─ docs/                  # SPEC.md, comms-search.md (design notes)
+├─ docs/                  # SPEC.md, comms-search.md (design notes), icon.md (changing the icon)
 ├─ icons/                 # OAuth callback / skill logo assets
 ├─ .github/workflows/     # test, lint, release, check-skill-sync,
 │                         # check-semantic-pull-request, issue-automation,

docs/icon.md

@@ -0,0 +1,35 @@
+# Changing the CLI icon
+
+The icon shows in four places.
+
+| Where                                   | What it shows                                                                    |
+| --------------------------------------- | -------------------------------------------------------------------------------- |
+| OAuth consent screen (`tdc auth login`) | The URL in `LOGO_URI` (`src/lib/auth-constants.ts`), or an older one (see below) |
+| Sign-in result pages in the browser     | The URL in `LOGO_URI`                                                            |
+| README (GitHub and npm)                 | `icons/comms-cli.png`                                                            |
+| Comms web, Settings → Integrations      | Its own copies in `Doist/comms-web`                                              |
+
+## 1. Export the artwork
+
+The source is the `Size=72, Style=Color` variant of [Service / Comms CLI](https://www.figma.com/design/xo9yAsH8PQUpi0eTJh9pmR/?node-id=15223-1259) in Product Library – Global.
+
+- Export a **512×512 PNG**.
+- Don't export SVG. The artwork uses blend modes that SVG export drops, so the tile renders pale.
+
+## 2. Replace the repo file
+
+Overwrite `icons/comms-cli.png` with the new PNG, keeping the name. It's the `LOGO_URI` (consent screen and sign-in result pages) and the README header.
+
+**Never rename or delete it.** `tdc` registers an OAuth client the first time it signs in (one per callback port) and reuses it. Todoist stores the client's `logo_uri` at registration and never refreshes it, so every URL a released version has sent must keep serving the icon. If you ever change `LOGO_URI`, keep the old file in place too. (1.0.0 to 1.4.0 used a commit-pinned URL that no longer resolves, and 3.6.1 to 3.6.4 registered `icons/comms-cli_512px.png`, which has since been removed, so clients first registered by those versions show Todoist's fallback icon.)
+
+The consent screen picks up a replaced file as soon as it's on `main` (allow about ten minutes: GitHub's raw files and Todoist's image proxy each cache for five). No release is needed unless `LOGO_URI` itself changes.
+
+## 3. Update Comms web
+
+`Doist/comms-web` keeps its own copies for the CLI card in Settings → Integrations:
+
+- `src/settings/integrations/comms-cli-icon.png` (32×32)
+- `src/settings/integrations/comms-cli-icon@2x.png` (64×64)
+- `src/settings/integrations/comms-cli-icon@3x.png` (96×96)
+
+Resize the 512px PNG to those sizes and open a PR there.

src/lib/auth-constants.ts

@@ -4,7 +4,8 @@ export const SECURE_STORE_SERVICE = 'comms-cli'
 /**
  * Icon sent as `logo_uri` when registering an OAuth client, and shown on the
  * local auth result pages. Todoist keeps the URL each client registered with,
- * so never rename or delete the file behind it. (3.6.1 to 3.6.3 registered
+ * so never rename or delete the file behind it. (1.0.0 to 1.4.0 used a
+ * commit-pinned URL that no longer resolves, and 3.6.1 to 3.6.4 registered
  * `icons/comms-cli_512px.png`, since removed, so those clients show Todoist's
  * fallback icon.)
  */