# Glyphs

Shared symbol vocabulary for docs, reports, generated tables, tickets, and chat replies.

The point is not decoration. A glyph is the only reliable way to make one row stand out from
fifty: in a rendered table `**bold**` in a right-aligned numeric column is close to invisible,
while a coloured glyph is found instantly. Spend that budget deliberately.

**Scope.** This file fixes what symbols *mean*. It does not govern box-drawing characters
(`─ │ ├ └ ┌ ┐ ┘`) used for trees and diagrams, nor the plain-text arrows (`→ ↔ ← ⇒ ↓ ↳`)
already used throughout prose — both are settled and stay as they are. It governs how densely
markers may be spent (§Restraint), but not table layout, rounding, cut-points, or which rows a
given document chooses to highlight — those belong to whatever document defines the table.

## The governing rule

> **Not important — suppress.** Render `<small>` / grey, or drop it from the document
> entirely. Removing a useless column, a repeated string, or a derivable value is better than
> dimming it.
>
> **Important — bright coloured glyph.** Bold is a secondary reinforcement only, never the
> sole signal.

## Restraint

The default is **no glyph**. A glyph earns its place only where a reader must find something
without reading everything — a severity, a status, a maximum, a blind spot. Ordinary prose,
ordinary rows, and headings take none.

The catalogue in §4 is a *reserved vocabulary*, not a menu. It exists so that when a marker is
needed the same one is chosen every time, and so that a symbol already carrying a meaning is
not quietly reused for another. Picking from it is not a reason to add one.

Three practical limits:

- **One glyph per cell**, and most cells get none.
- **One category axis per table.** A table already carrying severity bands does not also carry
  category diamonds or state buttons.
- **If most rows would carry it, none should** — that signal belongs in one line above the
  table.

A document where every row is marked has marked nothing.

---

## 1. Normative core

Fixed meanings, already in wide use across committed documentation. Do not redefine them for a
local table.

### Colour before shape · 🔴 🟠 🟢 ⚪ 🔵

Before any specific meaning, colour sets **how much attention the line is asking for**. This
holds across every coloured family — circles, squares, hearts — and a reader applies it without
consulting a legend, which is exactly why a document must not contradict it.

**The working set — what a table normally needs, and normally all it needs:**

| Colour | The line is asking for |
|---|---|
| 🔴 red | **important — pay attention** |
| 🟠 orange | notable; attention, but not now |
| 🟢 green | OK, success. Nothing to worry about, always |
| ⚪ white | no signal at all — absent, unset, inactive |
| 🔵 blue | information; also *not applicable* — nothing to worry about, and skipping the line costs nothing |

Five colours, four attention levels and a null. Every colour added past them costs the reader a
legend lookup the first five did not need, so the two that remain are genuinely last resorts:
🟣 for a value that has left the top of a scale (§Ordered bands), ⚫ as ⚪'s filled counterpart
where a table already distinguishes filled from empty.

**🟣 usually should not appear.** A value past the top of the scale is already 🔴 — *pay
attention* — and the sixth colour only earns its place when off-scale demands a **different
action** than high: page someone rather than schedule it, stop the run rather than note it. If
the reader would do the same thing either way, 🔴 said it already.

**But when the reds are many, 🟣 stops being optional.** A column with fifteen red rows has
ranked nothing: red now means *this table has problems*, which the reader knew, and it no longer
says where to start. At that point the different-action test is met by the situation itself —
the action that differs is *which row to open first* — so lift the genuinely worst rows to 🟣 and
leave the rest red. Enforce it rather than debate it: red must stay scannable, a handful per
screen. If more than that qualifies, either the top of the range takes 🟣 or the threshold that
produced so many reds is set wrong, and both are fixes, not annotations.

**No yellow anywhere** — 🟠 covers that level, and yellow is absent from the catalogue rather
than merely discouraged. Yellow and orange are the pair readers separate least reliably: on a
projector, on a phone, on a colour-blind display they are one colour, so a scale spending both
has bought a distinction its reader cannot see.

`—` and 🔵 both cover *not applicable* and do not compete: `—` is the text a data cell takes
(§Absence), 🔵 is the marker a status column takes.

