[kitlangton]

How it works

1. When discovery runs: Inline on first Project.resolve when project.icon_url is unset, and across unarchived projects during the hourly Project.sweep.
2. What it reads: opencode.json(c) / .opencode/opencode.json(c) icon first (https: URLs kept as-is; relative paths validated inside the project root), then a fixed priority list of well-known paths (Xcode .appiconset picking a 128–256 px entry, Icon Composer .icon front layer, assets/app-icon.*, build/icon.*, src-tauri/icons/icon.*, resources/icon.*, icons/icon.*, extension/icons/icon.*, web favicons/apple-touch-icon in public//app//src/app//site/public//root, and logo.*/icon.* in assets//public//root).
3. Where it is stored: Stores the project-relative path and 16-char content hash in the existing project.icon_url column (no database migration or schema change) and exposes /api/project/<id>/icon?v=<hash> on Project.Info.icon.url.
4. How it is served (GET /api/project/:projectID/icon): Resolves the stored relative path inside the project's canonical worktree (rejecting any path escaping it at the boundary), streams the image bytes with Content-Type, ETag: "<hash>", and Cache-Control (private, max-age=31536000, immutable when ?v= matches, 304 on If-None-Match), and returns 404 when the file is missing so ProjectAvatar falls back to the letter tile.
5. Freshness: Reading at request time means edits show up immediately; the hourly Project.sweep updates the v= hash if the file changed, or clears and rediscovers if the file was deleted.

Stack

1. PR A (fix(ui): show the OpenCode icon for the current project ID #57499): show the OpenCode icon for the current project ID (+9 / -4 code, +21 tests)
2. PR B (feat(core): discover project icons automatically #56698, this PR): store discovered icon location and serve via GET /api/project/:projectID/icon (+216 / -21 code, +190 / -1 tests, +42 / -4 generated client, 0 migrations)
3. PR C (feat(app): add detected icons picker in project settings #57500, draft): "Detected icons" picker in project settings

Proof

Dark	Light