feat(media-use): resolve official brand logos via a four-tier cascade (#2061)

* feat(media-use): resolve official brand logos via a four-tier cascade Third-party brand logos (the meeting's 'credibility signals lost' gap) had no acquisition path: capture only grabs the product's own site assets, and HeyGen asset search returns generic look-alike icons for brand queries (0/3 in testing — an X-in-a-circle for LinkedIn). Workers could only fake a mark or drop it. New resolve type 'logo', four tiers verified by a 54-brand stress test (100% cascade hit across dev tools / big tech / non-tech / CN brands): - svgl — official full-color vector SVGs + wordmark variants (40/54 first-hits); search is substring-based, so entities pass through alias normalization (nextjs → 'next.js', aws → 'amazon web services') - simple-icons (pinned CDN build) — official monochrome glyphs; catches the long tail (nike, visa, toyota, wechat, bytedance) - github org avatar — known-org map only; a brand name is not a GitHub login, guessing risks same-named personal accounts - domain favicon (DuckDuckGo ip3) — small-raster last resort; sub-500B responses are DDG's placeholder and rejected; frozen with a low_res provenance flag (chip-size use only) logo joins the icon/image equivalence group (typesMatch) and the images/ subdir, so entity cache hits interop with figma-imported marks. A total miss falls through resolve's normal failure path — no special casing. HeyGen search stays the icon provider; it is deliberately absent from the logo cascade. Docs: media-use gap/types/providers tables + example; the five workflow banners now cover logos (catalog claim kept for media, 'from their official sources' added for logos); product-launch story-design and motion-graphics logo-reveal point at the new type; catalog surfaces (CLAUDE.md / README / docs) updated in lockstep. Verified: 19 unit tests + coverage row green; live smoke across all four tiers (linkedin→svgl, nike→simple-icons, heygen→github.avatar, amazon→favicon) plus a fabricated brand exiting 1 on the default miss path. oxlint + oxfmt clean. * test(media-use): sanction the four logo providers in the registry allowlist svgl / simple-icons / github.avatar / favicon.ddg join the sanctioned list — the logo cascade added in the previous commit. Full lib suite 95/95 green. * test(media-use): gate the logo cascade behavior in CI + single-fetch favicon tier Review follow-ups (miga-heygen, jrusso1020 on #2061): - Eight mocked-network tests pin what the manual 54-brand stress test only asserted: descriptor shape, alias retry (svgl non-array payload → next query, simple-icons 404 → next slug), network-error → null fallthrough, the sub-500B placeholder rejection, github's no-guessing (zero fetches for unmapped entities), and the real cascade order landing tier by tier under a mocked network. - faviconSearch now hands its verified bytes over as a local file, so the freeze step copies instead of re-downloading — one round-trip, and the size check is authoritative over what gets frozen. - The header's hit counts are labeled as a stress-test snapshot, not a live invariant. Full lib suite 103/103; live smoke re-verified (amazon → favicon.ddg, frozen .ico).
2026-09-06 17:46:03 +00:00 · 2026-07-08 23:58:41 +08:00
parent 6192ed4cbd
commit 4d3cdc3e4b
21 changed files with 434 additions and 43 deletions
@@ -38,7 +38,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
 - `/hyperframes-animation` — all animation knowledge: atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP default, plus Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).
 - `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion.
 - `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.
- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk.
+- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record; generate via TTS / music / image models when the catalog misses; transcribe, caption, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk.
 - `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering).
 - `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream.
 - `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.
@@ -82,12 +82,12 @@ Run `npx skills add heygen-com/hyperframes --full-depth` for the interactive pic
 Atomic capabilities the creation workflows compose against — pull one when you need that specific layer.

 | Skill                    | Covers                                                                                                                                                                                                                                                                                                    |
-| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `/hyperframes-core`      | The composition contract — `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, determinism rules.                                                                                                                                            |
 | `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).                                                                                                                                             |
 | `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion.                                                                                               |
 | `/hyperframes-creative`  | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.                                                                                                                                                |
-| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
+| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. |
 | `/hyperframes-cli`       | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`).                                                                                                                                    |
 | `/hyperframes-registry`  | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream.                                                                                                                                                       |
 | `/figma`                 | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition.                                                                          |
@@ -80,7 +80,7 @@ Atomic capabilities the creation workflows compose against — pull one when you
 | `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU).         |
 | `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. |
 | `/hyperframes-creative`  | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns.            |
-| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking.          |
+| `/media-use`             | The media OS — resolve any media need (BGM, SFX, image, icon, logo, voice) into a frozen local file + ledger record, generate via TTS/music/image models when the catalog misses, transcribe, caption, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking.          |
 | `/hyperframes-cli`       | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). |
 | `/hyperframes-registry`  | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream.                   |
 | `/figma`                 | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations (MCP) and shaders (MCP source / native export) into a composition. |
@@ -6,7 +6,7 @@
      "files": 144
    },
    "faceless-explainer": {
-      "hash": "80882d8135b2aeac",
+      "hash": "58b1901b8ef7a84e",
      "files": 18
    },
    "figma": {
@@ -14,11 +14,11 @@
      "files": 1
    },
    "general-video": {
-      "hash": "6cb3fbdf9b860ba6",
+      "hash": "a4d2b4ed6d8a0643",
      "files": 1
    },
    "hyperframes": {
-      "hash": "4e0795ead8c8bfa3",
+      "hash": "547fd3b432a028bb",
      "files": 1
    },
    "hyperframes-animation": {
@@ -46,11 +46,11 @@
      "files": 10
    },
    "media-use": {
-      "hash": "b982d0f7c710bf23",
-      "files": 101
+      "hash": "22d8da57c4af6ddd",
+      "files": 103
    },
    "motion-graphics": {
-      "hash": "f5a432862116b39a",
+      "hash": "7452272d8da8934d",
      "files": 23
    },
    "music-to-video": {
@@ -58,11 +58,11 @@
      "files": 132
    },
    "pr-to-video": {
-      "hash": "71dce61cff0233f2",
+      "hash": "30a91ac16fae4737",
      "files": 22
    },
    "product-launch-video": {
-      "hash": "ac4e1e4aa671fe27",
+      "hash": "8499a01e77b41c6c",
      "files": 20
    },
    "remotion-to-hyperframes": {
@@ -78,7 +78,7 @@
      "files": 27
    },
    "website-to-video": {
-      "hash": "d81ede8e9cabd09b",
+      "hash": "76c4bae653b29e2f",
      "files": 32
    }
  }
@@ -3,7 +3,7 @@ name: faceless-explainer
 description: "Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a product promo (/product-launch-video) or a site tour (/website-to-video). Unclear → /hyperframes."
 ---

-> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill.
+> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.

 # Faceless Explainer to HyperFrames

@@ -8,7 +8,7 @@ description: >
 metadata: { "tags": "orchestrator, general-video, fallback, freeform, composition-authoring" }
 ---

-> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill.
+> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.

 # general-video — general video workflow

@@ -31,7 +31,7 @@ Atomic capabilities you load **on demand** — not full workflows; they never ow
 | **Animate** — atomic motion, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU)                              | `/hyperframes-animation` |
 | **Author seek-safe keyframes** — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth, plus `hyperframes keyframes` diagnostics | `/hyperframes-keyframes` |
 | **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive                                                       | `/hyperframes-creative`  |
-| **Media** — resolve/generate BGM, SFX, image, icon, voice; TTS voiceover, transcription, background removal, captions; cross-project reuse                              | `/media-use`             |
+| **Media** — resolve/generate BGM, SFX, image, icon, brand logo, voice; TTS voiceover, transcription, background removal, captions; cross-project reuse                  | `/media-use`             |
 | **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor                                                                                      | `/hyperframes-cli`       |
 | **Install registry blocks / components** (`hyperframes add`)                                                                                                            | `/hyperframes-registry`  |
 | **Import Figma content** — assets, tokens, components, storyboards→reconstructed motion (REST/CLI); Motion (MCP), shaders (MCP source / native export)                  | `/figma`                 |
@@ -1,6 +1,6 @@
 ---
 name: media-use
-description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, or voice into a frozen local file + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Keeps search noise on disk, hands the agent a path. Use for any audio, image, icon, voiceover, caption, or media-asset need.
+description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, or voice into a frozen local file + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Keeps search noise on disk, hands the agent a path. Use for any audio, image, icon, voiceover, caption, or media-asset need.
 ---

 # media-use
@@ -14,6 +14,7 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e
 | HyperFrames gap                            | media-use owns it via                                                                                                                       |
 | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                          |
+| No third-party brand logos                 | `resolve --type logo` (svgl → simple-icons → GitHub org avatar → domain favicon)                                                            |
 | No voice / audio generation                | `resolve --type voice` + the audio engine (`audio/scripts/audio.mjs`)                                                                       |
 | Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                          |
 | No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                           |
@@ -26,7 +27,7 @@ HyperFrames owns media _playback_; media-use owns everything else. Each row is e

 ## When to use

-Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, or voice. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first, freezes the best match locally, registers it in a manifest, and hands the agent one line; all search noise stays on disk.
+Call `resolve` whenever a composition needs media: background music, sound effects, images, icons, brand logos, or voice. For voiceover / TTS, music, SFX, and caption timing, use the **audio engine** (below); background removal is delegated to the `hyperframes` CLI; transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`). For cutting / reframing / transforming existing media, see `references/operations.md`. media-use searches the HeyGen catalog first, freezes the best match locally, registers it in a manifest, and hands the agent one line; all search noise stays on disk.

 ## Resolve

