Icon-Pipeline rendern

Die viz-Pipeline von Anfang bis Ende ausfuehren, um Icons aus bestehenden Glyphen zu rendern. Umfasst Palettengenerierung, Datenaufbau, Manifest-Erstellung und Icon-Rendering fuer Skills, Agents und Teams.

Kanonischer Einstiegspunkt: bash viz/build.sh [flags] vom Projektstamm aus oder bash build.sh [flags] aus viz/. Dieses Skript uebernimmt die Plattformerkennung (WSL, Docker, nativ), die Auswahl des R-Binaries und die Reihenfolge der Schritte. Niemals Rscript direkt fuer Build-Skripte aufrufen — dieser Pfad ist ausschliesslich fuer die MCP-Server-Konfiguration gedacht.

Wann verwenden

• Nach dem Erstellen oder Aendern von Glyphen-Funktionen
• Nach dem Hinzufuegen neuer Skills, Agents oder Teams zu Registries
• Wenn Icons fuer neue oder aktualisierte Paletten neu gerendert werden muessen
• Fuer einen vollstaendigen Pipeline-Neubau (z.B. nach Infrastruktur-Aenderungen)
• Beim erstmaligen Einrichten der viz-Umgebung

Eingaben

• Optional: Entitaetstyp — skill, agent, team oder all (Standard: all)
• Optional: Palette — spezifischer Palettenname oder all (Standard: all)
• Optional: Domaenenfilter — spezifische Domaene fuer Skill-Icons (z.B. git, design)
• Optional: Rendermodus — full, incremental oder dry-run (Standard: incremental)

Verfahren

Schritt 1: Voraussetzungen pruefen

Sicherstellen, dass die Umgebung fuer das Rendering bereit ist.

1. Existenz von viz/build.sh bestaetigen:

   ls -la viz/build.sh
   

2. Verfuegbarkeit von Node.js pruefen:

   node --version
   

3. Pruefen, ob viz/config.yml existiert (plattformspezifische R-Pfadprofile):

   ls viz/config.yml
   

build.sh uebernimmt die Aufloesung des R-Binaries automatisch — R-Pfade muessen nicht manuell verifiziert werden. Unter WSL wird /usr/local/bin/Rscript (WSL-natives R) verwendet, unter Docker das Container-R, und unter nativem Linux/macOS Rscript aus dem PATH.

Erwartet: build.sh, Node.js und config.yml sind vorhanden.

Bei Fehler: Falls config.yml fehlt, greift die Pipeline auf Systemstandards zurueck. Falls Node.js fehlt, ueber nvm installieren.

Schritt 2: Pipeline ausfuehren

build.sh fuehrt 5 Schritte in folgender Reihenfolge aus:

1. Palettenfarben generieren (R) → palette-colors.json + colors-generated.js
2. Daten aufbauen (Node) → skills.json
3. Manifeste erstellen (Node) → icon-manifest.json, agent-icon-manifest.json, team-icon-manifest.json
4. Icons rendern (R) → WebP-Dateien in icons/ und icons-hd/
5. Terminal-Glyphen generieren (Node) → cli/lib/glyph-data.json

Vollstaendige Pipeline (alle Typen, alle Paletten, Standard + HD):

bash viz/build.sh

Inkrementell (bereits vorhandene Icons auf der Festplatte ueberspringen):

bash viz/build.sh --skip-existing

Einzelne Domaene (nur Skills):

bash viz/build.sh --only design

Einzelner Entitaetstyp:

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

Probelauf (Vorschau ohne Rendering):

bash viz/build.sh --dry-run

Nur Standardgroesse (HD ueberspringen):

bash viz/build.sh --no-hd

Alle Flags nach build.sh werden an build-all-icons.R durchgereicht.

Erwartet: Icons gerendert nach viz/public/icons/<palette>/ und viz/public/icons-hd/<palette>/.

Bei Fehler:

• renv-Haenger auf NTFS: Die viz-.Rprofile umgeht renv/activate.R und setzt .libPaths() direkt. Sicherstellen, dass aus viz/ ausgefuehrt wird (build.sh erledigt das automatisch via cd "$(dirname "$0")")
• Fehlende R-Pakete: Rscript -e "install.packages(c('ggplot2', 'ggforce', 'ggfx', 'ragg', 'magick', 'future', 'furrr', 'digest'))" aus der R-Umgebung ausfuehren, die build.sh auswaehlt
• No glyph mapped: Die Entitaet benoetigt eine Glyphen-Funktion — den create-glyph Skill vor dem Rendering verwenden