Two consequences worth stating, because both are easy to get backwards:

**Green is always OK — this one is a hard rule, not a preference.** 🟢 says *nothing to worry
about here*, everywhere, in every document. If a scale would put green on the side the reader
should worry about — utilisation, cost, error rate, backlog — the scale is defined the wrong way
round and gets inverted. It is not annotated, not excused by a legend, and not "obvious from
context": a reader who has been trained by every other table to skip green rows will skip this
one too, and the one time it mattered they will have skipped the row that needed them.

**Green on something that needs action is a defect — say so.** A review that lets it through has
missed a real finding, the same as a wrong return type. Call it out and have the scale fixed;
this is not a style quibble.

**Colour outranks the glyph.** A red marker on an unimportant row is noise however apt the
symbol is, and a green one on a row that needs action is worse than no marker at all.

### Severity and status — from `CLAUDE.md` · 🔴 🟠 ⚪ ✅ ⚠️ 🎫 ❌ 🚫 ⛔ ❓ ⁉️

| Glyph | Unicode | Meaning |
|---|---|---|
| 🔴 | `U+1F534` | high severity — alert: something is wrong, pay attention |
| 🟠 | `U+1F7E0` | medium severity |
| ⚪ | `U+26AA` | low severity |
| ✅ | `U+2705` | fixed / done |
| ⚠️ | `U+26A0 U+FE0F` | partial / follow-up required |
| 🎫 | `U+1F3AB` | ticketed / handed off |
| ❌ | `U+274C` | FAIL — it ran and did not pass. Nothing else |
| 🚫 | `U+1F6AB` | cancelled / rejected — dropped by decision, not by failure |
| ⛔ | `U+26D4` | cannot be done — blocked, no access, impossible. Nothing failed; nothing ran |
| ❓ | `U+2753` | open question — needs an answer and has none: not measured, not observable, undecided |
| ⁉️ | `U+2049 U+FE0F` | disagreement — two sources contradict, and the conflict is still open |

❓ and ⁉️ are the two **open** states, and they are open in different ways. ❓ is *a question
that needs an answer and has none* — nobody disagrees, the answer simply does not exist yet: not
measured, not observable, undecided. ⁉️ is *two answers that exist and cannot both be right* — a review finding against what the code does, a ticket against the measurement,
two runs that disagree. Both say someone must act, and both come off the moment the item is
settled: a resolved question is just the answer.

Neither may be written as ❌. ❌ is failure and only failure — something ran and did not pass.
Everything adjacent has its own marker and must use it: "we could not check" is ❓, "the sources
conflict" is ⁉️, "partly done" is ⚠️, "someone else has it" is 🎫, "we decided not to" is 🚫,
"we cannot" is ⛔.
Each time one of those was allowed to borrow ❌, the table stopped distinguishing what happened
from what was never attempted.

Say what would settle it. A ❓ with no named next step — the query to run, the access to get,
the person to ask — is a shrug, and a shrug in a table cannot be told apart from work nobody
did. Same for ⁉️: name the two sources that disagree.

Severity and status answer different questions and are not interchangeable. 🔴 says **how much this
matters** — it is an alert, and it is right on a row that has not failed anything yet but is
about to. ❌ says **what happened** — the step ran and did not pass.

⛔ and ❌ are the pair most worth keeping apart: ⛔ means the step never ran — no access, no
data, blocked by something else — and ❌ means it ran and did not pass. A ⛔ row is somebody's
next task; a ❌ row is a result.

🚫 is the one most easily lost, because a dropped item and a failed one both read as bad news.
They are not the same claim: a cancelled scope item, a rejected finding, a proposal turned down —
nothing about them failed, someone decided. Marking those ❌ invents failures the project never
had and hides the decisions it did make.

### Ordered bands · ⚪ 🟢 🟠 🔴 🟣

When a document needs an ordered scale rather than the three severity levels, it uses this
order and no other:

| Glyph | Unicode | Band |
|---|---|---|
| ⚪ | `U+26AA` | none / lowest |
| 🟢 | `U+1F7E2` | low |
| 🟠 | `U+1F7E0` | medium |
| 🔴 | `U+1F534` | high |
| 🟣 | `U+1F7E3` | beyond the top band — saturated, overloaded, off-scale. Optional, and usually left out |

