Skip to content

docs: Fix broken Unicode emoji rendering across 122+ markdown files ([U+XXXX] → actual emoji) #254

@Foundup

Description

@Foundup

Problem

Emoji characters across 122+ markdown files are rendering as broken Unicode escape text [U+XXXX] instead of actual emoji characters. This makes documentation hard to read and looks unprofessional.

Example (ROADMAP.md line 1)

Current: # [U+1F310] FoundUps Intelligent Internet Orchestration System
Expected: # 🌐 FoundUps Intelligent Internet Orchestration System

Common broken patterns found

Escape Text Should Be Meaning
[U+1F310] 🌐 Globe
[U+1F300] 🌀 Cyclone/WRE
[U+1F4BB] 💻 Computer
[U+1F4E1] 📡 Satellite
[U+2502] Box drawing vertical
[U+1F6A7] 🚧 Construction
[U+1F984] 🦄 Unicorn
[U+1F52E] 🔮 Crystal ball
[U+1F3AD] 🎭 Performing arts
[U+1F3D7] 🏗️ Building construction
[U+1F4BC] 💼 Briefcase
[U+1F3AC] 🎬 Clapper board
[U+1F4F1] 📱 Mobile phone
[U+1F31F] 🌟 Glowing star
[U+1F536] 🔶 Large orange diamond
[U+1F4C1] 📁 File folder
[U+1F3B5] 🎵 Musical note
[U+1F528] 🔨 Hammer
[U+1F3B2] 🎲 Game die
[U+26A0] ⚠️ Warning

Also affected: ASCII art box-drawing characters [U+2502], [U+2500], [U+250C], [U+2514], [U+2510], [U+2518], [U+251C], [U+2524], [U+252C], [U+2534], [U+253C] used in diagrams.

And text-tag emoji aliases: [TARGET], [OK], [DATA], [AI], [BOT], [REFRESH], [ROCKET], [HANDSHAKE], [LINK], [IDEA], [CLIPBOARD], [NOTE], [BIRD], [LIGHTNING], [ALERT], [TERMINAL], [UP] — these should map to their corresponding emoji: 🎯, ✅, 📊, 🤖, 🤖, 🔄, 🚀, 🤝, 🔗, 💡, 📋, 📝, 🐦, ⚡, 🚨, 💻, 📈

Root Cause

The wsp_documentation_guardian.py and discovery_feeder.py sanitizers were converting real emoji to [U+{ord(char):04X}] safe representations (see lines 260-261 in holo_index/qwen_advisor/orchestration/src/wsp_documentation_guardian.py). This was intended for safe processing but was applied to .md documentation files where emojis should render properly.

The README.md is not affected because it was edited separately — but ROADMAP.md, modules/ROADMAP.md, and 120+ other docs were hit.

Scope

122 markdown files contain [U+1F...] broken emoji patterns (GitHub code search: [U+1F path:*.md).

Priority files (public-facing / high-traffic)

  1. ROADMAP.md — 12 instances (root project roadmap)
  2. modules/ROADMAP.md — 14 instances
  3. modules/README.md — 3 instances
  4. docs/foundups_vision.md — 21 instances
  5. prompt/README.md — 3 instances
  6. utils/README.md — 4 instances

Other affected areas

  • WSP_framework/ docs
  • WSP_knowledge/ docs
  • Module-level README.md and ROADMAP.md files across all enterprise domains
  • docs/ analysis and architecture documents

Fix Approach

  1. Manual fix for priority files (ROADMAP.md, modules/ROADMAP.md, etc.) — replace all [U+XXXX] with actual Unicode chars
  2. Script-based batch fix for remaining 117 files using regex: \[U\+([0-9A-Fa-f]{4,5})\]chr(int(match, 16))
  3. Fix the guardian: Update wsp_documentation_guardian.py to skip .md files or preserve emojis in markdown
  4. Add CI check: Prevent [U+ patterns from being committed to .md files in future

WSP References

  • WSP 90 (Unicode compliance)
  • WSP 22 (ModLog documentation)
  • WSP 49 (Module structure standards)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions