render-icon-pipeline

# 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:
   ```bash
   ls -la viz/build.sh
   ```
2. Verify Node.js is available:
   ```bash
   node --version
   ```
3. Check that `viz/config.yml` exists (platform-specific R path profiles):
   ```bash
   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.

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

**If fail:** 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
bash viz/build.sh
```

**Incremental (skip icons that already exist on disk):**
```bash
bash viz/build.sh --skip-existing
```

**Single domain (skills only):**
```bash
bash viz/build.sh --only design
```

**Single entity type:**
```bash
bash viz/build.sh --type skill
bash viz/build.sh --type agent
bash viz/build.sh --type team
```

**Dry run (preview without rendering):**
```bash
bash viz/build.sh --dry-run
```

**Standard size only (skip HD):**
```bash
bash viz/build.sh --no-hd
```

All flags after `build.sh` are passed 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**: 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:
   ```bash
   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

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

**If fail:** 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:

```bash
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)

## 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](../audit-icon-pipeline/SKILL.md) — detect missing glyphs and icons before rendering
- [create-glyph](../create-glyph/SKILL.md) — create new glyph functions for entities missing icons
- [enhance-glyph](../enhance-glyph/SKILL.md) — improve existing glyphs before re-rendering