🟠 and 🔴 now mean the same level on both scales; the bands only add ⚪ *none* below severity's
⚪ *low*, and — where a scale needs it at all — 🟣 above. Still say which scale a table uses — one line above it, "utilisation
bands, ⚪→🟣" — because the cut-points never travel with the glyphs.

The glyph order never changes. What each band *means* — the direction of "good", the
cut-points, the units — belongs next to the scale it measures, not here. Green stays the
untroubled end on every scale (see *Colour before shape*): a scale whose bad end would come out
green is defined the wrong way round and gets inverted, not annotated.

### Emphasis · 🌟 ⭐

| Glyph | Unicode | Meaning |
|---|---|---|
| 🌟 | `U+1F31F` | rank 1 — the maximum |
| ⭐ | `U+2B50` | rank 2 — the runner-up |

Two ranks, never three. 🌟 reads as the larger mark because of its sparkle burst, so the eye
lands on the maximum first and finds the runner-up second without re-reading the column. Ties
extend a rank rather than adding one: three equal maxima are three 🌟 and no ⭐.

Never the text-form black star (`U+2605`) — it renders in the body text colour and does not
read as a marker.

### Absence and unknowns · 0 ∅ — ¿

A document is only as honest as its blank cells. Distinguish these four; never render any of
them as an empty cell, which a reader scanning a table will skip in silence.

| Glyph | Unicode | Meaning |
|---|---|---|
| `0` | — | a measured zero |
| `∅` | `U+2205` | a real value too small to show at the displayed precision |
| `—` | `U+2014` | not applicable; the thing does not exist here |
| `¿` | `U+00BF` | not measured, or not observable |

The quiet `¿` is deliberate, and so is its being upside down. ❓ is the findings marker — an
open question someone must answer, meant to be seen; a cell nobody measured is not a finding,
and a column of red question marks would outshout every real signal on the page. But a plain `?`
in a cell is worse than quiet, it is invisible: it reads as a typo, as part of a value, or as
prose punctuation that leaked into the table. `¿` cannot be any of those — nothing else in an
English document uses it — so it stays text-weight while still being unmistakably a marker.
Same concept, two weights: ❓ in a findings or status line, `¿` in a table cell.

`∅` is not the digit zero and not "nothing": it says the quantity exists but rounds away. A
counted zero is `0`; a thing that cannot exist here is `—`. This is the meaning already carried
by every `∅` in `doc/infra/main-server-inventory*.md`.

---

## 2. Retire these alternates

Minority spellings of symbols that already have an established form. Replace on sight.

The retired forms are named rather than shown: printing them here would put the very characters
this section removes back into circulation, and several of them render as faint outlines in the
places that matter.

| Retire | Use | Why |
|---|---|---|
| warning sign without the selector, `U+26A0` | ⚠️ | renders monochrome next to coloured glyphs |
| black star, `U+2605` | ⭐ | renders in body text colour |
| check mark `U+2713` / heavy check mark `U+2714` without the selector | ✅ | text-presentation outlines. As a **status** mark ✅ is the established form; ✔️ *with* `U+FE0F` keeps its own quieter checklist role (§4) |
| ballot x, `U+2717` | ❌ | text-presentation outline |
| circled information source, `U+24D8` | ℹ️ | renders faint at body size; ℹ️ is the established info marker (💡 is a *tip*, a different callout) |
| a bare `?` anywhere | ❓ or `¿` | ❓ in a findings or status line, where it must be seen; `¿` in a data cell, where ❓ is too loud (§1). A plain `?` reads as a typo in both |

---

## 3. Reading the catalogue

§4 lists each symbol with the meanings it commonly carries in the wild — in issue trackers,
READMEs, dashboards, status pages, chat and commit messages. Most symbols carry several, and
the list is deliberately broad: **the risk being guarded against is assuming a symbol means one
narrow thing to everyone.** A reader who has met 🔥 as "urgent" and a writer who meant "popular"
will not notice they disagree.

Practical consequences:

- **Pick a symbol whose common meanings all point the same way** as your intent. Where they do
  not, say in the document what you mean by it — one line, once.
- **A row marked *ambiguous* means the symbol's meanings genuinely conflict** (often by
  audience or culture). Avoid it where being misread matters, or define it explicitly.
- **A row marked *collision* means it looks like another glyph** at table size, whatever it
  means. Keep the two out of the same table.
- Anything outside §1 is a *category* marker, not a severity marker — do not build a second
  severity scale out of it.

---

## 4. Catalogue

### Coloured circles · 🔴 🟠 🟢 🔵 🟣 🟤 ⚫ ⚪

The most reliable family for status, because the colour carries the meaning and the shape
carries none.

| Symbol | Name | Unicode | Common uses | Note |
|---|---|---|---|---|
| 🔴 | red circle | `U+1F534` | error, failure, critical, blocked, offline, stopped; also "recording" and "live" | core |
| 🟠 | orange circle | `U+1F7E0` | warning, degraded, medium severity, needs attention | core |
| 🟢 | green circle | `U+1F7E2` | ok, success, passing, healthy, online, available, go | core |
| 🔵 | blue circle | `U+1F535` | informational, neutral, unclassified; a fourth state deliberately outside good/bad | core |
| 🟣 | purple circle | `U+1F7E3` | special, custom, "other"; also the off-scale top band (§1) | core |
| 🟤 | brown circle | `U+1F7E4` | the seventh category colour, once the six bright ones are spent; also legacy / archived / superseded, since brown reads as faded rather than alarming | |
| ⚫ | black circle | `U+26AB` | disabled, inactive, off, N/A, filled/selected in a bullet scale | collision: check ⚫/🟣 and ⚫/🔵 in your own renderer |
| ⚪ | white circle | `U+26AA` | empty, not started, unset, unselected | core |

### Coloured squares · 🟥 🟧 🟩 🟦 🟪 🟫 ⬛ ⬜

The same palette in a second shape. Common in heat maps, progress bars, contribution graphs and
language bars, where a run of squares is read as a whole rather than cell by cell. Keep them out
of any table that already carries circles — two shapes in one table read as two axes.

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| 🟥 | red square | `U+1F7E5` | high severity, hot cell, blocked, failing |
| 🟧 | orange square | `U+1F7E7` | medium-high, warning tier |
| 🟩 | green square | `U+1F7E9` | good, low severity, complete, correct |
| 🟦 | blue square | `U+1F7E6` | informational tier, neutral fill |
| 🟪 | purple square | `U+1F7EA` | category tag, off-scale tier |
| 🟫 | brown square | `U+1F7EB` | archive or cold tier in a heat map — the band below "quiet", where a colder colour would read as healthy |
| ⬛ | black large square | `U+2B1B` | filled, on, present, selected |
| ⬜ | white large square | `U+2B1C` | empty, off, absent, unselected |

### Check, cross, status marks · ✅ ❌ ⚠️ 🚫 ❗ ❓ ➕ ➖ ✔️ ✖️ ⭕

| Symbol | Name | Unicode | Common uses | Note |
|---|---|---|---|---|
| ✅ | check mark button | `U+2705` | done, yes, passing, approved, correct, supported | core |
| ❌ | cross mark | `U+274C` | failed, no, rejected, incorrect, unsupported, absent. Narrower here: §1 makes it *failure only* | core |
| ⚠️ | warning sign | `U+26A0 U+FE0F` | warning, caution, hazard, known limitation | core |
| 🚫 | prohibited | `U+1F6AB` | not allowed, banned, unsupported, blocked by policy; here also **cancelled / rejected** (§1) | collision with ⛔; convention: 🚫 for *not permitted or dropped*, ⛔ for *do not proceed* |
| ❗ | red exclamation | `U+2757` | important, urgent, attention required | overlaps ‼️; pick one of the two per document |
| ❓ | red question mark | `U+2753` | unknown, unclear, open question, needs input | |
| ➕ | heavy plus | `U+2795` | added, new, include, expand, increase | |
| ➖ | heavy minus | `U+2796` | removed, exclude, collapse, decrease | |
| ✔️ | heavy check mark | `U+2714 U+FE0F` | a plain tick: checklist item done, row covered. Its job is to be **quieter than ✅** — in a dense table a column of green boxes shouts, a column of ticks reads | |
| ✖️ | multiplication x | `U+2716 U+FE0F` | the **close / dismiss** glyph, as on a dialog button; also literal multiplication and dimensions (`3 ✖️ 4`) — neither of which ❌ can carry | |
| ⭕ | hollow red circle | `U+2B55` | required field; circled for attention; the hollow half of a filled/hollow pair (○ vs ●). In Japanese convention (*maru*) it means **correct / yes**, so a ⭕/❌ compatibility matrix is read as supported/unsupported by a large audience | ambiguous; collision: reads as 🔴 |