@@ -39,11 +40,12 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 ### Types

 | Type    | What it finds        | Provider                                                 |
-| ------- | ------------------- | ---------------------------------------- |
+| ------- | -------------------- | -------------------------------------------------------- |
 | `bgm`   | Background music     | HeyGen audio catalog (10k+ tracks)                       |
 | `sfx`   | Sound effects        | Bundled 19-file library + HeyGen catalog                 |
 | `image` | Photos, backgrounds  | HeyGen asset search (75k+ vectors)                       |
-| `icon`  | Icons, logos        | HeyGen asset search (type=icon)          |
+| `icon`  | Icons, symbols       | HeyGen asset search (type=icon)                          |
+| `logo`  | Official brand marks | svgl → simple-icons → GitHub org avatar → domain favicon |
 | `voice` | TTS voiceover        | Local Kokoro (free); HeyGen TTS upsell                   |

 ### Examples
@@ -64,6 +66,10 @@ node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech backgr
 # Icon
 node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
 # → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
+
+# Brand logo (official mark — never redrawn by hand)
+node <SKILL_DIR>/scripts/resolve.mjs --type logo --entity linkedin --intent "LinkedIn logo" --project .
+# → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)
 ```

 ### Flags
@@ -117,6 +123,7 @@ ladder, `describeModelLadder`); the agent can see the ladder and override.
 | image         | heygen search, then local mflux (best FLUX for your RAM), then codex `image_gen` upsell |
 | voice         | local **Kokoro** (free, on-device), then **heygen tts** paid upsell                     |
 | icon          | heygen asset search                                                                     |
+| logo          | svgl, then simple-icons, then GitHub org avatar, then domain favicon (all free)         |
 | video (local) | local LTX (`videogen` ladder); `heygen video create` avatar upsell                      |

 Local Kokoro (voice), mflux (image), and LTX (video) run on-device (free,
@@ -18,6 +18,11 @@ test("weakness: audio-only → media-use resolves image + icon", () => {
  }
 });

+test("weakness: no third-party brand logos → media-use resolves logo", () => {
+  assert.ok(listTypes().includes("logo"), "logo type missing");
+  assert.ok(getProviders("logo").length >= 4, "logo cascade incomplete");
+});
+
 test("weakness: no voice/audio gen → media-use exposes voice + the audio engine", () => {
  assert.ok(listTypes().includes("voice"), "voice type missing");
  assert.ok(getProviders("voice").length > 0, "no enabled voice provider (Bin approved)");
@@ -0,0 +1,222 @@
+// Official brand marks — the `logo` type's provider tiers, tried in registry
+// order. Every tier was verified against a 54-brand stress test (2026-07,
+// 100% cascade hit). Hit counts below are a snapshot of that run — they
+// drift as the alias/org maps grow; re-run the stress test to refresh them.
+//
+//   1. svgl          — official full-color vector SVGs (+ wordmark variants);
+//                      40/54 first-hits. Search is substring-based, so
+//                      entities go through alias normalization first
+//                      ("nextjs" never matches "Next.js" raw).
+//   2. simple-icons  — monochrome official glyphs; caught the long tail the
+//                      others miss (nike, visa, toyota, wechat, bytedance).
+//                      Pinned CDN build for determinism.
+//   3. github avatar — the org's official logo for brands with a GitHub
+//                      presence. Known orgs only: guessing a login risks a
+//                      same-named personal account.
+//   4. domain favicon — small-raster last resort (DuckDuckGo ip3). Responses
+//                      under ~500B are DDG's globe placeholder, not a hit.
+//
+// HeyGen asset search is deliberately absent: for brand queries it returns
+// generic look-alike icons (0/3 in testing) — worse than a miss. A total miss
+// falls through to resolve's normal failure path (`no provider could resolve
+// logo`, exit 1).
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const SVGL_API = "https://api.svgl.app";
+const SIMPLE_ICONS_CDN = "https://cdn.jsdelivr.net/npm/simple-icons@16.25.0/icons";
+const FAVICON_MIN_BYTES = 500;
+
+// svgl search queries per entity, tried in order after the raw entity.
+const SVGL_ALIASES = {
+  nextjs: ["next.js", "next"],
+  aws: ["amazon web services"],
+  huggingface: ["hugging face"],
+  cocacola: ["coca-cola"],
+  mcdonalds: ["mcdonald's"],
+};
+
+// simple-icons slugs that differ from the normalized entity.
+const SIMPLE_ICON_SLUGS = {
+  nextjs: "nextdotjs",
+  aws: "amazonwebservices",
+};
+
+// Known GitHub orgs. Only mapped entities resolve at this tier — a brand name
+// is NOT a GitHub login, and guessing hits same-named personal accounts.
+const GITHUB_ORGS = {
+  slack: "slackhq",
+  meta: "facebook",
+  google: "google",
+  microsoft: "microsoft",
+  aws: "aws",
+  vercel: "vercel",
+  nextjs: "vercel",
+  alibaba: "alibaba",
+  heygen: "heygen-com",
+};
+
+// Favicon domains that aren't `<entity>.com`.
+const FAVICON_DOMAINS = {
+  cocacola: "coca-cola.com",
+  aws: "aws.amazon.com",
+  nextjs: "nextjs.org",
+};
+
+const norm = (s) =>
+  String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+
+/** The brand entity for a query: --entity wins; else the intent minus filler. */
+export function entityFrom(intent, entity) {
+  if (entity) return entity.toLowerCase().trim();
+  return String(intent)
+    .toLowerCase()
+    .replace(/\b(logo|logos|icon|brand|official|mark)\b/g, "")
+    .trim()
+    .replace(/\s+/g, " ");
+}
+
+/** Exact match after stripping case/spacing/punctuation — "Next.js" ≡ "nextjs". */
+export function titleMatches(title, entity) {
+  return norm(title) === norm(entity);
+}
+
+export function svglQueriesFor(entity) {
+  return [entity, ...(SVGL_ALIASES[norm(entity)] || [])];
+}
+
+export function simpleIconSlugsFor(entity) {
+  const slugs = [norm(entity)];
+  const alias = SIMPLE_ICON_SLUGS[norm(entity)];
+  if (alias) slugs.push(alias);
+  return slugs;
+}
+
+export function githubOrgFor(entity) {
+  return GITHUB_ORGS[norm(entity)] || null;
+}
+
+export function faviconDomainFor(entity) {
+  return FAVICON_DOMAINS[norm(entity)] || `${norm(entity)}.com`;
+}
+
+async function fetchJson(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+  if (!res.ok) return null;
+  return res.json();
+}
+
+async function urlExists(url) {
+  const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(10_000) });
+  return res.ok;
+}
+
+export async function svglSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  for (const q of svglQueriesFor(entity)) {
+    let items;
+    try {
+      items = await fetchJson(`${SVGL_API}?search=${encodeURIComponent(q)}`);
+    } catch {
+      return null; // network down — let the next tier try its own host
+    }
+    if (!Array.isArray(items)) continue;
+    const hit = items.find((it) => titleMatches(it.title, q) || titleMatches(it.title, entity));
+    if (!hit) continue;
+    const route = typeof hit.route === "string" ? hit.route : hit.route?.light;
+    if (!route) continue;
+    return {
+      url: route,
+      ext: ".svg",
+      source: "search",
+      metadata: {
+        description: `${hit.title} logo (official mark)`,
+        provider: "svgl",
+        provenance: { entity, query: q, route, wordmark: Boolean(hit.wordmark) },
+      },
+    };
+  }
+  return null;
+}
+
+export async function simpleIconsSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  for (const slug of simpleIconSlugsFor(entity)) {
+    const url = `${SIMPLE_ICONS_CDN}/${slug}.svg`;
+    let ok;
+    try {
+      ok = await urlExists(url);
+    } catch {
+      return null;
+    }
+    if (!ok) continue;
+    return {
+      url,
+      ext: ".svg",
+      source: "search",
+      metadata: {
+        description: `${entity} logo (official monochrome glyph)`,
+        provider: "simple-icons",
+        provenance: { entity, slug, pinned: "simple-icons@16.25.0" },
+      },
+    };
+  }
+  return null;
+}
+
+export async function githubAvatarSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  const org = githubOrgFor(entity);
+  if (!org) return null;
+  const url = `https://github.com/${org}.png?size=460`;
+  try {
+    if (!(await urlExists(url))) return null;
+  } catch {
+    return null;
+  }
+  return {
+    url,
+    ext: ".png",
+    source: "search",
+    metadata: {
+      description: `${entity} logo (GitHub org avatar)`,
+      provider: "github.avatar",
+      provenance: { entity, org },
+    },
+  };
+}
+
+export async function faviconSearch(intent, ctx = {}) {
+  const entity = entityFrom(intent, ctx.entity);
+  const domain = faviconDomainFor(entity);
+  const url = `https://icons.duckduckgo.com/ip3/${domain}.ico`;
+  let body;
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+    if (!res.ok) return null;
+    body = Buffer.from(await res.arrayBuffer());
+  } catch {
+    return null;
+  }
+  if (body.byteLength < FAVICON_MIN_BYTES) return null; // DDG placeholder, not a logo
+  // Hand the verified bytes over as a local file: the freeze step copies it
+  // instead of re-downloading, so the size check is authoritative over what
+  // gets frozen and the favicon tier costs one network round-trip, not two.
+  const bytes = body.byteLength;
+  const tmp = join(mkdtempSync(join(tmpdir(), "media-use-logo-")), `${domain}.ico`);
+  writeFileSync(tmp, body);
+  return {
+    localPath: tmp,
+    ext: ".ico",
+    source: "search",
+    metadata: {
+      description: `${entity} favicon (small raster — chip-size use only)`,
+      provider: "favicon.ddg",
+      provenance: { entity, domain, bytes, low_res: true },
+    },
+  };
+}
@@ -0,0 +1,137 @@
+import test from "node:test";
+import assert from "node:assert";
+import { readFileSync } from "node:fs";
+import {
+  entityFrom,
+  titleMatches,
+  svglQueriesFor,
+  simpleIconSlugsFor,
+  githubOrgFor,
+  faviconDomainFor,
+  svglSearch,
+  simpleIconsSearch,
+  githubAvatarSearch,
+  faviconSearch,
+} from "./logo-provider.mjs";
+import { getProviders, runProviders } from "./registry.mjs";
+
+test("entityFrom strips filler words from the intent; --entity wins", () => {
+  assert.equal(entityFrom("LinkedIn logo"), "linkedin");
+  assert.equal(entityFrom("official Slack brand mark"), "slack");
+  assert.equal(entityFrom("anything", "Notion"), "notion");
+});
+
+test("titleMatches ignores case, spacing, punctuation — and rejects lookalikes", () => {
+  assert.ok(titleMatches("Next.js", "nextjs"));
+  assert.ok(titleMatches("Coca-Cola", "coca cola"));
+  assert.ok(!titleMatches("Slackware", "slack"));
+});
+
+test("svgl queries include the alias forms the raw entity can't match", () => {
+  assert.ok(svglQueriesFor("nextjs").includes("next.js"));
+  assert.ok(svglQueriesFor("aws").includes("amazon web services"));
+  assert.deepEqual(svglQueriesFor("figma"), ["figma"]);
+});
+
+test("simple-icons slugs cover the renamed entries", () => {
+  assert.ok(simpleIconSlugsFor("nextjs").includes("nextdotjs"));
+  assert.ok(simpleIconSlugsFor("aws").includes("amazonwebservices"));
+  assert.deepEqual(simpleIconSlugsFor("nike"), ["nike"]);
+});
+
+test("github avatar tier never guesses an org", () => {
+  assert.equal(githubOrgFor("slack"), "slackhq");
+  assert.equal(githubOrgFor("heygen"), "heygen-com");
+  assert.equal(githubOrgFor("some-random-startup"), null);
+});
+
+test("favicon domain defaults to <entity>.com with explicit overrides", () => {
+  assert.equal(faviconDomainFor("cocacola"), "coca-cola.com");
+  assert.equal(faviconDomainFor("stripe"), "stripe.com");
+});
+
+// --- async tiers, network mocked -------------------------------------------
+// The 54-brand stress test is a manual snapshot; these pin the same behavior
+// as CI gates: descriptor shape, alias retry, error→null fallthrough, the
+// placeholder filter, and the real cascade order under a mocked network.
+
+const json = (data) => new Response(JSON.stringify(data), { status: 200 });
+const status = (code) => new Response(null, { status: code });
+const bin = (n) => new Response(new Uint8Array(n), { status: 200 });
+
+test("svglSearch returns the descriptor shape on an exact title hit", async (t) => {
+  t.mock.method(globalThis, "fetch", async () =>
+    json([{ title: "Figma", route: "https://svgl.app/library/figma.svg" }]),
+  );
+  const res = await svglSearch("Figma logo", {});
+  assert.equal(res.url, "https://svgl.app/library/figma.svg");
+  assert.equal(res.ext, ".svg");
+  assert.equal(res.metadata.provider, "svgl");
+});
+
+test("svglSearch skips a non-array payload and retries with the alias query", async (t) => {
+  const seen = [];
+  t.mock.method(globalThis, "fetch", async (url) => {
+    seen.push(decodeURIComponent(String(url)));
+    return seen.length === 1
+      ? json({ error: "unexpected shape" })
+      : json([{ title: "Next.js", route: "https://svgl.app/library/nextjs.svg" }]);
+  });
+  const res = await svglSearch("nextjs logo", {});
+  assert.equal(res.metadata.provenance.query, "next.js", "hit came from the alias query");
+  assert.ok(seen.length >= 2, "raw query then alias");
+});
+
+test("svglSearch returns null when the network is down — the cascade falls through", async (t) => {
+  t.mock.method(globalThis, "fetch", async () => {
+    throw new Error("network down");
+  });
+  assert.equal(await svglSearch("figma logo", {}), null);
+});
+
+test("simpleIconsSearch falls to the next slug on a 404", async (t) => {
+  const seen = [];
+  t.mock.method(globalThis, "fetch", async (url) => {
+    seen.push(String(url));
+    return String(url).includes("amazonwebservices") ? status(200) : status(404);
+  });
+  const res = await simpleIconsSearch("aws logo", {});
+  assert.ok(res.url.endsWith("amazonwebservices.svg"));
+  assert.equal(seen.length, 2, "plain slug 404s first, alias slug hits");
+});
+
+test("faviconSearch rejects DDG's sub-500B placeholder with null", async (t) => {
+  t.mock.method(globalThis, "fetch", async () => bin(120));
+  assert.equal(await faviconSearch("someco logo", {}), null);
+});
+
+test("faviconSearch hands verified bytes over as a local file — one fetch, no re-download", async (t) => {
+  const fetchMock = t.mock.method(globalThis, "fetch", async () => bin(600));
+  const res = await faviconSearch("someco logo", {});
+  assert.ok(res.localPath, "returns a localPath, not a url");
+  assert.equal(readFileSync(res.localPath).byteLength, 600, "frozen bytes are the verified bytes");
+  assert.equal(fetchMock.mock.callCount(), 1, "single network round-trip");
+  assert.equal(res.metadata.provenance.low_res, true);
+});
+
+test("githubAvatarSearch never touches the network for an unmapped entity", async (t) => {
+  const fetchMock = t.mock.method(globalThis, "fetch", async () => status(200));
+  assert.equal(await githubAvatarSearch("some-random-startup logo", {}), null);
+  assert.equal(fetchMock.mock.callCount(), 0);
+});
+
+test("the real logo cascade falls through tier by tier to the first hit", async (t) => {
+  t.mock.method(globalThis, "fetch", async (url) => {
+    const u = String(url);
+    if (u.includes("api.svgl.app")) return json([]); // tier 1: no hit
+    if (u.includes("jsdelivr")) return status(404); // tier 2: no such slug
+    // tier 3 (github) is never called: entity is unmapped
+    if (u.includes("duckduckgo")) return bin(600); // tier 4: real favicon
+    throw new Error(`unexpected fetch: ${u}`);
+  });
+  const res = await runProviders(getProviders("logo"), "search", "zzzbrand logo", {
+    entity: "zzzbrand",
+  });
+  assert.ok(res, "cascade must land on the favicon tier");
+  assert.equal(res.metadata.provider, "favicon.ddg");
+});
@@ -21,6 +21,7 @@ const TYPE_DIRS = {
  voice: "audio/voice",
  image: "images",
  icon: "images",
+  logo: "images",
  brand: "images",
  video: "video",
 };
