Audit Icon Pipeline

Detect missing glyphs, icons, stale manifests → compare registries vs glyph mappings, icon dirs, manifests. Structured gap report → skills, agents, teams.

Use When

• After add new skills/agents/teams → icons needed?
• Pre-full pipeline render → identify missing
• After registry updates → manifests in sync
• Periodic health check of icon pipeline

In

• Optional: Entity type filter —

  skill

  ,

  agent

  ,

  team

  ,

  all

  (default:

  all

  )
• Optional: Palette (default:

  cyberpunk

  — reference)

Do

Step 1: Read Registries

Collect entity IDs from source-of-truth registries.

1. skills/_registry.yml

   → all skill IDs across all domains

2. agents/_registry.yml

   → all agent IDs

3. teams/_registry.yml

   → all team IDs
4. Record counts: total skills, agents, teams

→ 3 lists of entity IDs w/ counts matching

total_skills

,

total_agents

,

total_teams

.

If err: Registry file missing → report path + skip that type.

Step 2: Read Glyph Mappings

Collect mapped entity IDs from glyph mapping files.

1. viz/R/glyphs.R

   → all keys from

   SKILL_GLYPHS

   list

2. viz/R/agent_glyphs.R

   → all keys from

   AGENT_GLYPHS

   list

3. viz/R/team_glyphs.R

   → all keys from

   TEAM_GLYPHS

   list

→ 3 lists of mapped IDs.

If err: Glyph file missing → report + mark all entities of that type unmapped.

Step 3: Compute Missing Glyphs

Diff registry IDs vs mapped IDs.

1. Missing skill glyphs:

   registry_skill_ids - mapped_skill_ids

2. Missing agent glyphs:

   registry_agent_ids - mapped_agent_ids

3. Missing team glyphs:

   registry_team_ids - mapped_team_ids

→ Lists of entity IDs in registries w/o glyph fn mapped.

If err: Diff fails → verify ID formats match (underscores vs hyphens).

Step 4: Check Rendered Icons

Verify mapped glyphs have corresponding rendered icon files.

1. Per mapped skill ID → check

   viz/public/icons/<palette>/<domain>/<skillId>.webp

2. Per mapped agent ID → check

   viz/public/icons/<palette>/agents/<agentId>.webp

3. Per mapped team ID → check

   viz/public/icons/<palette>/teams/<teamId>.webp

4. HD variants in

   viz/public/icons-hd/

   same structure

→ Lists of entities w/ glyphs but missing rendered icons (standard/HD).

If err: Icon dir missing → pipeline not run → report all as missing.

Step 5: Check Manifest Freshness

Compare manifest counts vs registry counts.

1. viz/public/data/icon-manifest.json

   → count entries

2. viz/public/data/agent-icon-manifest.json

   → count entries

3. viz/public/data/team-icon-manifest.json

   → count entries
4. Compare vs registry totals

→ Manifest counts match registry counts. Discrepancy = stale.

If err: Manifest files missing → data pipeline must run first (

node build-data.js && node build-icon-manifest.js

).

Step 6: Detect Orphan Icons

Walk

viz/public/icons*/

→ flag WebP files whose

<palette>/<domain>/<skillId>

triple absent from

icon-manifest.json

.

1. Enumerate all WebPs:

   find viz/public/icons* -name "*.webp"

2. Per file → extract

   <domain>/<id>

   from path
3. Check

   <domain>/<id>

   has entry in

   icon-manifest.json

4. Non-matching = orphans → exist on disk but no longer referenced

# Quick orphan count per palette
node -e "
const fs = require('fs');
const manifest = JSON.parse(fs.readFileSync('viz/public/data/icon-manifest.json'));
const ids = new Set(manifest.map(e => e.domain + '/' + e.id));
const orphans = require('child_process')
  .execSync('find viz/public/icons -name \"*.webp\"').toString().trim().split('\n')
  .filter(p => { const parts = p.split('/'); const id = parts.slice(-2).join('/').replace('.webp',''); return !ids.has(id); });
console.log('Orphans:', orphans.length);
orphans.forEach(p => console.log(' ', p));
"

→ Zero orphans. Any = skills re-homed to diff domain w/o cleanup (18 orphans per re-homing = 9 palettes × 2 sizes).

If err: Delete orphans manually → no manifest entry, won't be served. Re-home events rare → manual cleanup OK.

Step 7: Generate Gap Report

Structured summary.

1. Format out as clear table/list:

   === Icon Pipeline Audit ===
   
   MISSING GLYPHS (no glyph function):
     Skills: 5 missing — [list]
     Agents: 2 missing — [list]
     Teams: 0 missing
   
   MISSING ICONS (glyph exists, no rendered WebP):
     Standard (512px): 3 skills, 1 agent
     HD (1024px): 8 skills, 3 agents, 1 team
   
   STALE MANIFESTS:
     icon-manifest.json: 320 entries vs 326 registry (stale)
     agent-icon-manifest.json: 66 entries vs 66 registry (OK)
     team-icon-manifest.json: 15 entries vs 15 registry (OK)
   

2. Suggest next actions from findings

→ Complete gap report w/ actionable next steps.

If err: All checks pass, zero gaps → report "Pipeline fully in sync" as positive outcome.

Check

• All 3 registries read
• All 3 glyph mapping files checked
• Icon dirs scanned both standard + HD
• Manifest freshness verified
• Orphan icons checked (disk paths vs manifest)
• Gap report produced w/ counts + entity lists
• Actionable next steps provided

Traps

• ID format mismatch: Registry = kebab-case (

  create-skill

  ), glyph maps may use snake_case → normalize comparison
• Palette assumption: Only checking cyberpunk misses palette-specific gaps
• Empty dirs: Domain dir exists but empty → counts as "icons present" w/ globbing → check file existence, not dir
• HD not rendered: HD icons in separate tree (

  icons-hd/

  ) → don't confuse w/ standard
• Orphans after re-homing: Skill domain change →

  build.sh

  creates icons at new path but NOT deletes old → always run Step 6 orphan check after any domain migration

→

• create-glyph — create missing glyph identified by this audit
• enhance-glyph — improve quality of existing glyphs
• render-icon-pipeline — run full pipeline → generate missing icons