### Diamonds, stars, hearts · 🔶 🔷 🌟 ⭐ ❤️ 🧡 💛 💚 💙 💜 🤍 🖤

Diamonds and hearts are category palettes, so the same rule the squares carry applies: one
category axis per table (§Restraint). A table already spending circles on severity may add
*one* of these families, never two.

| Symbol | Name | Unicode | Common uses | Note |
|---|---|---|---|---|
| 🔶 | large orange diamond | `U+1F536` | bullet or legend key, first category | |
| 🔷 | large blue diamond | `U+1F537` | bullet or legend key, second category | |
| 🌟 | glowing star | `U+1F31F` | featured, standout, excellent — in the wild interchangeable with ⭐; the rank-1/rank-2 split is this codebase's convention (§1), not something an outside reader will infer | core |
| ⭐ | star | `U+2B50` | favourite, rating, bookmarked, repository star | core |
| ❤️ | red heart | `U+2764 U+FE0F` | like, sponsor, favourite, "made with"; as a tag, the first category colour | |
| 🧡 | orange heart | `U+1F9E1` | category tag | |
| 💛 | yellow heart | `U+1F49B` | category tag | |
| 💚 | green heart | `U+1F49A` | category tag | |
| 💙 | blue heart | `U+1F499` | category tag | |
| 💜 | purple heart | `U+1F49C` | category tag | |
| 🤍 | white heart | `U+1F90D` | category tag | |
| 🖤 | black heart | `U+1F5A4` | category tag | |

The hearts earn their place by **not being circles**. A table that already spends circles on
severity has no colour left for category without the two axes bleeding into each other; hearts
give a second full palette that cannot be misread as a band. The cost is that a heart also reads
as affection to everyone — fine for a label column, wrong for anything a reader might take as
approval.

### Priority and signal · 🔥 ⚡ 🚨 🔔 📌 🏁 🎯

| Symbol | Name | Unicode | Common uses | Note |
|---|---|---|---|---|
| 🔥 | fire | `U+1F525` | urgent, hot; **and** trending / popular / excellent — praise and alarm in one symbol; also *deleting code* (gitmoji) and literally burning | ambiguous |
| ⚡ | high voltage | `U+26A1` | fast, performance, power, quick action, electricity, a "lightning" shortcut | |
| 🚨 | police car light | `U+1F6A8` | alert, incident, emergency, escalation, breaking news | |
| 🔔 | bell | `U+1F514` | notification, reminder, subscribe, watch | |
| 📌 | pushpin | `U+1F4CC` | pinned, sticky, important, kept at the top | |
| 🏁 | chequered flag | `U+1F3C1` | finish, milestone reached, release, race end | |
| 🎯 | bullseye | `U+1F3AF` | goal, target, objective, on target, precision, scope | |

### Severity and attention · 💥 ⛔ ‼️ 💢 ⁉️

| Symbol | Name | Unicode | Common uses | Note |
|---|---|---|---|---|
| 💥 | collision | `U+1F4A5` | crash, breaking change, conflict, impact, explosion | |
| ⛔ | no entry | `U+26D4` | forbidden, blocked, do not proceed, access denied; here **cannot be done** (§1) | collision with 🚫 — see its row |
| ‼️ | double exclamation | `U+203C U+FE0F` | must not be missed, double emphasis | |
| 💢 | anger symbol | `U+1F4A2` | friction with a human cost: the pain point in a retro, the step where users give up, the process everyone dreads. Reads as *someone is annoyed* — which is why it is not 💥, a machine-side breakage | |
| ⁉️ | exclamation question | `U+2049 U+FE0F` | in this codebase (§1) an open **disagreement** between two sources; in the wild also plain surprise or disbelief, so say which you mean outside a findings table | |