@@ -37,10 +37,11 @@ export function tokenOverlap(a, b) {
  return n;
 }

-// icon and image are interchangeable: both live in images/, and figma-imported
-// brand marks are recorded as type image while agents ask for logos as icon.
+// icon, image, and logo are interchangeable: all live in images/, and
+// figma-imported brand marks are recorded as type image while agents ask for
+// logos as icon or logo.
 export function typesMatch(a, b) {
  if (a === b) return true;
-  const visual = new Set(["icon", "image"]);
+  const visual = new Set(["icon", "image", "logo"]);
  return visual.has(a) && visual.has(b);
 }
@@ -23,6 +23,12 @@ import { bgmProvider } from "./bgm-provider.mjs";
 import { sfxProvider } from "./sfx-provider.mjs";
 import { imageProvider, iconProvider } from "./image-provider.mjs";
 import { brandProvider } from "./brand-provider.mjs";
+import {
+  svglSearch,
+  simpleIconsSearch,
+  githubAvatarSearch,
+  faviconSearch,
+} from "./logo-provider.mjs";
 import { heygenTtsGenerate } from "./voice-provider.mjs";
 import { localTtsGenerate } from "./tts-local-provider.mjs";
 import { codexImageGenerate } from "./codex-provider.mjs";
@@ -50,6 +56,16 @@ const REGISTRY = {
    N("codex.image_gen", { generate: codexImageGenerate }),
  ],
  icon: [N("heygen.asset.search", { search: iconProvider.search })],