Schritt 3: Ausgabe verifizieren

Bestaetigen, dass das Rendering erfolgreich abgeschlossen wurde.

1. Dateianzahlen gegen Erwartungen pruefen:

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

2. Auf angemessene Dateigroessen pruefen (2-80 KB pro Icon)
3. Den audit-icon-pipeline Skill fuer eine vollstaendige Pruefung ausfuehren

Erwartet: Dateianzahlen stimmen mit Manifest-Eintragsanzahlen ueberein. Dateigroessen im erwarteten Bereich.

Bei Fehler: Falls die Anzahlen nicht uebereinstimmen, koennten einige Glyphen waehrend des Renderings Fehler verursacht haben. Das Build-Log auf [ERROR]-Zeilen pruefen.

CLI-Flag-Referenz

Alle Flags werden von build.sh an build-all-icons.R durchgereicht:

Flag	Default	Beschreibung
--type <types>	all	Kommagetrennt: skill, agent, team
--palette <name>	all	Einzelne Palette oder all (9 Paletten)
--only <filter>	keiner	Domaene (Skills) oder Entitaets-ID (Agents/Teams)
--skip-existing	aus	Icons mit vorhandenen WebP-Dateien ueberspringen
--dry-run	aus	Auflisten, was generiert wuerde
--size <n>	512	Ausgabedimension in Pixeln
--glow-sigma <n>	4	Glow-Unschaerferadius
--workers <n>	auto	Parallele Worker (detectCores()-1)
--no-cache	aus	Inhaltshash-Cache ignorieren
--hd	ein	HD-Varianten aktivieren (1024px)
--no-hd	aus	HD-Varianten ueberspringen
--strict	aus	Bei erstem Unterskript-Fehler beenden

Was build.sh intern tut

Nur zur Referenz — diese Schritte NICHT manuell ausfuehren:

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

Die Pipeline kann auch in Docker ausgefuehrt werden:

cd viz
docker compose up --build

Dies fuehrt die vollstaendige Pipeline in einer isolierten Linux-Umgebung aus und liefert das Ergebnis auf Port 8080.

Validierungscheckliste

• bash viz/build.sh ausgefuehrt (nicht bloss Rscript)
• Palettenfarben generiert (JSON + JS)
• Datendateien aus Registries aufgebaut
• Manifeste aus Daten generiert
• Icons fuer Zieltypen und -paletten gerendert
• Dateianzahlen stimmen mit Erwartungen ueberein
• Dateigroessen im erwarteten Bereich (2-80 KB)

Haeufige Fehler

• Rscript direkt aufrufen: Niemals Rscript build-icons.R oder Rscript generate-palette-colors.R manuell ausfuehren. Immer bash build.sh [flags] verwenden. Direkte Rscript-Aufrufe umgehen die Plattformerkennung und koennen das falsche R-Binary verwenden (Windows-R ueber ~/bin/Rscript-Wrapper anstelle von WSL-nativem R unter /usr/local/bin/Rscript). Hinweis: Der Windows-R-Pfad in CLAUDE.md und Guides ist ausschliesslich fuer die MCP-Server-Konfiguration gedacht, nicht fuer Build-Skripte.
• Falsches Arbeitsverzeichnis: build.sh wechselt automatisch in sein eigenes Verzeichnis (cd "$(dirname "$0")"), sodass der Aufruf von ueberall aus funktioniert: bash viz/build.sh vom Projektstamm aus arbeitet korrekt.
• Veraltete Manifeste: build.sh fuehrt die Schritte 1-5 in der richtigen Reihenfolge aus, sodass Manifeste immer vor dem Rendering neu generiert werden. Werden nur Manifeste ohne Rendering benoetigt, node viz/build-data.js && node viz/build-icon-manifest.js verwenden (die Node-Schritte benoetigen kein R).
• renv nicht aktiviert: Der .Rprofile-Workaround erfordert Ausfuehrung von viz/ — build.sh erledigt dies. Die Verwendung des --vanilla-Flags oder das Starten von R aus einem anderen Verzeichnis ueberspringt ihn.
• Parallelitaet unter Windows: Windows unterstuetzt keine fork-basierte Parallelitaet — die Pipeline waehlt automatisch multisession ueber config.yml.

Verwandte Skills

• audit-icon-pipeline — Fehlende Glyphen und Icons vor dem Rendering erkennen
• create-glyph — Neue Glyphen-Funktionen fuer Entitaeten ohne Icons erstellen
• enhance-glyph — Bestehende Glyphen vor dem erneuten Rendering verbessern