### State and lifecycle · ✳️ ♻️ 🔒 🔑 ⏸️ ▶️ ⏹️ 🔁 🔄 🆕 🆗 🆙 🔚 🔛 🔜

| Symbol | Name | Unicode | Common uses | Note |
|---|---|---|---|---|
| ✳️ | eight-spoked asterisk | `U+2733 U+FE0F` | footnote anchor and "see note" — the one that survives Markdown, where a bare `*` is eaten as emphasis; also a required field | |
| ♻️ | recycling symbol | `U+267B U+FE0F` | refactor, reuse, cleanup, recurring; also sustainability | |
| 🔒 | locked | `U+1F512` | secured, private, closed, protected, read-only | |
| 🔑 | key | `U+1F511` | credentials, auth, access, secret; also "key insight / the crux" | |
| ⏸️ | pause button | `U+23F8 U+FE0F` | paused, on hold, suspended | |
| ▶️ | play button | `U+25B6 U+FE0F` | run, start, resume, expand a disclosure | |
| ⏹️ | stop button | `U+23F9 U+FE0F` | stopped, halted, terminated | |
| 🔁 | repeat | `U+1F501` | retry, loop, recurring, repeat-all | collision with 🔄; convention: 🔁 for *repeats*, 🔄 for *sync / refresh* |
| 🔄 | counterclockwise arrows | `U+1F504` | sync, refresh, reload, update in place | collision with 🔁 — see its row |
| 🆕 | NEW button | `U+1F195` | new, recently added | |
| 🆗 | OK button | `U+1F197` | acceptable — *good enough*, as opposed to ✅ *done* or 🟢 *healthy*: the outcome nobody objects to | |
| 🆙 | UP! button | `U+1F199` | version bumped, promoted a tier — a discrete step up, where ⬆️ is the direction of a continuous quantity | |
| 🔚 | END arrow | `U+1F51A` | end of life, last entry, no successor | |
| 🔛 | ON! arrow | `U+1F51B` | enabled, switched on, feature live | |
| 🔜 | SOON arrow | `U+1F51C` | planned, upcoming, on the roadmap but not started; once it is running it is ▶️ | |

🆕 🆗 🆙 🔚 🔛 🔜 carry a **readable word** rather than an abstract shape, so they survive being
read aloud, machine-translated, or rendered in a legend nobody consulted. That is their whole
advantage; they are otherwise louder than the marks around them and belong in status columns
rather than prose.

### Direction and flow · ⬆️ ⬇️ ➡️ ↩️ 🔀

Prose keeps `→ ↔ ← ⇒ ↓ ↳`. These emoji arrows are for diagrams and status columns only.

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| ⬆️ | up arrow | `U+2B06 U+FE0F` | increase, upgrade, higher priority, sort ascending, upvote |
| ⬇️ | down arrow | `U+2B07 U+FE0F` | decrease, downgrade, lower priority, sort descending, downvote, download |
| ➡️ | right arrow | `U+27A1 U+FE0F` | leads to, next, flow, becomes |
| ↩️ | right arrow curving left | `U+21A9 U+FE0F` | revert, undo, reply, return, go back |
| 🔀 | shuffle | `U+1F500` | random order, swap, cross over; *merge branches* only by the gitmoji convention, which not every reader shares |

### Categories, tags, objects · 🏷️ 📦 🔖 📎 🧩 🗂️ 📁

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| 🏷️ | label | `U+1F3F7 U+FE0F` | tag, label, category, price |
| 📦 | package | `U+1F4E6` | release, build artifact, dependency, library, shipment |
| 🔖 | bookmark | `U+1F516` | bookmarked, saved, version tag |
| 📎 | paperclip | `U+1F4CE` | attachment, linked item, enclosure |
| 🧩 | puzzle piece | `U+1F9E9` | plugin, module, extension, component, "the missing piece" |
| 🗂️ | card index dividers | `U+1F5C2 U+FE0F` | organised, indexed, grouped, archive |
| 📁 | file folder | `U+1F4C1` | directory, folder, group of files |