+  logo: [
+    // Official brand marks. Tiers verified by a 54-brand stress test (100%
+    // cascade hit); HeyGen asset search is deliberately absent — it returns
+    // generic look-alike icons for brand queries. All free, all network →
+    // --local-only leaves only the cache rungs.
+    N("svgl", { search: svglSearch }),
+    N("simple-icons", { search: simpleIconsSearch }),
+    N("github.avatar", { search: githubAvatarSearch }),
+    N("favicon.ddg", { search: faviconSearch }),
+  ],
  voice: [
    // Local Kokoro first (free, private, on-device via the hyperframes CLI, kept
    // under --local-only), then HeyGen TTS as the higher-quality paid upsell and
@@ -19,8 +19,9 @@ test("heygen provider is first for every type it serves", () => {
  }
 });

-test("sanctioned providers only: heygen, local mflux/kokoro, codex, design spec", () => {
-  const allowed = /^heygen|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$/;
+test("sanctioned providers only: heygen, local mflux/kokoro, codex, design spec, logo tiers", () => {
+  const allowed =
+    /^heygen|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$/;
  for (const t of listTypes()) {
    for (const p of getProviders(t)) {
      assert.ok(allowed.test(p.name), `${t} lists unsanctioned provider: ${p.name}`);
@@ -462,6 +462,7 @@ const DEFAULT_EXT = {
  voice: ".wav",
  image: ".jpg",
  icon: ".svg",
+  logo: ".svg",
  brand: ".png",
 };

@@ -1,6 +1,6 @@
 # logo-reveal — category module

-A **logo sting / brand lockup**. The logo is user-supplied (`asset_needs` = one logo `source`, not a search). ~3–5s. Often `export: alpha-overlay` (sting to drop on other footage).
+A **logo sting / brand lockup**. The logo is user-supplied, or resolved for a known brand (`resolve --type logo --entity <brand>`); `asset_needs` = one logo `source`. ~3–5s. Often `export: alpha-overlay` (sting to drop on other footage).

 ## Plan (Director)

@@ -3,7 +3,7 @@ name: pr-to-video
 description: "Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes."
 ---

-> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill.
+> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.

 # PR to HyperFrames

@@ -3,7 +3,7 @@ name: product-launch-video
 description: "Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Not a general site tour (/website-to-video). Unclear → /hyperframes."
 ---

-> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill.
+> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.

 # Product Launch to HyperFrames

@@ -309,7 +309,7 @@ Step 3 only TAGS the candidate id and writes the shaped VO. Step 4 (visual desig
 2. Use only filenames listed there; write as `assets/<basename>`.
 3. One line, candidates separated by semicolons, a short description after `—`.
 4. Prefer `[video]` assets when motion proves the product better than a still.
-5. Use content assets (UI, screenshots, product photos, charts, demos). Skip tiny icons, favicons, badges, decorative chrome, repeated logo variants — unless the beat needs them.
+5. Use content assets (UI, screenshots, product photos, charts, demos). Skip tiny icons, favicons, badges, decorative chrome, repeated logo variants — unless the beat needs them. Partner / third-party logos come from `/media-use` (`resolve --type logo --entity <brand>`) — never redrawn by hand.
 6. Pure-typography beats may use an empty asset list. Do not use nested lists.

 Example:
@@ -3,7 +3,7 @@ name: website-to-video
 description: "Capture a general website/URL and turn it into a video OF the site — tour, showcase, or social clip built from captured screenshots and the site's own brand assets. Use for portfolio / blog / docs / landing-page showcases. Not a product launch or promo, even from a URL (/product-launch-video). Unclear → /hyperframes."
 ---

-> **media-use**: Before sourcing audio/images, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog. Run `--adopt` first to register existing assets. See `/media-use` skill.
+> **media-use**: Before sourcing audio/images/logos, call `/media-use` to resolve BGM/SFX/images from the HeyGen catalog and brand logos from their official sources. Run `--adopt` first to register existing assets. See `/media-use` skill.

 # Website to HyperFrames