MeshTerm/CLAUDE.md

MeshTerm — working notes for Claude

MeshTerm is a full-featured TUI MeshCore client for your terminal. The UI is a prompt_toolkit session rendering Rich content (meshterm/ui/), tools register into a menu (meshterm/tools/), services run in the background (meshterm/services/), and everything heard is recorded to SQLite (meshterm/persistence/).

Run the tests with python -m pytest -q. Screens must stay readable at each platform's readable_cols — 72 regular, 53 PicoCalc (see Platforms below); the dual-platform gallery test (tests/test_gallery.py) is the enforcement point, and every picocalc case is a hard gate.

Git workflow

Commit directly on main — do not create topic branches unless explicitly asked (this is a solo repo; branches just create divergence to merge back later). Commit freely, but never git push unless explicitly asked in that moment.

Licensing — what every file and every build carries

• Every Python file opens with # SPDX-License-Identifier: Apache-2.0 (line 2 after a shebang). tests/test_spdx.py is the gate. Anything under another licence lives beside its own text and says so in its header — the GPL-2.0-only console-font script, the MeshCore MIT notice beside the XIAO patch — and never enters the distributed package.
• The map credits OpenStreetMap in the map's own bottom-right corner (ui/attribution.py): the full OpenFreeMap line on arrival, © OpenStreetMap after the first keystroke, muted, on both platforms and in the same words. Which corner is the frame's, not the drawing's, wherever the frame has one — regular sets the credit into the panel's bottom border rule, right-justified, one rule cell before the corner, the way a title sits in the top rule (Screen.bottom_caption → frame._panel_box), so the map's cells are untouched; picocalc, whose frame has no bottom rule at all, stamps it over the right end of the drawing's last row instead, overprinting what it covers. The minimap always stamps. The split is bound once via platforms.on_platform, never asked per frame. Never a title atom, never a footer character, never a key. The licence and URL live on the About page.
• The name and the wordmark are trademarks reserved in NOTICE, which Apache §4(d) makes every fork carry; NOTICE holds only what must travel with a redistribution.

UX standards

These are binding. Every new screen, dialog, row, or hint follows them; when you touch an old one that doesn't, bring it along. The enforcement points live in code — build through them instead of hand-rolling:

• ui/menus.py — exit_rows, menu_rows, lane_row, section_heading, confirm_discard, fit_cells.
• ui/markdown.py — render_markdown (THE prose renderer: a page of writing, drawn in the language below).
• ui/widgets.py — highlighted_hash (THE key widget — shows a key, lights its hash), format_ago (prose ages), format_age (column ages), channel_glyph, NODE_GLYPHS, heard-age heat colouring.
• ui/theme.py — name_style/node_style (per-node hues, hash-derived), snr_style, the you white.

Lexicon — one term per concept

Term	Meaning
node	any device on the mesh — a radio broadcasting packets; roles: companion, repeater, room server, sensor. The umbrella term
contact	a node your device knows: discovered (heard broadcasting, not yet added) or added (in the contact list, messageable). Every contact is a node; not every node is a contact
heard	received from ("last heard", "first heard") — never "seen" in UX text
key	the full fixed-length value — a node's public key, a channel secret
hash	the short derived id — a key's first path-hash-mode bytes (the slice highlighted_hash lights), a channel hash, a path hop
path	an ordered hop spec you compose or force (a1,3d,…)
route	the concrete node sequence a trace walked or will walk
via	prefix for a packet/message's relay chain
region	a named area a repeater relays floods for (region put yul); shown bare, never #yul — the # belongs to key derivation only
scope	the region a flood is limited to — a packet's, a channel's send scope, the device's default scope. A direct packet has none. MeshCore's sense and the only one: the menu's This node / Other nodes / This app sections name whose a setting is, never a "scope"
unscoped	a plain flood, relayed by any repeater that allows the wildcard *
Back	leave the current screen/list — Esc's word, and a row's only where leaving is a choice (see below)
Quit	leave the app (main menu, device splash) — nowhere else

Node vs contact — the boundary: node is the hardware/participant sense — the map, mesh walk, heard-nodes, relay hops, graph vertices, and node types (companion/repeater/room server/ sensor) all speak "node". Contact is the saved-identity sense — the Contacts screen, the courier recipient, anything you address. The reception/persistence layer (observations.node, HeardNode, heard_nodes(), trace_hops.node) stays "node"; the sortable list you pick from is contactlist.py (ContactListScreen/ContactRow/ ContactsSort/contacts_table). The contacts tool lists the device's added contacts.

Setting vs preference — the other boundary, three-way and never blurred: a setting is the radio's (core/device_config.py, read live from the companion, edited on Device config); a preference is MeshTerm's own behaviour (core/preferences.py, defaults in code, overrides in preferences.toml, edited on the Preferences page — ctx.preferences, or preferences.current() where there is no context to reach through); and config is machine setup — paths and device profiles (core/config.py, config.toml, a text editor only). A behaviour value belongs in the preference registry, not as a module constant and not in config.toml: a code constant a reader can't reach is a preference nobody has.

What MeshTerm writes, it writes from what it knows: a store reads its file into typed records and writes back out of them, never the raw document it read, so a field no record knows (retired, or invented by a hand edit) is gone at the next write — every *_store.py and preferences.toml work this way, and the settings store keeps only keys device_config still registers, since it offers them back to the radio. And a name that leaves is retired for good, never reused with another meaning, because a value can outlive its key in a file nobody saved since, and an old 30 that passes a new spec means something else undetectably. A preference key goes in preferences.RETIRED (loading refuses it; report_dropped logs what the next save will drop); a stored field goes in its record dataclass's own RETIRED set — the record is the path, not the leaf. tests/test_retired.py fails any live name found in either. Units live in the name (_s, _hours, _db), so a changed unit is a new name by construction.

