---

name: render-icon-pipeline description: > Run the viz pipeline to render icons from existing glyphs. Entry point for the viz subproject covering palette generation, data building, manifest creation, and icon rendering for skills, agents, and teams. Always use build.sh as the pipeline entry point — never call Rscript directly. license: MIT allowed-tools: Read Bash Grep Glob metadata: author: Philipp Thoss version: "1.1" domain: visualization complexity: basic language: multi tags: visualization, rendering, pipeline, icons, glyphs, build

Render Icon Pipeline

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

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

When to Use

• After creating or modifying glyph functions
• After adding new skills, agents, or teams to registries
• When icons need re-rendering for new or updated palettes
• For a full pipeline rebuild (e.g., after infrastructure changes)
• When setting up the viz environment for the 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)

Procedure

Step 1: Verify Prerequisites

Ensure the environment is ready for rendering.

1. Confirm viz/build.sh exists:

   ls -la viz/build.sh
   

2. Verify Node.js is available:

   node --version
   

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

   ls viz/config.yml
   

build.sh handles R binary resolution automatically — you do not need to verify R paths manually. On WSL it uses /usr/local/bin/Rscript (WSL-native R), on Docker it uses the container R, and on native Linux/macOS it uses Rscript from PATH.

Expected: build.sh, Node.js, and config.yml are present.

On failure: If config.yml is missing, the pipeline falls back to system defaults. If Node.js is 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 are passed through to build-all-icons.R.

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

On failure:

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

Step 3: Verify Output

Confirm the render completed successfully.

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 the audit-icon-pipeline skill for a comprehensive check

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

On failure: If counts don't match, some glyphs may have errored during rendering. Check the build log for [ERROR] lines.

CLI Flag Reference

All flags are passed 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 manually:

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

The pipeline can also run in Docker:

cd viz
docker compose up --build

This runs the full pipeline in an isolated Linux environment and serves the result on port 8080.

Validation Checklist

• 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)

Common Pitfalls

• Calling Rscript directly: Never run Rscript build-icons.R or Rscript generate-palette-colors.R manually. Always use bash build.sh [flags]. Direct Rscript calls bypass platform detection and may use the wrong R binary (Windows R via ~/bin/Rscript wrapper instead of WSL-native R at /usr/local/bin/Rscript). Note: the 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 automatically (cd "$(dirname "$0")"), so you can call it from anywhere: bash viz/build.sh from project root works correctly.
• Stale manifests: build.sh runs Steps 1-5 in order, so manifests are always regenerated before rendering. If you only need manifests without rendering, use node viz/build-data.js && node viz/build-icon-manifest.js (the Node steps don't need R).
• renv not activated: The .Rprofile workaround requires running from viz/ — build.sh handles this. Using --vanilla flag or running R from another directory will skip it.
• Parallel on Windows: Windows doesn't support fork-based parallelism — the pipeline auto-selects multisession via config.yml.

Related Skills

• 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