### Data, metrics, development · 📊 📈 📉 🐛 ⚙️ 🧪 🚧 📝 🔗

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| 📊 | bar chart | `U+1F4CA` | metrics, analytics, statistics, report, dashboard |
| 📈 | chart increasing | `U+1F4C8` | growth, trending up, improvement, rising cost |
| 📉 | chart decreasing | `U+1F4C9` | decline, trending down, drop, falling cost |
| 🐛 | bug | `U+1F41B` | bug, defect, issue, debugging |
| ⚙️ | gear | `U+2699 U+FE0F` | configuration, settings, build, CI, machinery, automation |
| 🧪 | test tube | `U+1F9EA` | test, experiment, lab, staging, beta, unstable |
| 🚧 | construction | `U+1F6A7` | work in progress, draft, unfinished, do not rely on this yet |
| 📝 | memo | `U+1F4DD` | documentation change, notes, written up, draft text |
| 🔗 | link | `U+1F517` | related item, cross-reference, URL, dependency between two things |

📈 and 📉 name a *direction*, not a verdict: rising latency and rising revenue take the same
arrow. Where the reader could take the direction as good news, say which it is.

### Navigation and documents · 🔍 🔎 📋 🗺️ 📅 ℹ️ 💡 📢 🔊 🔇

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| 🔍 | magnifying glass, left | `U+1F50D` | search, find, inspect, query, investigate, "see also" |
| 🔎 | magnifying glass, right | `U+1F50E` | drill down, zoom in, examine one item closely — the pair 🔍/🔎 gives two distinct verbs, *find it* and *look into it*, provided the document uses them that way consistently |
| 📋 | clipboard | `U+1F4CB` | checklist, list, copy to clipboard, agenda |
| 🗺️ | world map | `U+1F5FA U+FE0F` | roadmap, overview, geography, territory |
| 📅 | calendar | `U+1F4C5` | date, schedule, deadline, planning |
| ℹ️ | information | `U+2139 U+FE0F` | information, note, FYI — neutral by design, where 💡 proposes something |
| 💡 | light bulb | `U+1F4A1` | idea, tip, hint, insight, suggestion |
| 📢 | loudspeaker | `U+1F4E2` | announcement, broadcast, news, call for attention |
| 🔊 | speaker high volume | `U+1F50A` | sound on, verbose, loud |
| 🔇 | muted speaker | `U+1F507` | muted, silent, suppressed, quiet mode |

### Infrastructure · 🖥️ 🗄️ 💾 🔌 🛠️ 🔧 🧰

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| 🖥️ | desktop computer | `U+1F5A5 U+FE0F` | machine, host, node, server, workstation |
| 🗄️ | file cabinet | `U+1F5C4 U+FE0F` | storage, archive, database, records |
| 💾 | floppy disk | `U+1F4BE` | save, persist, backup, disk; the save icon long after the medium |
| 🔌 | electric plug | `U+1F50C` | connector, plugin, integration, power, "plugged in" |
| 🛠️ | hammer and wrench | `U+1F6E0 U+FE0F` | tooling, maintenance, repair work (WIP is 🚧) |
| 🔧 | wrench | `U+1F527` | fix, repair, configure, tweak — collides with 🛠️ at table size |
| 🧰 | toolbox | `U+1F9F0` | toolkit, utilities, collection of tools |

### Miscellaneous · ✨ 🎉 🚀 🧹

| Symbol | Name | Unicode | Common uses |
|---|---|---|---|
| ✨ | sparkles | `U+2728` | new feature, enhancement, polish, magic, cleaned up |
| 🎉 | party popper | `U+1F389` | celebration, milestone, launch party; in gitmoji specifically the *initial* commit of a project |
| 🚀 | rocket | `U+1F680` | deploy, ship, launch, speed, growth |
| 🧹 | broom | `U+1F9F9` | cleanup, chore, housekeeping, removing dead code |

---

