Sync Harness Icons
Every harness AgentsView can read gets a monochrome brand mark in two places:
the "Every agent" chip grid in docs/website/index.html, and the HarnessIcon
component in the kit-ui repository that Forge draws in its launch and terminal
surfaces. New parsers land without either, so a person runs this skill after a
batch of provider additions to bring both back in sync, then moves the Forge pin
so Forge picks the marks up. Do the steps in order; each pull request references
the one before it.
1. Audit
From the AgentsView repository root, with a kit-ui checkout that is on main
and up to date (git -C <kit-ui> status -sb shows ## main...origin/main):
python3 .agents/skills/sync-harness-icons/audit.py --kit-ui <kit-ui checkout>
The script reads the provider headings in
docs/internal/session-format-sources.md, so a new parser is invisible to the
audit until its heading and evidence entry exist there; confirm that first. It
reports:
- chips that still use a two-letter text tag. Each is a sourcing target for step
2; a vendor may have published a logo since the last run. When a sourcing pass
finds nothing, add the chip to
TEXT_TAG_ACCEPTED in the script with the
month and what was searched, so later runs skip it until someone has a new
lead.
- providers with no landing-grid chip, matched by normalized name against the
chip list. Judge each line. Importers and IDE/CLI variants of a brand already
on the grid stay off it; add such keys to
INTENTIONALLY_UNLISTED in the
script with the reason. A provider the matcher missed because its chip has a
different display name (codebuddy is the CodeBuddy CN chip) goes in
CHIP_NAMES. Everything else needs a mark.
- sprite symbols with no kit-ui id, which is the kit-ui gap list.
- chips whose name appears in no kit-ui
agents list. A chip listed in
TEXT_TAG_ACCEPTED is expected here and needs no action.
2. Source a mark for each missing harness
Dispatch one subagent per three or four harnesses with this brief, writing to a
scratch directory outside any repository:
- Find the vendor repository from the provider's entry in
docs/internal/session-format-sources.md; if the entry has no repository,
search the product site. Look for a first-party vector, in roughly this order:
- The repository:
assets/, docs/, .github/assets/, the README header
image, and web packages such as packages/web/public/.
- The product site: follow the page's
<link rel="icon"> and the header
<img src> targets rather than guessing /favicon.svg. Products sold in
China often have a separate .cn site with the current mark.
- A JetBrains plugin:
https://plugins.jetbrains.com/api/plugins/<id> returns
an icon path such as /files/<id>/<update>/icon/default.svg (fetch with
curl -L). The /api/icon?pluginId= endpoint returns 403.
- A VS Code extension: find the publisher and name with the Marketplace
extensionquery API, download
https://marketplace.visualstudio.com/_apis/public/gallery/publishers/<publisher>/vsextensions/<name>/latest/vspackage,
and open the .vsix with Python's zipfile if unzip is missing. Check
both the extension icon and the webview assets; they can show different
generations of the mark. Prefer the one the product site shows.
- Fallbacks in order: the lobehub monochrome redraw
(
npm pack @lobehub/icons-static-svg, file icons/<name>.svg; its -color
variants can be older designs) when a side-by-side render matches the official
mark's silhouette; the publisher's mark when the product has no distinct logo
(this is how Codex draws OpenAI and QClaw draws Tencent); potrace of an
official raster of at least 512 px, stated as such. Never hand-draw.
- Normalize: parse the source, compute the mark's bounding box, then scale and
translate it into a 20-unit box centred at (12,12) on
viewBox="0 0 24 24",
either by rewriting the path coordinates or by wrapping in <g transform="…">
(the sprite already contains both styles). Use fill-rule="evenodd" for
holes. A mark drawn as a light glyph on a coloured tile or disc becomes one
shape with the glyph cut out as a hole; when the glyph overflows the tile,
clip it with an exact boolean operation (for example skia-pathops in a
scratch venv), never by hand. Strip fill and stroke colours, gradients, masks,
clip paths, filters, and <style>. Valid XML, under 4 KB.
- Render at 64 px and 16 px as a light glyph on a dark background (add a
temporary
fill="#fff" for the preview only) and view the PNGs. Use
rsvg-convert, or ImageMagick when it is missing:
magick -background '#1a1a1a' -density 600 in.svg -resize 64x64 out.png.
- Report a table: agent, slug, source URL, licence, confidence, and anything
that has no usable vector, plus the places searched. A harness with no
findable logo keeps a two-letter text tag and goes in
TEXT_TAG_ACCEPTED.
Look at every rendered PNG yourself before using a mark. Same-hue accent pixels
and thin decorative rings vanish in monochrome; drop them rather than keep an
unreadable silhouette.
3. Add to the landing grid
Minify: npx --yes svgo@3 --multipass -q -o <out> -f <scratch>.
Wrap each file's inner markup as
<symbol id="i-<slug>" viewBox="0 0 24 24">…</symbol> and insert it after
the last existing <symbol> line. A publisher fallback reuses the existing
symbol id instead of adding one. Products of one brand share a symbol (Augure
Code and Augure Desktop both use i-augure).
To replace a text tag, swap the chip's glyph text for the <svg> below and
keep the chip where it is unless it sits out of alphabetical order after
Zencoder.
Add a chip. The grid opens with a fixed run of chips that ends at Zencoder;
the chips after Zencoder are roughly alphabetical, so place the new chip by
name among them. Use the display name from the README session discovery
table:
<a class="agent-chip" href="/docs/configuration/#session-discovery"><span class="agent-chip-glyph"><svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#i-<slug>"/></svg></span><span class="agent-chip-name"><Name></span></a>
Keep xlink:href; the built-site check requires it.
Verify: make docs-check, then
(cd docs/website && python3 -m http.server 8766 --bind 127.0.0.1 &)
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new --hide-scrollbars \
--window-size=1280,2000 --screenshot=/tmp/grid.png http://127.0.0.1:8766/index.html
On Linux, use Playwright's Chromium
(~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome) with the same
flags plus --no-sandbox.
Crop to the grid and show the person the image.
Rerun the audit; the grid and text-tag lists must be empty. Commit and open
the pull request with kenn:commit-push-pr. The PR body lists where each
mark came from and its licence, since the diff cannot show that.
4. Mirror into kit-ui
Work in a fresh worktree from kit-ui main. One commit touches:
| File |
Change |
src/lib/assets/harness-icons/<slug>.svg |
The minified file with the same path data as the sprite; bun run fmt settles tag spacing |
src/lib/components/harness-icon.ts |
Append to the HarnessIconId union and HARNESS_ICONS, after the last entry: { id: "<slug>", label: "<Brand>", agents: ["<chip name>"] } |
src/lib/components/HarnessIcon.svelte |
import <slug> from "../assets/harness-icons/<slug>.svg?raw" and add <slug>, to GLYPHS |
docs/components/harness-icon.md |
A row in the Harnesses table: id in backticks, brand, then the agent names comma separated, in the same three columns as the rows above it |
tests/browser/harness-icon.spec.ts |
Raise both toHaveCount values by the number added |
Run bun install, bun run fmt, bun run generate:types (kit-ui commits the
generated types/ declarations, and bun run check:types fails until they
match), bun run check, bun run lint, bun run test:browser, and
bun run build. Use the brand as the id and label, not the product: StepCode
draws stepfun, as QClaw draws tencent. Screenshot the HarnessIcon page of
the demo gallery (bun run dev -- --port <n>, then /#harness-icon with the
same headless Chrome command). Open the PR; its body references the AgentsView
PR for provenance.
5. Move the Forge pin
After the kit-ui PR merges, get the merge commit:
gh pr view <n> --repo kenn-io/kit-ui --json mergeCommit -q .mergeCommit.oid
In a worktree from Forge main: replace the commit hash in the
@kenn-io/kit-ui entry of frontend/package.json with that hash, run
bun install, confirm the new SVG files exist under
frontend/node_modules/@kenn-io/kit-ui/src/lib/assets/harness-icons/, run
make frontend-check-core-no-deps, then from frontend/ run
node ../node_modules/vite-plus/bin/vp test run --project unit-node --project unit-jsdom agentHarness,
and open a PR that commits frontend/package.json and the repository-root
bun.lock. Forge matches launch target keys against the registry's agents
names, so a new harness whose key is its name needs no Forge code change. Never
pin to the PR head; it is deleted after the squash merge.
AgentsView's own frontend does not import HarnessIcon; its kit-ui pin needs no
bump for icon work.
Common mistakes
- Trusting the audit's list without reading it: it matches by name and cannot
know a new key is a variant of an existing brand.
- A mark that renders black on a dark preview: the file still carries a fill
colour, or the preview omitted one.
- Skipping the private-terms scrub before push. SVG path data trips the
IP-address heuristic, which is a false positive, but a private repository name
in a comment is not.
1---2name: sync-harness-icons3description: Use when a person asks to audit or update the harness marks after new agent parsers were added, when the landing-page agent grid or the kit-ui HarnessIcon set is missing a newly supported agent, or when someone invokes /sync-harness-icons. Human-invoked only.4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/tuyv/sync-harness-icons7---89# Sync Harness Icons1011Every harness AgentsView can read gets a monochrome brand mark in two places:12the "Every agent" chip grid in `docs/website/index.html`, and the `HarnessIcon`13component in the kit-ui repository that Forge draws in its launch and terminal14surfaces. New parsers land without either, so a person runs this skill after a15batch of provider additions to bring both back in sync, then moves the Forge pin16so Forge picks the marks up. Do the steps in order; each pull request references17the one before it.1819## 1. Audit2021From the AgentsView repository root, with a kit-ui checkout that is on `main`22and up to date (`git -C <kit-ui> status -sb` shows `## main...origin/main`):2324```bash25python3 .agents/skills/sync-harness-icons/audit.py --kit-ui <kit-ui checkout>26```2728The script reads the provider headings in29`docs/internal/session-format-sources.md`, so a new parser is invisible to the30audit until its heading and evidence entry exist there; confirm that first. It31reports:3233- chips that still use a two-letter text tag. Each is a sourcing target for step34 2; a vendor may have published a logo since the last run. When a sourcing pass35 finds nothing, add the chip to `TEXT_TAG_ACCEPTED` in the script with the36 month and what was searched, so later runs skip it until someone has a new37 lead.38- providers with no landing-grid chip, matched by normalized name against the39 chip list. Judge each line. Importers and IDE/CLI variants of a brand already40 on the grid stay off it; add such keys to `INTENTIONALLY_UNLISTED` in the41 script with the reason. A provider the matcher missed because its chip has a42 different display name (`codebuddy` is the CodeBuddy CN chip) goes in43 `CHIP_NAMES`. Everything else needs a mark.44- sprite symbols with no kit-ui id, which is the kit-ui gap list.45- chips whose name appears in no kit-ui `agents` list. A chip listed in46 `TEXT_TAG_ACCEPTED` is expected here and needs no action.4748## 2. Source a mark for each missing harness4950Dispatch one subagent per three or four harnesses with this brief, writing to a51scratch directory outside any repository:5253- Find the vendor repository from the provider's entry in54 `docs/internal/session-format-sources.md`; if the entry has no repository,55 search the product site. Look for a first-party vector, in roughly this order:56 - The repository: `assets/`, `docs/`, `.github/assets/`, the README header57 image, and web packages such as `packages/web/public/`.58 - The product site: follow the page's `<link rel="icon">` and the header59 `<img src>` targets rather than guessing `/favicon.svg`. Products sold in60 China often have a separate `.cn` site with the current mark.61 - A JetBrains plugin: `https://plugins.jetbrains.com/api/plugins/<id>` returns62 an `icon` path such as `/files/<id>/<update>/icon/default.svg` (fetch with63 `curl -L`). The `/api/icon?pluginId=` endpoint returns 403.64 - A VS Code extension: find the publisher and name with the Marketplace65 `extensionquery` API, download66 `https://marketplace.visualstudio.com/_apis/public/gallery/publishers/<publisher>/vsextensions/<name>/latest/vspackage`,67 and open the `.vsix` with Python's `zipfile` if `unzip` is missing. Check68 both the extension icon and the webview assets; they can show different69 generations of the mark. Prefer the one the product site shows.70- Fallbacks in order: the lobehub monochrome redraw71 (`npm pack @lobehub/icons-static-svg`, file `icons/<name>.svg`; its `-color`72 variants can be older designs) when a side-by-side render matches the official73 mark's silhouette; the publisher's mark when the product has no distinct logo74 (this is how Codex draws OpenAI and QClaw draws Tencent); potrace of an75 official raster of at least 512 px, stated as such. Never hand-draw.76- Normalize: parse the source, compute the mark's bounding box, then scale and77 translate it into a 20-unit box centred at (12,12) on `viewBox="0 0 24 24"`,78 either by rewriting the path coordinates or by wrapping in `<g transform="…">`79 (the sprite already contains both styles). Use `fill-rule="evenodd"` for80 holes. A mark drawn as a light glyph on a coloured tile or disc becomes one81 shape with the glyph cut out as a hole; when the glyph overflows the tile,82 clip it with an exact boolean operation (for example `skia-pathops` in a83 scratch venv), never by hand. Strip fill and stroke colours, gradients, masks,84 clip paths, filters, and `<style>`. Valid XML, under 4 KB.85- Render at 64 px and 16 px as a light glyph on a dark background (add a86 temporary `fill="#fff"` for the preview only) and view the PNGs. Use87 `rsvg-convert`, or ImageMagick when it is missing:88 `magick -background '#1a1a1a' -density 600 in.svg -resize 64x64 out.png`.89- Report a table: agent, slug, source URL, licence, confidence, and anything90 that has no usable vector, plus the places searched. A harness with no91 findable logo keeps a two-letter text tag and goes in `TEXT_TAG_ACCEPTED`.9293Look at every rendered PNG yourself before using a mark. Same-hue accent pixels94and thin decorative rings vanish in monochrome; drop them rather than keep an95unreadable silhouette.9697## 3. Add to the landing grid98991. Minify: `npx --yes svgo@3 --multipass -q -o <out> -f <scratch>`.1001011. Wrap each file's inner markup as102 `<symbol id="i-<slug>" viewBox="0 0 24 24">…</symbol>` and insert it after103 the last existing `<symbol>` line. A publisher fallback reuses the existing104 symbol id instead of adding one. Products of one brand share a symbol (Augure105 Code and Augure Desktop both use `i-augure`).1061071. To replace a text tag, swap the chip's glyph text for the `<svg>` below and108 keep the chip where it is unless it sits out of alphabetical order after109 Zencoder.1101111. Add a chip. The grid opens with a fixed run of chips that ends at Zencoder;112 the chips after Zencoder are roughly alphabetical, so place the new chip by113 name among them. Use the display name from the README session discovery114 table:115116 ```html117 <a class="agent-chip" href="/docs/configuration/#session-discovery"><span class="agent-chip-glyph"><svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#i-<slug>"/></svg></span><span class="agent-chip-name"><Name></span></a>118 ```119120 Keep `xlink:href`; the built-site check requires it.1211221. Verify: `make docs-check`, then123124 ```bash125 (cd docs/website && python3 -m http.server 8766 --bind 127.0.0.1 &)126 "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --headless=new --hide-scrollbars \127 --window-size=1280,2000 --screenshot=/tmp/grid.png http://127.0.0.1:8766/index.html128 ```129130 On Linux, use Playwright's Chromium131 (`~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome`) with the same132 flags plus `--no-sandbox`.133134 Crop to the grid and show the person the image.1351361. Rerun the audit; the grid and text-tag lists must be empty. Commit and open137 the pull request with `kenn:commit-push-pr`. The PR body lists where each138 mark came from and its licence, since the diff cannot show that.139140## 4. Mirror into kit-ui141142Work in a fresh worktree from kit-ui `main`. One commit touches:143144| File | Change |145| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |146| `src/lib/assets/harness-icons/<slug>.svg` | The minified file with the same path data as the sprite; `bun run fmt` settles tag spacing |147| `src/lib/components/harness-icon.ts` | Append to the `HarnessIconId` union and `HARNESS_ICONS`, after the last entry: `{ id: "<slug>", label: "<Brand>", agents: ["<chip name>"] }` |148| `src/lib/components/HarnessIcon.svelte` | `import <slug> from "../assets/harness-icons/<slug>.svg?raw"` and add `<slug>,` to `GLYPHS` |149| `docs/components/harness-icon.md` | A row in the Harnesses table: id in backticks, brand, then the agent names comma separated, in the same three columns as the rows above it |150| `tests/browser/harness-icon.spec.ts` | Raise both `toHaveCount` values by the number added |151152Run `bun install`, `bun run fmt`, `bun run generate:types` (kit-ui commits the153generated `types/` declarations, and `bun run check:types` fails until they154match), `bun run check`, `bun run lint`, `bun run test:browser`, and155`bun run build`. Use the brand as the id and label, not the product: StepCode156draws `stepfun`, as QClaw draws `tencent`. Screenshot the HarnessIcon page of157the demo gallery (`bun run dev -- --port <n>`, then `/#harness-icon` with the158same headless Chrome command). Open the PR; its body references the AgentsView159PR for provenance.160161## 5. Move the Forge pin162163After the kit-ui PR merges, get the merge commit:164165```bash166gh pr view <n> --repo kenn-io/kit-ui --json mergeCommit -q .mergeCommit.oid167```168169In a worktree from Forge `main`: replace the commit hash in the170`@kenn-io/kit-ui` entry of `frontend/package.json` with that hash, run171`bun install`, confirm the new SVG files exist under172`frontend/node_modules/@kenn-io/kit-ui/src/lib/assets/harness-icons/`, run173`make frontend-check-core-no-deps`, then from `frontend/` run174`node ../node_modules/vite-plus/bin/vp test run --project unit-node --project unit-jsdom agentHarness`,175and open a PR that commits `frontend/package.json` and the repository-root176`bun.lock`. Forge matches launch target keys against the registry's `agents`177names, so a new harness whose key is its name needs no Forge code change. Never178pin to the PR head; it is deleted after the squash merge.179180AgentsView's own frontend does not import `HarnessIcon`; its kit-ui pin needs no181bump for icon work.182183## Common mistakes184185- Trusting the audit's list without reading it: it matches by name and cannot186 know a new key is a variant of an existing brand.187- A mark that renders black on a dark preview: the file still carries a fill188 colour, or the preview omitted one.189- Skipping the private-terms scrub before push. SVG path data trips the190 IP-address heuristic, which is a false positive, but a private repository name191 in a comment is not.