Relative ages: format_ago for prose ("now", "5m ago", "never" — never "now ago"), format_age for aligned columns ("now", "5m").

Navigation — the stack

Navigation is a strict stack: entering a screen or a dialog pushes one frame, Esc pops exactly one, and the frame you land back on is the one you left — same object, so its cursor, sort, scroll and typed filter are simply still there. Exceptions are added deliberately, one at a time, and say why in the code.

• A screen that owns a loop is a hub, and a hub stays pushed for the whole visit: async with session.stay(screen) as visit: / while True: x = await visit.result(). One push, one pop, however many rounds. Never pop-and-re-push a screen to give a dialog a backdrop — a screen that never left the stack already is one. run_screen remains the one-shot form: push, await, pop, for a dialog or a prompt.
• A sub-view nests; nothing flattens the stack to spare the reader a climb. Two peers may open each other (trace ↔ trophy case) and that cycle is fine — ^W is the climb.
• A list whose content is data (an editor's staged values, a queue that lost a row) refreshes in place with SelectScreen.replace_items, which follows the highlighted row by value and keeps the filter. Rebuilding the screen is for when the rows it was holding a place in are genuinely gone (a purge, a delete) — and then say so.
• A popup is not a place. The stack is for places — full-frame screens the reader is in (a menu, a map, a list that is the tool's own page, an editor). A popup informs, confirms, or asks, and then it is gone: it is never kept pushed as a hub under the screen it was gathering for, so Esc from that screen lands where the tool was launched from, not on a picker. The test is whether the reader is in it or being asked something — a SelectScreen can be either (Channels is a place; "node to manage" is a question). A question draws as a box even when it is the only frame on the stack (the main menu is popped while a tool runs, and a lone floating screen would otherwise be painted full-frame): session.select(floating=True), session.text(floating=True), session.stay(screen, dialog=True) — all through TuiSession._floated, which puts a blank base under it.
• An entry chain is a stack too. A flow that asks two or more things in a row runs through menus.run_steps: each step gets the answers so far (to label itself, and to offer its own previous answer as its default) and returns None to step back, so Esc undoes one step instead of the whole flow. A trailing Cancel/verb confirm is still a decision, not a step — its Cancel abandons. Where the steps are lists to pick from, the chain is one popup that turns its page — menus.run_wizard over WizardPages (SelectScreen.turn_page; title Feature — subject · step 1 of 2), never two popups stacked. Esc on a later page turns back one, with that page's previous answer highlighted; the box is popped before whatever the answers were for opens.
• Esc peels before it leaves. A screen carrying a find-as-you-type filter treats the typed query as the most recent thing the reader entered: the first Esc clears it and the screen stays, the second leaves. One rule on all four (SelectScreen and everything built on it, the path composer, the map, the mesh walk), and the footer says Esc clear for as long as it is true. Chat is the same shape with a different peelable thing — its first Esc unpicks a selected message. It used to be a 2–2 split, which put opposite outcomes behind the same keystroke on the same affordance.
• ^W unwinds every frame back to the main menu, ^Q asks to quit from anywhere: it floats the same confirm the menu's Quit row opens, detached over whatever is up so nothing under it stops, and a second ^Q while it asks leaves at once (TuiSession.request_quit; ^Q sits one key from ^W). Both are answered in TuiSession._dispatch, and neither is advertised — a global verb has no screen to belong to, and the F-key lane has only three free slots per screen — except ^Q quit? on the main menu's own hint, where Esc is inert and the reader looks for the way out. On picocalc that atom rides the title bar's tail (frame._way_out), and the menu's lane puts the way out on F3: Quit? asks, its Shift half F8 Quit! leaves without asking (quit_now, the one door that skips the confirm, and only on the menu). The confirm keeps the chip that asked: its F3 reads Quit! and sends the same quit, which with the question up is the leaving — one key pressed twice, as ^Q is. test_navigation walks every string literal in the package to keep them out of the rest of the UI.
• Esc at the main menu does nothing but peel a typed filter: the menu is the bottom of the stack, so Esc-mashing up to it settles there. Leaving is the Quit row or ^Q, both behind the confirm. ^W arms every frame on the stack, not just the top (request_pop_all), stopping at anything modal: a screen opened from a key handler — the packet viewer, the chat's delivery paths, a trace path flow — runs in a task no navigation frame awaits, so an unwind sent only to the top died there while the hub below sat on a visit.result() nothing would resolve. Such a flow is launched through session.run_detached, which absorbs the duplicate PopToMenu its task cannot carry; the stack is what the unwind actually travels down.
• modal is owning the keyboard (a prompt, progress, a busy splash); floating is only drawn as a box. They are not the same flag: a select list floats and is not modal, the busy splash is modal and does not float. ^W declines to unwind past anything modal.
• A caller tests one thing for "the user left": CANCEL (or the None that ui.select folds it to). POP_ALL never reaches a caller — the navigation boundary turns it into PopToMenu, which derives from BaseException so it crosses the app's except Exception tool guards; only the menu loop catches it.

Screens and lists

• No screen carries an exit row. Esc leaves — it is on both platforms' keyboards and every footer hint says so — so a row that only repeated it was two lines out of every screen (a row in thirteen on the PicoCalc's 26) buying nothing. Lists end on their last content row; a hand-drawn action list ends on its last verb. The gallery enforces it: no rendered line may be the bare word Back.
• The exception is where leaving is a choice rather than an exit, which is the same rule that keeps a dialog's Cancel button. exit_rows(staged, …) draws nothing while clean and, once changes are staged, one blank Separator(" ") line then ✓ Apply n staged changes over ✗ Back — discard staged changes — Apply has no key of its own, so it needs a visible counterpart naming what the other way out costs. Same shape in ReorderScreen. A Quit row is likewise kept (main menu, device splash): it initiates the app's terminal action behind a confirm, and on the splash it is the only statement that the app can be left at all.
• An editor has one of two shapes, chosen by who holds the change. Where MeshTerm holds it until told (Device config, Preferences, Repeater admin's settings), edits are staged and nothing reaches the device until Apply — the exit_rows shape above. Where the device holds each edit live in RAM until its own save command (a repeater's region table: every edit takes effect at once, and a reboot undoes whatever region save did not persist), edits apply immediately and the page is live, then save: the title counts unsaved edits (· 2 unsaved), the page ends on the same shape reworded — ✓ Save n changes to the … over ✗ Back — a reboot undoes them — and Esc with unsaved edits asks first (amber). Never stage what the device already holds live: the edits depend on each other there (a region must exist before it can be allowed), and a stage would have to re-implement the firmware's rules to order them. ui/region_editor.py is the reference.
• A cursor clamps at both ends — nothing in the app rolls over. ↓ off the last row and ↑ off the first stay put, in a select list, a hand-drawn action list, a reorder list, a dialog's button row, everywhere. The window follows the highlight, so a roll hauls the whole list back to the other end and flips its edge markers: the one move that reads as the screen changing under you rather than as one step, and held-down arrows should settle at an end rather than loop. The exception is a forward-only key with no reverse of its own, which cycles or it dead-ends — Tab on a button row, and the picocalc F-lane's single-chip advancers (Sort →, the node page's tab chip, the Time Machine's window chip). Those state it in the code.
• Edge scroll — what a clamped arrow does instead. With the highlight on the first selectable row, ↑ scrolls the page up a line, and on the last, ↓ scrolls it down, until the page's real top or bottom is in view: whatever sits above the first row or below the last (a node's vitals, a list's lead-in, a closing note) can always be reached. Home and End go to the page's very top and bottom with the highlight. The frame stops following the highlight while a page is edge-scrolled, so it may leave the screen — deliberately. The snap-back brings it home: while it is out of view, a key that would move it or act on it (the other arrow, Enter, Delete) only brings it back into view, jumping if it must, and does nothing else — nothing runs that can't be seen. Any other key ends the edge scroll. It lives in Screen.edge_scroll, which the session asks before handle; a screen opts in by answering cursor_at_edge (Screen.row_at_edge for an index over rows), and one whose ↑↓ move no highlight (a prompt's history recall) leaves it None.
• Grouped-list section headings use section_heading("Label") → ── Label ── in the bold heading grey, never the frame's accent: a rule in the border's colour reads as part of the frame. A chat's day divider wears the same dress. That is also what makes a heading sticky (it pins to the top row while its section scrolls, and the ^PgUp/^PgDn jumps step by it), so build them through it — a hand-rolled Separator is no landmark. Prose written directly under a heading (a description of what the section holds) is its preamble and pins with it, in order, as each row scrolls off; prose after the section's first row labels nothing and never pins.
• Label + description command rows go through menu_rows (two cell-aligned lanes, description muted). Editor rows (setting/value/description) go through lane_row.
• A row that opens further prompts ends with …; a row that acts immediately doesn't.
• A bare-letter shortcut only where nothing is typed. A screen that filters, finds or composes as you type has no free letters, so its verbs are Ctrl chords — one table, session._CTRL_LETTER_CHORDS, each letter the mnemonic of its action (^P paths, ^U URL, ^Y you). A screen that takes no typing may spend a bare letter instead (the Time Machine's w, the dashboard's s, the device splash's h). Either way the key is named where it acts: in the hint, and on the PicoCalc's lane.
• Empty states are lowercase muted, optionally — explanation, never parenthesized.
• Body section headings inside screens: accent title, optional muted · note.
• A find-as-you-type screen echoes its live query as /query in warn, on its own body line directly above whatever the query narrows — render.query_line is the one definition (select list, path composer, map, mesh walk). A screen that also carries the query in its footer hint draws the body line only where the footer isn't drawn (Platform.footer_fkeys), never both: the query must be visible on every platform, and twice on none.
• A QR code is white on black, and when it is the answer it is the whole screen. Modules are pure white ink on a pure black field whatever theme the terminal runs (qr._STYLE, both ends named) — a camera reads contrast, light-on-dark is what a scanner expects of a screen — and never black on white. A share screen (qr.share_screen → qr.QrScreen: the channel share, the contact card, the CLI's share commands in the menu) is a bare frame: Screen.bare / frame.compose_bare draw the body alone on blank rows — no header, no footer, no title bar, no box, no hint, no F-key lane, no instruction — with nothing on it but the code and the URL it encodes, sat a little above centre; Esc leaves, as everywhere. The code fits itself to the frame every paint, width and rows both: a lighter error level, then a narrower quiet zone, before it would ever be cut (a contact card is 57 cells and 29 rows at the standard fit in half blocks; a regular terminal is 24 tall), and when code and URL can't share the frame the code is whole at the top and the URL a page down. A chat message's links open there too, on every platform: ^U on the picked message, and with several, one code at a time that ←→ step through, clamped. That screen's URL line is flanked ←/→, lit toward another code and dim at an end — the one mark the bare frame carries beyond the code and its URL, because nothing else could say the others are there. On the Cardputer it is the only way to a link's code, as on the desktop: its 14 rows have none to spare under every message that carries one, and its braille code is small enough that a link and its code share the panel. Two codes sit inline instead: a ```qr fence in a written page, where the code is an illustration drawn in the prose where the fence is, and — on the PicoCalc alone (Platform.url_codes) — a chat message's URLs, each drawn as a code under the message at its body's indent, side by side, wrapping onto a new band when the line is full (qr.qr_strip). A picked message keeps the codes under it in view. Where the font draws braille solid (Platform.solid_braille: the PicoCalc's built fonts, the Cardputer's console host, host/font.BRAILLE) every code — share screen, page fence and chat alike — is drawn in braille, one module a dot, eight a cell (qr._GRID), so the contact card is 29 cells by 15 rows there and shares the 53×26 panel with its URL at the standard fit.

Written pages

A screen that is prose (the three About pages) is markdown, not composed rows: the text lives in meshterm/assets/pages/*.md and ui/markdown.py draws it in the language above — # the page's own name in brand, ## a section in the body accent (## Title · note gives it the muted aside), ### a sub-heading indented with its prose, paragraphs and lists hanging as blocks, quotes and fences behind a rail that survives wrapping, links showing where they go (nothing is clickable on a framebuffer console). Two paragraphs are page frame rather than body and sit flush and muted: the standfirst under the # title and the colophon, the last paragraph under a closing ---. Live package facts arrive as {version} / {author} / {copyright} placeholders, filled as the page opens. The ## headings are the page's landmarks — they pin and the section jumps step by them — so a written page earns Sect ↑/Sect ↓ on the F-key lane exactly as a grouped list does. Filling a page in is editing its .md; no Python follows.

Titles

• Sentence case, always ("Trace — Lakeside", "Nodes", "Path width", "Admin login").
• No emoji in any screen or dialog title — icons live in menu/list rows. (A terminal that draws an emoji narrower than Rich measures leaves a content-sized dialog's border short.)
• — (em dash) introduces the subject/qualifier: Feature — subject. · chains status atoms: Map · z12 · 34 nodes · 2.1 km across.

Footer hints

• ≤72 cells. Sentence shape: navigation keys, then action keys, Esc last.
• Esc verb by surface: Esc back leaves a screen · Esc close dismisses a read-only floating view · Esc cancel abandons a prompt/dialog · Esc keep leaves a value picker unchanged · no Esc atom at the main menu, which ends on ^Q quit? instead · Esc bye only on the device splash, which is the door rather than a screen — nothing has been started there to quit out of. While a find-as-you-type filter is standing the verb becomes Esc clear, because that is what the press does then.
• A hint that outgrows the surface drawing it sheds atoms rather than being cut off, because the cut takes the end and the end is Esc (frame.fit_hint, the chromeless splash). They go from the right, in front of Esc; a screen may name the ones it can spare first (spare_hint_atoms) — a key the reader would find anyway, like the ←→ its move atom already named, before one that is unguessable and advertised nowhere else.
• Enter verb by action: Enter open when the row pushes a screen or dialog · Enter select when it picks a value or action row · Enter set in a value picker. A more specific committing verb (Enter adopt path, Enter add) is fine; a synonym of the generic three (pick, choose, commit) is not. The filter atom is always type to filter. A button row is the one place the specific verb is barred: Enter commits whichever chip is highlighted, so the hint stays ←→ choose · Enter select · Esc cancel — Enter quit on the quit confirm was true only until ←→ moved, and hid the key that moves it. A lone-button acknowledgement names its verb (Enter OK) and offers no ←→, having nothing to choose between.
• A hint is drawn once per frame, and which surface draws it is the footer's call. Where the footer is the hint line (regular) it carries the top screen's hint, so a floating dialog's border stays silent — the same sentence in the border and at the bottom of the terminal was one of them wasted — and its clip arrows fall back to the base frame's ↑↓ more. Where the footer is the F-key lane (picocalc) there is no hint line, so the border is the only place Enter/Esc/the arrows can be named and it keeps the hint, less every atom whose keys are all chips on the lane one row below (fkeys.strip_lane_atoms via frame._dialog_hint, resolved per paint — a screen rewrites its hint as its content changes and reads its lane fresh every frame). The chromeless splash has no footer row of any kind and keeps its hint in its own border on both platforms.
• Key notation: ↑↓ move (include the verb), ^R/^End for Ctrl chords, ⌫ for backspace, ⇧ for shift.
• An arrow atom leads the hint and names only the arrows: what they do (↑↓ move, ←→ choose, ↑↓ newer/older) or what they move (←→ slot). Several keys share one atom only when they do the same thing — ↑↓ PgUp/PgDn scroll, Home/End ends; a key that does something else gets its own, which is what ←→/Y/N choose and ↑↓ Tab complete had wrong (Y/N answers, Tab completes, neither is what those arrows do). The subject must be the right one, too: cursor is the row ❯ points at, so the composer's ←→ moves its slot. Every button dialog carries the same hint, ←→ choose · Enter select · Esc cancel — a yes/no prompt is a button row like any other, so its y/n accelerators ride its Yes/No labels rather than the line.

Dialogs

• Modal popups over the pushed backdrop (never full-screen replacements).
• Buttons are reverse-video chips ( Label , selected style): safe way out on the left, the committing verb on the right and default, so Enter commits and Esc backs out. Two escalating caution tiers theme the frame: danger=True (amber) for a disruptive choice — discard edits, reboot, show private key — and destructive=True (the reserved red) for irreversible data loss, so a delete confirm reads red like its typed_confirm sibling. Bulk or irreversible deletions gate behind typed_confirm (also red); a single-record delete is a red Cancel/Delete confirm.
• Confirms are Cancel/Verb button dialogs, not Yes/No. Prompt lines that ask for input end with a colon.
• Dialog title is short; the question/instruction goes in prompt.

Marks and icons — one glyph per concept

• Status marks (single-width, themed): ✓ ok · ✗ err · ⚠/? warn · ● unread/ unacked (err) · ○ acked/empty (muted). Never ✔, ✖, ✅, ❌ as status.
• Node types (shared with the map): ★ you (yellow) · ● companion · ▲ repeater · ■ room server · ◉ sensor · ○ unknown.
• Path cuts: a path line drawn as chips that gets cut — a lane that ran out, a row scrolled past its edge — breaks the chip off on a half block in that chip's own fill (▐ ends a line, ▌ opens one; pathline.cut_mark/cut_to), so half the cell is segment and half is bare page. An ellipsis would say a word was shortened; the crack says the segment continues. Arrow-drawn paths keep the … — nothing to shear. Distinct from ⋯, which marks whole hops elided out of the middle (PathLine.ellipsized).
• Path endpoints: a path line runs between the nodes it actually went between — the true origin and destination, never the first and last relay. Our own end is always the app-wide ★ (pathline.SELF_GLYPH, taken straight from marks.SELF_MARK), never our name: the one node the reader never has to be told, and the cells belong to the hops that differ from row to row. As a chip it is the map's yellow star on neutral dark grey, padded like every other chip.
• Chip seams are one interlocked chevron (previous fill on next). Two chips of the same fill are the exception the interlock can't draw — and so are two fills the eye can't tell apart: under pathline.SEAM_BLUR apart in OKLab (ui/oklab.py, THE perceptual colour distance — never a hue gap, never sRGB, both of which mis-size the greens against the cyans). There the seam is the thin chevron (POWERLINE_THIN) in the previous chip's own fill shaded SEAM_SHADE darker (lighter for a dark fill), drawn on the next, so the ribbon runs on unbroken and the join is a line the chip draws on itself, never a wedge of page cut out of the route and never a third colour. An elision breaks the ribbon rather than joining it — bare ⋯ on the page between a closing point and the next chip's notch, no fill, no padding.
• The ribbon's outer ends: the chevron means the route continues, so an end that is the route's own never wears one. It ends square — nothing appended, the last chip's own pad is the edge — and opens square the same way; a full Nerd Font rounds such ends into a lozenge instead (POWERLINE_ROUND_*, drawn only where termfont.powerline_full). Two things put the chevron back, and either is enough. A wrapped line the path outruns closes on the point: there the route really does go on. And a line drawing only the middle of a route — a packet's via chain, the TX sweep's composed relays: hops that are neither the node the frame came from nor the one it reached — opens on the notch and closes on the point, because a square end is the promise that the chip beside it is where the route began or ended (PathLine(from_origin=…, to_destination=…), defaulting to a whole route). Arrow mode spells the same claim with the separator alone, a leading or trailing → with no hop on the far side of it.
• Concept icons: 📡 advert · 🕒 clock/sync · 🔄 reboot · 💾 backup · 📂 restore · 🔑 channel/credential key · 🔐 identity/auth secret · 🔒 lock (a locked contact, a private channel) · 🔓 unlock · 🗑 clear/delete · ✎ compose/edit · ⚙ parameter · # count · ▶ run · ⚡ explore/probe · ★ best/winner · ⭐ watch · 📤 send now · 📨 courier/queue · 💬 chat · 🔔 notify · 🔕 mute (notifications off) · 📱 QR · 🔗 link · ↻ re-read · ↕ reorder · ⇄ reverse (flip a path's direction) · 🔖 region/scope · 🏆 trophy case/record · ⌨ command line · 📖 read/about · 💰 support/donate · 🚪 quit. Packet-class icons (feed/viewer lane): 📢 advert · 📊 telemetry · 📦 packet · 💬 message · ✅ ack. Raw payload classes (PAYLOAD_ICONS): 📻 channel text · 💽 channel data · 📩 direct message (overheard) · 📥 request · 📮 response · 🎭 anon request · 🧭 path · 🎯 trace · 🧩 multipart · 🧰 control · ❔ unknown — raw advert/ack reuse 📢/✅.

Colour

• Node names are always coloured: name_style(name, key) palette hue, derived from the node's key (its first byte — any known prefix agrees) so a rename keeps the colour. One rule on every platform; only the resolution changes (see Platforms). A surface holding only a name resolves it first (make_name_key_resolver); a node no key can place — an unresolved sender, a bare hash standing in as a name, an ○ ring — takes node.unknown, THE light grey for an unidentified node, everywhere and on both platforms. Colour is reserved for keyed identities, never seeded from a name's characters. node.unknown is deliberately not muted: muted is chrome and may sit a step darker, while an unidentified node is content you can still act on. Our own node is the pure-white you style; a context colouring (chart quality) may still win.
• White is what "you picked this" looks like, and nothing else in the app is allowed to say it. The cursor row — the row ❯ points at, in a select list or in a screen drawing its own rows — wears cursor (white), never brand: the wordmark's teal is the app's identity, not a selection, and teal/cyan is itself a node hue, so a cyan-keyed node used to vanish into its own highlight. White is outside the node spectrum, so it can never collide with an identity. The same white lights the active sort column's heading and triangle (contactlist._SORT_ACTIVE, widgets._sort_header) — the same claim one axis over — and the path composer's insertion-slot chip, so the row you pick and the slot it lands in read as one gesture. It rides under the row's spans, so every lane keeps the colour it set — an age's heat, an SNR reading, a red badge — with the one exception the highlight exists for: a node's key-derived hue folds to the cursor white on the cursor row (theme.is_identity_style → render._whiten_identities, applied once at the render boundary for any Text whose base style is cursor), so the highlighted row reads as one thing instead of as a name arguing with its own selection. Only a keyed hue folds: node.unknown's grey stays grey, because the highlight must not claim to know a node we can't place. A path line is spared wherever it sits on the row — there a hue is not decoration on a name, it is what tells one hop from the next and what a route graph's one-byte labels are matched by — so pathline stamps its own extent (PATH_INK, a style that draws nothing) and the fold skips what lies inside it. That is what makes the arrow form say what the chip form always said, its fills having never been in the fold's vocabulary. Reverse-video chips — a dialog's committing button, a running action's Abort, the arrow-mode composer slot, the editor cursor — are the selected fill, a grey block (muted's slate; light grey slot 7 on the VT, the one grey a reverse can put behind text there, and the same fill the F-key lane uses). A chip marks where a press lands; it is chrome, and it does not get a hue. Recency heat colours heard/first-heard ages, never names — seven steps on plain human boundaries (widgets._HEAT_STEPS), each heat.* style named for how old the node it colours is: white under 5 minutes, then yellow, light red, brown, red, light grey, and one cold grey shared by "over a year" and "never heard". A key lane (via highlighted_hash) lights its hash in the same key-derived hue; the rest of the key, and any key standing in as a name, stays muted. UX text says "key" for the lane and "hash" only for the short derived id — never "hash" for a truncated key.
• SNR always through snr_style; timelines oldest→now left-to-right, grey baseline = 0, drawn via ui/braillechart only.

Layout

• Wrapped labelled rows hang under their value block (two-column grid), never column 0. The one exception is a URL, which is never cut where the screen can hold it: one too long for its hanging lane steps out to the gutter on a line of its own (render_hanging(whole=…, gutter=…)), since a terminal opens a link, and a reader copies one, only while it sits on one line. Only a URL wider than the screen folds. A link is what core/links.py finds, and nothing guesses beside it: a scheme (scheme://…), or a host written without one where nothing else could be meant — starting www., or ending in a TLD IANA has delegated (assets/tlds.txt, the registry verbatim; refreshing it is downloading it again). So meshterm.net is a link and file.txt is not. A scheme-less link opens, and encodes, as https://….
• A chart that is a row's last column shortens to fit, on every platform: drawn in whatever cells the lanes before it leave, its oldest buckets dropped so now stays on the right, never cut by the row's ellipsis — and left out when no cell is left. The row title takes the render width to know it (Choice.title as a one-argument callable; channels._slot_text is the reference), and the header's label gives way the same way (("ACTIVITY", "ACT", ""), gone with the chart).
• Dialogs anchor slightly above true centre, sized for their populated state.
• Radio traffic: single transmissions or a user-chosen sample count with cooldown pacing — never bursts.
• A channel message goes out through Device.send_channel_in_scope, never send_channel_message directly. The firmware has no per-channel scope, only one session scope that every flood uses, so a channel's scope is a window: set it, send, restore, under the transmit lock (Device.transmitting()) so no other flood slips out inside it. A direct send skips that window without an error and the message floods everywhere; a refused scope raises FloodScopeError and sends nothing, never a quiet unscoped send. Any new command that can transmit a flood holds transmitting() too.

The command line — one answer, two faces

Everything above describes the menu, which is read by a person sitting in front of it. The command line has two readers and it no longer pretends they are the same one: the plain face is for somebody at a prompt who typed a command to find something out, and the JSON face (--json) is for a program, often on another machine and often later.

The seam that makes two faces possible is the rule everything else here hangs off:

A tool states its answer as data. A renderer turns data into bytes. The CLI boundary picks the renderer.

exit_code already worked this way — the tool states it, the boundary turns it into a process status, no tool calls sys.exit. The answer travels the same way now. A tool that prints its answer has given it away: it is rendered and gone by the time anything could offer it in another format, which is why --json reached two commands out of twenty and stopped, each one growing an if ctx.json_output: branch above the rendering that restated the whole answer in a dialect nobody else could reuse.

• ui/report.py — Listing (records) and Facts (one thing, key by key). A row holds the typed value (6.0, None, a datetime), never a formatted cell; each Column carries both projections, a plain Lane and a JSON function. A Facts block also covers the one-scalar answer, through shape=BARE (config get prints its value alone because the caller named the key) and the acknowledgement, through shape=SILENT.
• ui/fields.py — the shared shapes, one constructor per concept: node, channel, position, route, spec, when, instant, snr, flag, free. A listing that mentions a node asks for fields.node, so every document speaks the same five-key object and every listing names its lanes the same way — by construction, not by review. fields.node is the one that earns the design: one machine key expands to as many plain columns as the surface has room for, four in contacts and one in a hop table.
• ui/renderers.py — PlainRenderer and JsonRenderer, chosen by ctx.output. A third format is a new renderer and nothing else: no tool is touched, no report changes. ctx.output is an OutputFormat, never a boolean, because the boolean was already being asked questions it could not answer.
• ToolResult.report is None for the menu path and for a feature with no scripted face (the map, the dashboard). It is not summary: that is the run log's record of what an invocation did, written to the runs table on every execution, and folding a five-hour monitor capture into it would be the price of one field fewer.
• ui/surface.py is untouched by all of this. PlainUi/TuiUi is the menu-vs-terminal split and stays exactly what it is; a report is returned, not shown, so ctx.ui never grows a report() method and TuiUi never sees one.
• Streaming is a second, narrower seam and deliberately not the general path: monitor and chat listen run until a window closes, so their answer cannot be a value handed back at the end. They open renderers.stream(...) and emit one typed row per record. Two commands use it; anything that can build a whole report builds one.

The plain face — for a person at a prompt

It is still a Unix utility's output — one record per line, no colour, no frames, stdout is the answer, the exit status is half the report — but every rule that existed only to make splitting safe has gone, because splitting is the machine face's job now. meshterm/ui/script.py is the whole vocabulary and carries the reasoning; the rules:

• Alignment is the delimiter. A name is bare (script.name). The escaping under the quoting stays and always will (script._escaped): a node broadcasts its own name and a stranger fills in a message body, and neither may end the record it sits in.
• A time is an age — now, 5m, 3h, never (script.age, delegating to widgets.format_age so the two faces cannot drift). An absolute instant survives where the instant is the fact (script.stamp, fields.instant): the device clock, an appointment set with --at, a live capture's own TIME, every column under --absolute. --absolute is an override of the cli_time_format preference, not a switch beside it — behaviour belongs in the registry.
• A route is drawn and a path is typed. script.route joins hops with →; a hop is Name (hash), or whichever half is known, never an empty (). script.spec is the comma-joined hex --path takes back, and it is the one line on either face that round-trips, so nothing creeps into it. Our own node is a hop like any other — the menu's ★ says "you already know who this is", which is true of the reader and false of whoever opens the file afterwards.
• unknown is a word and - is an absence. script.NONE is the one token for absent; never is a value (a node not yet heard is a fact). A node type stays the word repeater — a monochrome ▲ would need a legend and the CLI has no legends.
• A live stream pins its lanes (script.stream), because a capture cannot measure columns it has not seen. A value wider than its lane overruns and pushes the row right; nothing is elided, and the one unbounded field goes last so it can push nothing.
• A value that round-trips is untouchable. config show prints what config set takes — an enum's number, "" for an empty string — and gains nothing cosmetic. fields.rendered carries the typed value beside the text its own spec produced, so neither face parses the other's output.
• No wrapping, with one exception: the four written pages (about, about-author, discord, support) draw on a script.PAGE_WIDTH console. The no-wrap rule exists so a record is never split with its fields under the wrong headings; a paragraph has no fields, and unwrapped it is a 600-cell line no terminal can read. Never wrap a listing.
• stdout is the answer; everything else is stderr — errors (meshterm: what went wrong), progress bars, log records, ui.ack, and a ToolResult.message. The last two used to be dropped; stderr keeps the promise the dropping was made to keep (a redirect catches only the answer) while giving the person at the prompt back their ✓ and their count. script.stderr_console() stops wrapping off a terminal, because a sentence folded at 80 columns is a sentence grep cannot find.

The JSON face — the machine contract

--json prints the answer itself, and the report a caller needs is still $?.

• No envelope. An array for a listing, an object for a set of facts, so contacts --json | jq '.[].node.name' reads what it looks like. A multi-block report is one object: each Listing under its own key, each Facts merged at the top level.
• One compact line, \n-terminated, UTF-8 with no ASCII escaping, keys in the order the report declares them. A stream is one document per record, all the same shape — no discriminator, because every reader would pay for it and only a stream would use it.
• Absent is null, never an omitted key, and typed values throughout: 9 not "9", false not "false", a body raw and unescaped. unknown becomes null; a consumer already has one spelling for "nothing here".
• Timestamps are UTC, RFC 3339, Z, to the second — twenty characters, so string comparison is time comparison. --absolute does not touch this: a local offset is a fact about the machine that ran the command, not about the event.
• A numeric field carries its unit in its key (snr_db, uptime_s, rtt_ms), never in its value, and a key/hash is lowercase hex. A key is never truncated — a truncated key cannot go back into --to or --path, so a short id is a hash.
• --json changes the rendering, never the report. Same exit status, same records. An empty result prints its empty document ([], or the object with its nulls) and still exits 5; a failure prints nothing on stdout and keeps its sentence on stderr.
• "Prints nothing" is never a legitimate JSON answer. A command whose plain face is silent (config advert, channels join, courier cancel) still emits what it did.
• A command with no data face refuses, loudly. --json specimen is a usage error (exit 2): its output is the colour, and a document of it would be a lie or an empty gesture. So is --json with no subcommand. The map, the dashboard, the live feed, the watchtower and the mesh walk have no subcommand to refuse from, and that stays the honest answer rather than a degraded one.

The exit status is the report

core/exitcodes.py, and the --help epilog: 0 ok · 1 failure · 2 usage · 3 no device · 4 device failed · 5 nothing to report. A tool that ran fine and found nothing returns NO_RESULT; a failure is raised, never returned. Two classifications worth restating because both were wrong somewhere: nothing transmitted is not a device failure (a bad argument is exit 2), and a rendering flag never moves the status.

tests/test_report.py is the enforcement point for the seam, tests/test_script_output.py for the plain vocabulary, and tests/test_cli_contract.py for the commands — including a derived sweep that runs every registered command twice, once plain and once under --json, and pins that the two agree about the exit status.

Platforms

One codebase, three flavours: regular (desktop/ssh, 72 cols, truecolor, emoji), picocalc (the PicoCalc's 53×26/53×40 framebuffer console, 16 palette slots, a 512-glyph font, no emoji), and cardputer (M5Stack's Cardputer Zero, 53×14 in 6×12 cells on a 320×170 panel a console host paints itself, truecolor, no emoji — hardware not yet in hand, so it is chosen by flag only). A frozen Platform spec (meshterm/platforms.py) resolves once at boot; consumers bind at platform-switch time via platforms.on_platform — never branch on the platform per frame, and never from meshterm.platforms import PLATFORM.

• The borderless title bar (frame._title_bar) is this platform's whole panel border: ↑↓ ──── Title ─────── Esc back. The clip arrows lead the row and are always both drawn — colour reads the scroll (the border's accent where that direction has more, muted where it doesn't), the same live/dim language the lane draws one row below. A pair that appeared and vanished, half of it a blank cell, asked the reader to compare the row against a memory of itself; fixed furniture means the bar never changes width as the body scrolls either.
• The Cardputer has no header row (Platform.header_row): the header's badges and battery ride the title bar's right end, after the way out — ↑↓ ── Title ──── Esc back ● 3 ⣷ 87%, the top-right corner they always had, one row up — and the wordmark is the main menu's title (menu._menu_title). The status never gives way: the way out sheds first, then the title is cut on an ellipsis. A tall dialog draws over the bar (dialog_row_margin 1) but never over the lane, which is the dialog's own; the bar's ends either side of the box are blanked (frame.composite_float), since a stray 7% would read as the battery.
• Never emit a raw emoji or bare hex colour into picocalc output. Icons go through theme.glyph() (the compact map); everything else is caught by the render-boundary fold (theme.fold_text, applied in tui/render.render_to_ansi and MapCanvas.to_ansi_lines) — but the fold is the safety net, not the design.
• The glyph contract is ui/fontset.py — the installed console font's exact codepoint inventory, device-verified. A character outside it is a test failure, not a tofu box found on-device. The font itself is built by scripts/picocalc/calculinux-console-font-6x12.sh; the two files move in the same commit.
• The 16-slot palette is theme._VT_SLOTS (programmed via /etc/vtrgb; same script). MESH_THEME_16 speaks color(0..15) only; backgrounds stop at slot 7. Both themes define identical style names.
• Bold is brightness on the VT: bold on a 0–7 foreground is slot N+8, so a dim-slot style must state its intent — not bold (keep the declared colour) or bold (the promotion is the point, only title.muted), never silent. Rich merges a row's base style into every span, so a silent one changes colour inside a selected row. Same trap outside the theme: MapCanvas drops emphasis entirely where bold is brightness, since its colours arrive quantized and it can't know which bank they landed in, and the fold's quantizer (theme._nearest_slot_params) states intent for it — a dim slot leaves as 22;3N, never a bare 3N, because 9N is how the console spells bright and adjacent art spans (the wordmark's bevels, a raster's neighbouring cells) reset nothing between them, so a bare one inherits the intensity bit and lands a bank too high mid-row.
• On picocalc, the node hue and the heat gradient quantize — same rule, coarser resolution: node_style snaps the key's hue to its sixth of the wheel (theme._NODE_SLOT_HEXES, the six chromatic bright slots) and heat to the heat.* steps. Nothing loses its colour for being on the console. Marks whose hue is fixed rather than derived go through a theme name so the slot is chosen deliberately (the node types' type.*; a raster resolves the same entry via theme.mark_rgb) — a naive downsample greys the repeater's violet. Footer hints are replaced by the F-key lane (ui/tui/fkeys.py): five FPair slots per screen, F1–F5 primary and F6–F10 each slot's opposite number (physical Shift+F1..F5), labels ≤6 cells. DEFAULT_LANE claims only F4/F5 — the pager, which has no physical key at all; the jump to either end rides the Shift half of the very pager heading for it (F10 Top behind F5 Page ↑, F9 Bottom behind F4 Page ↓), because Home and End are on this keyboard and only ever wanted a chip for consistency. That leaves F1–F3 free on every screen for its own verbs, and EMPTY_LANE for a screen with none at all (every dialog but the quit confirm, whose F3 is the chip that asked, pressed again). A chip names an action, never a key — Page ↑, not PgUp; Latest on a transcript; Region on the map, whose Home reframes and whose paging zooms. A directional pair rises toward its outer key: where two adjacent chips are opposite ends of one axis, the up · in · more end takes the slot nearer the lane's edge — F5 on the right-hand pair (F4/F5's paging, the map's zoom: Zoom - then Zoom +, a rocker), F1 on a left-hand pair (a select list's Sect ↑ then Sect ↓) — and a slot's Shift companion follows its own slot's direction. The lane is the footer here, so it obeys the hint line's rule — never advertise a key that would do nothing. Empty and dim are different claims: leave the slot empty when the action isn't a thing on this screen (Retry in a channel), and clear enabled/opp_enabled to draw it dim (label kept, fill dropped) when it's a thing that just isn't available this paint. Dimming is presentational — handle stays the authority and no-ops. The lane is also the only affordance advertisement here, so anything the desktop reaches by a chord or a bare letter (a list's ^PgUp/^PgDn section jumps, the Time Machine's w, the map's ^Y, a row's Del) earns a slot — otherwise it is undiscoverable on the device.
• Each handheld deals its own lane. Everything about the lane that belongs to one keyboard is a LaneDeck (fkeys.PICOCALC_DECK, fkeys.CARDPUTER_DECK), named by Platform.lane_deck: which keycodes drive the slots, where the chips sit on the row, how they are drawn, and which of a screen's definitions it reads. A screen defines picocalc_lane, and cardputer_lane follows it until that screen overrides it (JP, 2026-09-30: same entries for now, Fn+L/M being an awkward reach for paging). Override the per-deck property, never fkey_lane, which only resolves the active deck; resolve a key or draw a row through the deck (deck.action_for, deck.lane_text), never by assuming F1–F5. Both decks having five slots is a coincidence, not a rule. The Cardputer's lane is Fn+4…8 (F4–F8), never the bare digits, since a digit must stay a digit where the app takes typing; Shift with them arrives as F16–F20 (xterm's encoding, which the console host copies). Its chips are laid out exactly as the PicoCalc's — key caption, 9-cell chip, 2-cell gaps — captioned F4–F8 in both banks, white on the fn key's orange-red (a step darker than the print, same hue, so the white holds 4:1), and white on dark blue while Shift is held.
• The Cardputer draws its own pixels (meshterm/host/): the stock image leaves an app no text console, only the framebuffer and the keyboard's event device. The console host runs the ordinary TUI in-process — prompt_toolkit's app session pointed at a fixed 53×14 output whose bytes feed the host's own VT parser (host/vt.py), and a pipe the host types into (host/keys.py, xterm's spelling, so Shift+F4–F8 parse as F16–F20) — then draws the cells in Terminus 6×12 with MeshTerm's marks over it (host/font.py). The front end is the only part that differs: the framebuffer and evdev on the device (host/device.py, written ahead of the hardware), a Tk window on the desktop (host/sim.py): python -m meshterm.host --mock, after python scripts/cardputer/fetch-terminus.py once. Its glyph contract is fontset.CARDPUTER_CODEPOINTS, named by Platform.font as the PicoCalc's is; the fold derives everything from the platform's font (accents, emoji, the ? net) and quantizes colour only where truecolor is off.
• meshterm specimen prints the whole visual language through the real funnels — the acceptance card on-device, a preview under --platform picocalc on the desktop.
• Dev loop: meshterm --mock --platform picocalc in a 53×40 window, or --platform cardputer in a 53×14 one; the gallery and tests/test_theme16.py carry the contracts.