## 5. Conventions

Where §4 offers several meanings, this section fixes the one this repo uses. Each entry either
**records a live convention** — naming the document that owns it, which wins on conflict — or
**adjudicates** a collision §4 only flags. Nothing here is a menu. A concept that is missing gets
an adjudication added, not a private choice made.

### Batch summaries — owned by `/push-stage`

Slack posts summarising a promotion use the set in `.claude/skills/push-stage/SKILL.md`, not a
per-commit typology:

🚀 fixed post marker · 🆕 new capability · ⬆️ improvement · 🔧 fix · 🧪 tests · ⚙️ internal, nothing to test

Two readings there differ from gitmoji, deliberately: **🔧 is a fix, not configuration**, and ⚙️
means "nothing to test", not build/CI. This repo does not use gitmoji — commit subjects carry a
ticket id or an area prefix (`RLM-851 …`, `docs: …`) and never a glyph — so gitmoji readings are
not imported into these posts.

### Concept → glyph

The lookups a writer actually arrives with, settled once:

- **important callout** — ‼️. §4 leaves ❗/‼️ as "pick one per document"; this repo picks ‼️
  everywhere. 💡 stays *tip*, ℹ️ stays *note*.
- **blocked / cannot be done** — ⛔ on the item, whatever the obstacle, with it named in text
  (`⛔ blocked on A.3.6 creds`). ⛔ is *we cannot*, never *it failed* (❌). Not 🚫, which is
  *cancelled or rejected* (§1); not 🔴, which is severity — a blocked row is often low-severity.
- **deferred / postponed / on hold** — ⏸️, one glyph. Committed plans currently use both ⏸️ and
  🚧 for this; ⏸️ wins because 🚧 has its own job — *work in progress, do not rely on it yet*,
  an active state rather than a parked one.
- **deprecated / superseded / legacy** — 🟤 in tables, where brown reads as faded rather than
  alarming. 🔚 only for end-of-life with no successor.
- **release** — 📦 the artifact or version shipped · 🚀 the act of deploying it. Not 🔖, 🏁 or 🎉.
- **test skipped** — ➖ beside ✅/❌ in a results column: deliberately not run, which is neither a
  pass, a failure, nor an unknown. (An adjudication, not existing practice — the suite has a
  skip state and nothing marked it.)
- **security column** — 🔒 secured · 🔑 credentials · ⛔ forbidden. There is deliberately no
  glyph for *unlocked*: the one that exists reads as *open* to one person and *insecure* to the
  next, and a security column is the worst place to let a symbol flip. Write it in words.
- **repeat vs refresh** — 🔁 retry, recurring · 🔄 sync, refresh. Restated here because it is the
  catalogue's most frequent mix-up.

### Conventions owned elsewhere

- `doc/infra/main-server-inventory*.md` — **💾 = HDD** media class, ⚡ = NVMe, plain SATA SSD
  unmarked; `∅` = below display precision (§1). A backup is written there as a word, not as 💾.

---

## 6. Variation Selector-16

Symbols with both a text and an emoji form carry a trailing `U+FE0F` to force the coloured
rendering: ⚠️ ℹ️ ✔️ ✖️ ♻️ 🖥️ 🗄️ 🛠️ ⚙️ ‼️ ⁉️ 🗺️ 🏷️ 🗂️ ✳️ ⏸️ ▶️ ⏹️ ⬆️ ⬇️ ➡️ ↩️ ❤️.
Without it they render as monochrome outline glyphs and lose the only property they were chosen
for. Circle and square emoji (`U+1F534` and friends) are emoji by default and need no selector.

The **Source literal** column shows what to write; the **Rendered result** column shows what the
runtime or browser displays.

| Runtime | Source literal | Rendered result |
|---|---|---|
| HTML | `&#x26A0;&#xFE0F;` | ⚠️ |
| JavaScript | `"\u{26A0}\u{FE0F}"` | ⚠️ |
| Python | `"⚠️"` | ⚠️ |

Rendering is not uniform across platforms: the same code point differs in colour and weight
between vendors, and monochrome terminals drop the colour entirely. A glyph is a fast index
into a document, never the only place a fact is stated.