Distribution: what bundled and compact mean, and which one the plain name gets

[A13xB0]

Five issues describe how MeshBench reaches a user: two build variants (#509), a
page to choose from (#510), an apt repository (#511), a Homebrew tap (#512), and
whether the smaller variant can even finish installing itself off Linux (#514).

Read together they did not agree. This is the parent, and on naming and
defaults it is the authority; where a child says something different, the
child is out of date.

What the two variants are

• bundled - the application, the emulators, and the chip model. Boots an
  emulated board on first run with nothing to fetch and nothing to explain.
• compact - the application alone. Completes itself through
  Configuration > Setup, where that is possible (The compact build cannot complete itself off Linux: the fetcher serves no emulator for macOS or Windows #514).

Both always carry the fixtures, the fonts, the licences, and the chip model.
The chip is about a hundred kilobytes now that it is
virtual-sx1262 loaded by whichever
emulator runs a board, so leaving it out is not a size judgement any more, it is
a floor: without it neither variant can start any board at all.

The decision

meshbench is the application. meshbench-bundled adds the emulators.

One rule, every channel, no exceptions:

channel	plain name	with emulators
apt (#511)	meshbench	meshbench-bundled
Homebrew (#512)	meshbench	meshbench-bundled

The suffix names an addition, which is how package naming has always worked:
texlive and texlive-full, git and git-all. meshbench-compact would
name a subtraction, and a package whose name says what it lacks is a strange
thing to ask somebody to type. It also means the word "compact" need not appear
in any package name at all: the plain name is the compact one.

This overrules #512, which had the plain cask as bundled. Its reason does
not survive reading: it says a cask "re-fetches the whole disk image on every
upgrade either way, so the argument that flips the default for apt does not
apply". But the apt argument is that a package manager re-downloads on every
release, and re-fetching the whole image is that same property. The upgrade is
26 MB or 110 MB depending on the variant, every release, forever. That argues
for the flip rather than against it.

Which leaves the case for a lean default standing on both channels: a package
manager is not a one-off, and emulation is the specialist backend here. Native
is what anything being compared runs on, because an emulated node is explicitly
not reproducible. Somebody who installs MeshBench to answer a coverage or a
link-budget question may never point it at an emulated board.

A downloadable file always says which variant it is

Package managers are asked a question and can answer it. A file in a Downloads
folder cannot, so it carries its own label and there is no unsuffixed release
asset:

meshbench-linux-x86_64-bundled.tar.gz     meshbench-linux-x86_64-compact.tar.gz
meshbench-x86_64-bundled.AppImage         meshbench-x86_64-compact.AppImage
MeshBench-arm64-bundled.dmg               MeshBench-arm64-compact.dmg
meshbench-windows-x86_64-bundled.msi      meshbench-windows-x86_64-compact.msi
meshbench-windows-x86_64-bundled.zip      meshbench-windows-x86_64-compact.zip

meshbench-source.tar.gz                   source is source; it has no variant
SHA256SUMS                                covers all of them

This is the one place the "unsuffixed means compact" rule is not applied, and it
is deliberate. Applying it would silently turn today's
meshbench-linux-x86_64.tar.gz - the only stable asset name we have - from a
build that boots a board into one that cannot. Labelling both makes that link
404 instead, which is the failure worth having. Every other current name has
a version in it and is being renamed by #509 anyway.

The debs are the meeting point of the two rules and follow both: the package
name carries the variant (meshbench, meshbench-bundled) and Debian
convention puts the version in the filename.

The download page recommends bundled, and says why

Naming and recommending are different jobs. No filename claims to be the
default; the page (#510) picks one, and for a one-off download that is bundled,
because it works on first run. It should carry one line saying apt and Homebrew
give you the application alone, so nobody meets that difference for the first
time at a Setup prompt.

compact is only offered where it can complete itself

That is #514. Where Setup cannot fetch the emulators, the compact download stays
available but leads with what the user must build by hand: the fork URLs, the
branches, and the fact that a distribution's own QEMU has no SX1262 in it and a
stock Renode sleeps for ever on a wake condition that is already true.

Order

1. Release two variants of every asset: bundled with the emulators, compact without #509 builds the two variants and settles the filenames. Everything else
   consumes what it names.
2. The compact build cannot complete itself off Linux: the fetcher serves no emulator for macOS or Windows #514 in parallel: mostly a catalogue and a PE header case, and it decides
   which compact options may be offered without a caveat.
3. A download page on meshbench.github.io #510 once the names are stable, because its whole design rests on
   releases/latest/download/<name> resolving server-side.
4. An apt repository, with meshbench and meshbench-bundled #511 and A Homebrew tap: meshbench and meshbench-bundled casks #512 last, independent of each other, and now identical in
   shape.

What has changed under these issues since they were written

• radioserver no longer exists. Both emulators load the chip themselves.
  Anywhere these issues say "radioserver", read libvirtualsx1262.{so,dylib,dll}
  from MeshBench/virtual-sx1262, pinned by release like the emulators.
• A bundle needs Renode's support files, which nothing shipped until now: the
  .repl platform descriptions and our C# peripherals, in renode-support/
  beside the binary. Without them a bundle carrying both emulators can start an
  ESP32 board and not an nRF52 one. packaging/verify-bundle.sh checks for them.
• The compact build cannot complete itself off Linux: the fetcher serves no emulator for macOS or Windows #514's macOS inventory is out of date, in our favour. The chip model
  publishes macos-arm64 and windows-amd64, so what is missing off Linux is
  the two emulators rather than three things.

[A13xB0]

Plan

Grounded in what the pipeline does today rather than how the children describe
it. package.yml builds one tree per platform and packages it once: Linux tars
that tree (bundled) and then builds an AppImage and a deb from a subset
(compact), macOS repacks the dmg with the emulators in it (bundled), Windows
zips and wraps an msi (bundled). So the machinery for "assemble, then package"
already exists on Linux and only has to become deliberate.

First, a blocker none of the five issues names

The in-app updater picks its download by suffix. wanted() in
internal/app/update/artefact.go matches HasSuffix(n, ".AppImage"),
.dmg, .msi, .zip, .tar.gz. The moment a release carries two of each,
every one of those matches both, and a bundled install can be updated into a
compact one - losing its emulators, silently, on a machine where emulated boards
were working the day before.

Fix it in the same change that creates the second variant, and do not infer the
variant from what is lying beside the binary:

• The packaging steps write a one-line VARIANT file into each tree.
• Detect() reads it, and wanted() requires the matching label in the name.
• meshbench -version prints it. That also answers Release two variants of every asset: bundled with the emulators, compact without #509's own worry about
  dropping the version from filenames: what a file is becomes a question the
  installed thing can answer.
• A release whose asset set does not satisfy both variants of the running
  platform fails the release job, beside the existing "refuse a release nobody
  can use" checks.

Stage 1 - make today's assets honest (#509, naming only)

One small change, on its own, before anything is built twice. Rename what
already exists to say which variant it already is:

meshbench-linux-x86_64.tar.gz        -> meshbench-linux-x86_64-bundled.tar.gz
meshbench-<v>-x86_64.AppImage        -> meshbench-x86_64-compact.AppImage
MeshBench-<v>-arm64.dmg              -> MeshBench-arm64-bundled.dmg
meshbench-<v>-windows-x86_64.msi     -> meshbench-windows-x86_64-bundled.msi
meshbench-<v>-windows-x86_64.zip     -> meshbench-windows-x86_64-bundled.zip
meshbench-<v>-source.tar.gz          -> meshbench-source.tar.gz
meshbench_<v>_amd64.deb              unchanged

Nothing new is built. This is the whole one-time link break, taken alone so it
is not tangled with the variant work, and it is the change that makes
releases/latest/download/<name> viable for #510.

Also in scope, because they name these files: the release job's refusal checks,
the release-notes grouping, README.md, docs/install.md, and the two download
buttons on the landing site.

Done when a release publishes under the new names and the updater still finds
its own artefact.

Stage 2 - the PE case (#514, step 1)

formatOf in internal/app/resource/execformat.go knows ELF and Mach-O. Add
PE: MZ, then the COFF machine word at the e_lfanew offset. Pure Go, unit
testable, blocks nothing and is blocked by nothing. Can be done by somebody else
in parallel with stage 1 on day one.

Done when a PE binary passes checkExecutable and a wrong-architecture one
is refused with the same wording the other two get.

Stage 3 - build both variants (#509, the rest)

Per platform, one build and two packaging passes over a strict superset:

1. assemble the compact tree - binary, fixtures, fonts, LICENCES, VARIANT,
   and the chip model;
2. package the compact assets from it;
3. unpack the emulators and renode-support/ into the same tree;
4. package the bundled assets from that.

Linux gains a compact tarball, a bundled AppImage and a meshbench-bundled deb.
macOS gains a compact dmg. Windows gains a compact zip and msi - two variants
rather than one, because #513 settled that an emulated board does boot there.

The smoke test runs against both trees. "The application starts without its
emulators beside it" is the case nothing currently proves, and it is the whole
premise of the compact build.

Done when a release carries the full matrix, verify-bundle.sh passes on
every bundled tree, and the compact trees start.

Stage 4 - let compact finish itself off Linux (#514, the rest)

Now unblocked by stage 2. Three independent pieces:

• Windows: serve the Windows assets from toolchaincatalogue.go. Emulation
  is proven there and the PE check now exists.
• macOS QEMU: pinned since v9.2.2-meshbench-sx1262-11 and never run. Boot
  one ESP32 board on macOS against it. This is running it, not building it.
• macOS Renode: the fork publishes a build tree rather than a portable
  package. Get it publishing one, place renode-support/ alongside, and bring
  up one nRF52 board.

Done when Configuration > Setup can complete a compact install on all three
platforms, or the download page says exactly what is missing on the ones it
cannot.

Stage 5 - the download page (#510)

Needs stage 1's names and stage 4's answers, and nothing else. Static page,
releases/latest/download/<name> for every button, the API only filling in
version, date and sizes as progressive enhancement with baked-in fallbacks.

Recommends bundled, carrying one line that apt and Homebrew give the application
alone.

Stage 6 - the package managers (#511, #512)

Independent of each other, both needing stage 3's artefacts. apt needs the two
debs and a signing key held as a release secret; Homebrew needs a tap repository
and a token scoped to it. Same shape now that both use meshbench and
meshbench-bundled.

The quarantine flag is the reason #512 is worth doing beyond convenience: we are
not notarised, so a first launch is refused today until the user right-clicks and
chooses Open, and a cask removes the attribute itself.

Order, and what can run at once

stage 1 (names) ─┬─> stage 3 (both variants) ─┬─> stage 5 (download page)
                 │                            └─> stage 6 (apt, brew)
stage 2 (PE) ────┴─> stage 4 (off-Linux setup) ──┘

Stages 1 and 2 can start now and touch nothing in common. Stage 4's three
pieces are independent of each other, and its macOS half is the long pole of the
whole plan, because it needs a macOS machine and a board brought up on it.

What to do first

Stage 1 and stage 2. Neither depends on anything, together they are a day, and
they unblock every remaining stage.

[A13xB0]

The download page design

Prototype (private link, interactive - the tabs and the variant switch work):
https://claude.ai/code/artifact/14a0c650-5d7e-4141-b7b3-e2ef79291bf2

Written down here as well so the issue stands on its own.

What the research changed

Looked at Grafana, Node.js, Ghostty, VS Code and Anaconda/Miniconda. Three
things came out of it.

Three selectors is one too many. Grafana makes you pick edition, then
version, then platform before you see anything at all. Node.js does better by
leading with one default and letting you override it. We have an extra axis that
neither has - bundled or compact - so making somebody traverse all three would be
worse than either. So: the OS is detected and the tabs override it, and the
variant is one page-level switch rather than a choice repeated at every leaf.
It is a property of what you want, not of the platform, and one switch changes
every filename, size and command on the page at once.

Package manager first, file second. Node.js and Ghostty both lead with the
command. For anybody who has brew or apt, a command is a better answer than a
disk image, so it sits beside the primary button rather than below the fold.

Anaconda has no comparison table and it is a real gap. Their wording is good

• Miniconda is "for users who know what they need" - but there is nothing to
  compare. The page keeps that framing and adds the table: what each build can do,
  what it costs, and what a package manager gives you.

The shape

1. Masthead, the landing site's own: sticky, basalt, the mark, the same five
   nav labels, with Download marked as the current page rather than a button.
2. Hero: the detected platform, one filled download button, and beside it the
   one-command install.
3. The variant switch, with a caption that changes to say what it means.
4. Which build do you want, two cards in user terms plus the comparison
   table.
5. Every platform, tabbed, each with its install methods in order.
6. Verifying, and older versions - because a run is meant to be reproducible
   and somebody will need the build a colleague used.

One command, and why it is not a fourth install mechanism

The hero's alternative is a single line on macOS and Linux:

curl -fsSL https://meshbench.github.io/install.sh | sh

An earlier draft put the raw apt sequence there - key, sources list, update,
install - which is four lines of paste as the first thing a newcomer sees, and
ugly. The setup half is the script's job.

It installs through the package manager rather than instead of it. It works
out the distribution, adds our repository or tap, and then runs apt or brew, so
updates still arrive with the rest of the system and we do not acquire a third
install path nobody maintains. Same line on both platforms. On macOS it goes
through Homebrew, so the quarantine flag is handled, which is the thing a disk
image cannot fix on its own.

It follows the variant switch: | sh installs meshbench, and
| sh -s -- --bundled installs meshbench-bundled. A script that ignored the
choice made directly above it would be the page arguing with itself.

The explicit steps stay, one section down, as "Homebrew, by hand" and "apt, by
hand", with a link to read the script. Not wanting to pipe a script into a shell
is a fair position and deserves a real answer.

Windows has no script line, because there is no package manager for it in
this plan. Inventing a PowerShell one-liner that nothing would build is the kind
of thing that reads as finished and is not.

Colour

The palette is MeshBench/brand's own tokens rather than anything invented, so
this applies the identity. The rule that governs it is that orange is signal -
traffic, the route, the node transmitting, never a surface and never decoration.
So orange appears twice and only twice: in the mark, where it is the lit route,
and on the one download being recommended. Violet carries every other piece of
structure, and status has its own greens and ambers.

The filled button is #D0450B rather than the mark's #E8500F. White on
#E8500F is 3.76:1 and fails AA at this size; the landing site had already
solved that and its answer is the one used here rather than a second one.

The caveats appear only when they are true

Switching to compact grows a warning on the macOS and Windows panels about what
Setup cannot fetch yet, with the fork warning as its first line - somebody
reaching for their distribution's QEMU has not brought their own, they have
brought one with no SX1262 in it. Switching back to bundled removes them,
because they are then untrue.

What this adds to the work

install.sh does not exist. It is small - detect the OS and distribution, add
the apt repository or the brew tap, install one of two package names, take a
--bundled flag - but it is a new deliverable rather than something that comes
free with #511 and #512, and it is the thing the whole hero now rests on. It
belongs in stage 6 beside them, and the download page in stage 5 should not
promise it before it exists.

[A13xB0]

Built

All six stages exist as pull requests. The stack, in merge order:

stage	PR	base	what
2	#569	main	PE recognition, with the tests that file never had
1	#570	main	every asset names its variant, version dropped
3	#571	#570	both variants built; the updater can no longer swap one for the other
4	#572	#569	Windows fetches its emulators; every pin checked on every platform
6	#573	#571	apt repository and Homebrew tap
5	meshbench.github.io#5	main	the download page and install.sh

#569 and #570 are independent and can merge in either order. Watch the
stacked ones: merging a base and deleting its branch closes the child rather
than retargeting it.

Three things found on the way that none of the issues named

The updater would have silently downgraded people. wanted() matches on
suffix, so the moment a release carried two of each format both matched and
whichever came first won. A bundled install updated into a compact one loses its
emulators on a machine where emulated boards were working the day before, and
the download looks entirely normal on the way past. Fixed in #571 with a
VARIANT file each tree carries, read rather than deduced.

The Windows job fetched the emulators before the compact pair was cut, so a
"compact" zip would have shipped 92 MB of emulators inside it.

verify-bundle.sh treated an unlabelled tree as compact, which made the
existing "refuses a bundle without its emulators" test pass for the wrong
reason.

What still needs a human

Neither is something a workflow can do for itself, and both are why #511 and
#512 cannot be exercised yet:

1. The apt signing key. APT_SIGNING_KEY and APT_SIGNING_KEY_ID on an
   apt-publish environment, the public half committed to the site repository
   at apt/meshbench.gpg, and a SITE_PUBLISH_TOKEN that can write there.
2. The tap repository. MeshBench/homebrew-meshbench - Homebrew requires
   that exact name - and a TAP_PUBLISH_TOKEN scoped to it.

Both workflows fail loudly with the reason rather than skipping, and both take a
dry_run dispatch that commits without pushing, which is how to see the first
one work.

And one ordering rule

The site PR must not merge before a release carries the new asset names.
Every button points at releases/latest/download/<name>; the current release
still uses the old names, so they would all 404 until stages 1 and 3 have
shipped in a release.

What is left in #514

macOS, and only macOS. Renode publishes a build tree there rather than a
portable package, and no nRF52 board has ever been brought up on a Mac. QEMU is
pinned for macOS and has never been run against a board. Both need a Mac, so
neither could be done here - and the download page already says so on its compact
macOS panel rather than handing that over silently.