Diagnostics is prose, so it is a written page

The block is a title, a standfirst, sections and a list under each. That
is a page of writing, not a screenful of rows, and the app already knows
how to draw one: the About pages' markdown renderer. So the tool states
its report as before and a third projection turns it into markdown, which
is exactly what the report seam was built for -- no tool touched, no
report changed, one new function beside the other two faces.

Being a written page buys the two things a long block most needs and that
a hand-built screen had neither of. Its ## headings are landmarks, so each
pins to the top row while its own section scrolls under it and ^PgUp/^PgDn
step section by section; and the PicoCalc lane picks up Sect up / Sect
down for the same reason a grouped list does. AboutPage already does all
of it, so the page is that page with one verb added.

The frame comes back with it. The bare frame was there to keep a border
off every line a mouse would drag through, which mattered while copying
off the screen was the only way out; saving is the way out now, so the
page can be a normal screen and the save can be advertised where this app
advertises verbs -- the footer hint on a desktop, the lane's one free F3
slot on the console -- instead of in the page's own body, which belongs to
the report. The answer moves to a popup with it: a path is worth reading
carefully, a write can fail, and the page underneath is unchanged and
still there when the popup goes.

Saving markdown is the same decision as drawing it. One source is what the
page renders and what the file holds, and an issue tracker renders it as
written, with no fence and no apology. Every value is a code span, which
is correctness and not taste: a Windows path is full of backslashes that
markdown reads as escapes, and an error a stranger's firmware wrote can
hold an asterisk. A value already holding a backtick gets a longer fence.

Rows are a list and not a table, measured rather than assumed -- a
markdown table's cells are cropped with an ellipsis at 53 columns, and a
bug report whose one long value is cut is missing the half that mattered.
A list item wraps and hangs under its own text at any width.

Two smaller things fell out. A block may carry a caption, the heading a
format that has headings draws above it -- plain and JSON have no use for
one and ignore it. And the host block splits in two, because a "it looks
wrong" report is about the terminal and its reader should not have to pass
the processor architecture on the way to it.

The command line is untouched: aligned records, because that face is a
stream to grep and headings are furniture on it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 5 committed 2026-09-19 17:10:31 -04:00
1 parent 41c2cf416b
commit 72f72b84cd
8 files changed
+532 -378

No files matched your search

+34 -22
View File
@@ -1489,10 +1489,11 @@ $ meshterm diagnostics
meshterm 0.3.7
install frozen
os Windows 11
os_build 10.0.26100
arch AMD64
python 3.13.1
os Windows 11
os_build 10.0.26100
arch AMD64
python 3.13.1
terminal Windows Terminal
term -
colorterm truecolor
@@ -1525,17 +1526,21 @@ runs_failed 3
first_heard 8mo
last_heard now
TABLE ROWS
observations 418203
runs 912
traces 47
...
TABLE ROWS
observations 418203
runs 912
traces 47
PREFERENCE VALUE
log_level DEBUG
map_style terrain
```
The seven groups are the page's seven sections — build, host, terminal, radio, storage,
stored rows, changed preferences. The command line shows them as blank-line-separated
records, because that face is a stream to grep; the page and the saved file show them as
markdown headings, because that one is a document to read.
**The radio is asked but never required.** A report about a companion that will not connect
is exactly the report most worth filing, so a failure to reach it becomes `connected no`
with the radio's own words in `error`, and every other fact still arrives.
@@ -1553,7 +1558,7 @@ feature and not a habit: the block is designed to be pasted in public by somebod
not read it, and `tests/test_diagnostics.py` plants real secrets in every store that holds
one and fails if any of them — or a field merely *named* like one — reaches either face.
Under `--json`, the three fact blocks merge into one flat object and the two listings keep
Under `--json`, the five fact blocks merge into one flat object and the two listings keep
a key of their own:
```json
@@ -1563,23 +1568,30 @@ a key of their own:
**`--out PATH` writes it to a file instead of printing it**, and the answer becomes the
path — the same trade `config export-key --out` makes, since a caller who asked for a file
wants to be told where it is rather than handed the contents they just redirected into it.
The file is always the plain block, even under `--json`: it exists to be attached to an
issue and read by a person. Redirection still works and is not replaced; what `--out` adds
is a file laid out at full width rather than folded to whatever the terminal happened to be.
```console
$ meshterm diagnostics --out meshterm-diagnostics.txt
$ meshterm diagnostics --out meshterm-diagnostics.md
✓ diagnostics written — attach it to the report.
/home/jp/meshterm-diagnostics.txt
/home/jp/meshterm-diagnostics.md
```
In the menu this is the **Diagnostics** page under *This app*, drawn on a bare frame — no
border, no header, no footer, no key hints — because a terminal is selected by dragging and
every one of those is a character the clipboard would carry into the issue. Its one line of
its own is `s save this to a file`, which writes `meshterm-diagnostics.txt` into the config
directory beside the log and then says so on that same line. A bare frame has nowhere else
to advertise a key, and one trailing line after a blank row costs a paste far less than a
border costs it on every line.
**The file is markdown**, whichever face the run was printing, because an issue tracker
renders markdown as written — no fence, no apology. Every value is a code span, so a
Windows path's backslashes and a firmware error's asterisks arrive as themselves rather
than as markdown. Redirection still works and is not replaced; `--out` is what gives you
the document rather than the record stream.
In the menu this is the **Diagnostics** page under *This app*, and it is one of the app's
**written pages** — the same markdown renderer behind the About pages, drawing the same
document the file holds. That buys what a long block most needs: its `##` headings are
landmarks, so each pins to the top row while its own section scrolls under it and
`^PgUp`/`^PgDn` step section by section.
`s` saves, advertised in the footer hint on a desktop and on the lane's free **F3** slot on
the PicoCalc — never in the page's body, which belongs to the report. It writes
`meshterm-diagnostics.md` into the config directory beside the log, and answers in a popup
naming the path. A write that fails says so in the same popup, in red, and leaves the page
readable.
#### `meshterm platform`