bee/bible-local/rules/patterns/ascii-safe-text/contract.md

Contract: ASCII-Safe Text in Scripts and Boot Configs

Version: 1.0

Principle

Shell scripts, bootloader configs, and any text rendered on serial/SOL consoles must use only printable ASCII characters. Non-ASCII Unicode — including typographic punctuation such as the em-dash (U+2014 —), en-dash (U+2013 –), curly quotes, and ellipsis (U+2026 …) — breaks rendering on serial terminals, GRUB text/serial mode, IPMI SOL, and tooling that assumes ASCII.

Rules

• Never use em-dash (—) or en-dash (–) in any shell script, GRUB config, syslinux/isolinux config, or service unit file. Use ASCII double-hyphen -- or single hyphen - instead.
• Never use curly quotes (" " ' ') in shell scripts or configs. Use straight quotes " and '.
• Never use the Unicode ellipsis (…). Use ....
• GRUB menuentry and submenu titles must be ASCII-only — GRUB serial terminal output is ASCII; non-ASCII characters render as garbage or are dropped.
• Comments in GRUB theme files (.txt) must also be ASCII-only, as GRUB may parse the entire file.

Why

GRUB renders menus over both gfxterm (graphical, Unicode-capable) and serial (ASCII-only) simultaneously when terminal_output gfxterm serial is set. The serial output — used by IPMI SOL and BMC remote consoles — cannot display multi-byte UTF-8 sequences and shows raw bytes or drops characters. A menuentry title "EASY-BEE — GSP=off" appears as "EASY-BEE â€" GSP=off" or "EASY-BEE GSP=off" on SOL, making the menu unreadable.

Anti-patterns

• menuentry "EASY-BEE — GSP=off" — em-dash in GRUB title
• # bee logo — centered — em-dash in GRUB theme comment
• echo "done — reboot" in a shell script displayed over serial

Correct form

• menuentry "EASY-BEE -- GSP=off"
• # bee logo - centered
• echo "done - reboot"