diff --git a/src/servers/app-store/catalogue.ts b/src/servers/app-store/catalogue.ts
index ed2c6511..ddb3392c 100644
--- a/src/servers/app-store/catalogue.ts
+++ b/src/servers/app-store/catalogue.ts
@@ -53,7 +53,19 @@ export type UiManifest = {
   name: string;
   /** A lucide icon name, resolved at render. */
   icon?: string;
-  /** An image asset instead of a glyph, for a service with its own mark. */
+  /**
+   * An image asset instead of a glyph, for a service with its own mark. Real PNGs are coming, and this
+   * is the field they arrive in.
+   *
+   * `/slskd.png` works today because it sits in the platform's `public/`. A marketplace plugin cannot
+   * put a file there, so one thing has to be decided before third-party icons ship: whether the bytes
+   * are fetched from the marketplace (simple, but the dock loses its icons offline), served by us from
+   * the sidecar's own directory (works offline, needs a route and a cache header), or inlined as a data
+   * URI (no fetch, but every manifest carries it and it is unpleasant at 512px).
+   *
+   * Whichever wins, this stays a STRING the renderer resolves — never an import — for the same reason
+   * `icon` is a name: a manifest has to survive being JSON.
+   */
   image?: string;
   /** Tile colour. */
   color: string;