Render Icon Pipeline

Run viz pipeline end-to-end to render icons from existing glyphs. Cover palette generation, data building, manifest creation, icon rendering for skills, agents, teams.

Canonical entry point: bash viz/build.sh [flags] from project root, or bash build.sh [flags] from viz/. This script handles platform detection (WSL, Docker, native), R binary selection, step ordering. Never call Rscript direct for build scripts — that path is only for MCP server configuration.

When Use

• After create or modify glyph functions
• After add new skills, agents, or teams to registries
• When icons need re-rendering for new or updated palettes
• For full pipeline rebuild (e.g., after infrastructure changes)
• When set up viz environment for first time

Inputs

• Optional: Entity type — skill, agent, team, or all (default: all)
• Optional: Palette — specific palette name or all (default: all)
• Optional: Domain filter — specific domain for skill icons (e.g., git, design)
• Optional: Render mode — full, incremental, or dry-run (default: incremental)

Steps

Step 1: Verify Prerequisites

Ensure environment ready for rendering.

1. Confirm viz/build.sh exists:

   ls -la viz/build.sh
   

2. Verify Node.js available:

   node --version
   

3. Check viz/config.yml exists (platform-specific R path profiles):

   ls viz/config.yml
   

build.sh handles R binary resolution automatic — no need to verify R paths manual. On WSL it uses /usr/local/bin/Rscript (WSL-native R), on Docker it uses container R, on native Linux/macOS it uses Rscript from PATH.

Got: build.sh, Node.js, config.yml are present.

If fail: config.yml missing? Pipeline falls back to system defaults. Node.js missing? Install via nvm.

Step 2: Run the Pipeline

build.sh executes 5 steps in order:

1. Generate palette colors (R) → palette-colors.json + colors-generated.js
2. Build data (Node) → skills.json
3. Build manifests (Node) → icon-manifest.json, agent-icon-manifest.json, team-icon-manifest.json
4. Render icons (R) → icons/ and icons-hd/ WebP files
5. Generate terminal glyphs (Node) → cli/lib/glyph-data.json

Full pipeline (all types, all palettes, standard + HD):

bash viz/build.sh

Incremental (skip icons that already exist on disk):

bash viz/build.sh --skip-existing

Single domain (skills only):

bash viz/build.sh --only design

Single entity type:

bash viz/build.sh --type skill
bash viz/build.sh --type agent
bash viz/build.sh --type team

Dry run (preview without rendering):

bash viz/build.sh --dry-run

Standard size only (skip HD):

bash viz/build.sh --no-hd

All flags after build.sh pass through to build-all-icons.R.

Got: Icons rendered to viz/public/icons/<palette>/ and viz/public/icons-hd/<palette>/.

If fail:

• renv hang on NTFS: viz .Rprofile bypasses renv/activate.R and sets .libPaths() direct. Ensure you run from viz/ (build.sh does this auto via cd "$(dirname "$0")")
• Missing R packages: Run Rscript -e "install.packages(c('ggplot2', 'ggforce', 'ggfx', 'ragg', 'magick', 'future', 'furrr', 'digest'))" from R environment that build.sh selects
• No glyph mapped: Entity needs glyph function — use create-glyph skill before rendering

Step 3: Verify Output

Confirm render completed successful.

1. Check file counts match expectations:

   find viz/public/icons/cyberpunk -name "*.webp" | wc -l
   find viz/public/icons-hd/cyberpunk -name "*.webp" | wc -l
   

2. Check for reasonable file sizes (2-80 KB per icon)
3. Run audit-icon-pipeline skill for comprehensive check

Got: File counts match manifest entry counts. File sizes in expected range.

If fail: Counts no match? Some glyphs may have errored during rendering. Check build log for [ERROR] lines.

CLI Flag Reference

All flags pass through build.sh to build-all-icons.R:

Flag	Default	Description
--type <types>	all	Comma-separated: skill, agent, team
--palette <name>	all	Single palette or all (9 palettes)
--only <filter>	none	Domain (skills) or entity ID (agents/teams)
--skip-existing	off	Skip icons with existing WebP files
--dry-run	off	List what would be generated
--size <n>	512	Output dimension in pixels
--glow-sigma <n>	4	Glow blur radius
--workers <n>	auto	Parallel workers (detectCores()-1)
--no-cache	off	Ignore content-hash cache
--hd	on	Enable HD variants (1024px)
--no-hd	off	Skip HD variants
--strict	off	Exit on first sub-script failure

What build.sh Does Internally

For reference only — do NOT run these steps manual:

cd viz/
# 1. Platform detection: sets R_CONFIG_ACTIVE (wsl, docker, or unset)
# 2. R binary selection: WSL → /usr/local/bin/Rscript, Docker → same, native → Rscript
# 3. $RSCRIPT generate-palette-colors.R
# 4. node build-data.js
# 5. node build-icon-manifest.js --type all
# 6. $RSCRIPT build-all-icons.R "$@"  (flags passed through)
# 7. node build-terminal-glyphs.js

Docker Alternative

Pipeline can also run in Docker:

cd viz
docker compose up --build

Runs full pipeline in isolated Linux environment. Serves result on port 8080.

Checks

• Ran bash viz/build.sh (not bare Rscript)
• Palette colors generated (JSON + JS)
• Data files built from registries
• Manifests generated from data
• Icons rendered for target types and palettes
• File counts match expectations
• File sizes in expected range (2-80 KB)

Pitfalls

• Call Rscript direct: Never run Rscript build-icons.R or Rscript generate-palette-colors.R manual. Always use bash build.sh [flags]. Direct Rscript calls bypass platform detection. May use wrong R binary (Windows R via ~/bin/Rscript wrapper instead of WSL-native R at /usr/local/bin/Rscript). Note: Windows R path in CLAUDE.md and guides is for MCP server configuration only, not for build scripts.
• Wrong working directory: build.sh CDs to its own directory auto (cd "$(dirname "$0")"), so you can call it from anywhere: bash viz/build.sh from project root works correct.
• Stale manifests: build.sh runs Steps 1-5 in order, so manifests always regenerated before rendering. Need only manifests without rendering? Use node viz/build-data.js && node viz/build-icon-manifest.js (Node steps no need R).
• renv not activated: .Rprofile workaround needs running from viz/ — build.sh handles this. Using --vanilla flag or running R from another directory will skip it.
• Parallel on Windows: Windows no support fork-based parallelism — pipeline auto-selects multisession via config.yml.

See Also

• audit-icon-pipeline — detect missing glyphs and icons before rendering
• create-glyph — create new glyph functions for entities missing icons
• enhance-glyph — improve existing glyphs before re-rendering