pekth · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026 · Oct 16, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,29 @@ follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Changed
+
+- Shorten heatmap hover/focus totals to values such as `42.4B tokens` and
+  `1.6K sessions` across local and account history. Keep exact grouped counts
+  in tooltips and accessibility labels. Summary counts compact from 1,000.
+
+### Fixed
+
+- Show the running app bundle's version in Settings instead of the legacy
+  hardcoded version. Source previews omit the version when none is supplied.
+
+## [0.3.0-beta.1] - 2026-10-16
+
+### Release
+
+- Publish Electron build 54 as an opt-in Apple silicon beta. Keep Swift 0.2.41
+  as the stable download and preserve its updater and installer contracts.
+- Replace old product screenshots with current synthetic Codex, Claude, notch
+  and Settings captures. Refresh download, source-choice and beta-limit docs.
+- Disclose the cosmetic 0.2.41 Settings footer and incomplete native acceptance.
+  The signed build is unchanged; Antigravity/Grok desktop login is follow-up work.
+
+
 ### Added
 
 - Label the Grok integration **Beta** in usage cards, setup and provider settings.
@@ -32,7 +55,7 @@ follows [Semantic Versioning](https://semver.org/).
 ### Changed
 
 - Make buttons smaller throughout the Electron menu, Settings and side-notch
-  cards. Reveal the notch Settings gear on strip hover or keyboard focus.
+  cards. Keep Settings in each card footer and remove the duplicate strip gear.
 - Align heatmap menu labels with a fixed selection-checkmark column.
 
 - Keep Service status at the top of the Electron menu. Switch between provider
@@ -47,7 +70,7 @@ follows [Semantic Versioning](https://semver.org/).
   summaries and setup details under Configure. Keep existing settings, account
   controls and explicit connection actions. Show the current source, collection
   state and reading availability separately.
-- Place service health after usage cards. Use exact grouped heatmap totals on
+- Keep service health above usage cards. Use exact grouped heatmap totals on
   hover and focus, with one Tab entry per heatmap and arrow-key navigation.
   Keep control focus visible without highlighting the panel edge.
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -136,9 +136,11 @@ See [`docs/DEMO.md`](docs/DEMO.md) for the data and privacy rules.
 
 ## TypeScript Electron candidate
 
-The source version is 0.2.41. This candidate is unpublished; private build and
-installation receipts exist, while complete native acceptance remains open.
-See the [candidate guide](docs/electron/README.md) for source choices and parity gaps.
+The source manifest retains 0.2.41. The public Electron beta is 0.3.0-beta.1,
+build 54, with the version explicitly set during packaging. See the
+[beta guide](docs/BETA.md) for the signed artifact, known cosmetic footer issue
+and incomplete native acceptance, and the [Electron guide](docs/electron/README.md)
+for source choices and parity gaps.
 
 
 Use the Node and pnpm versions declared in `package.json`. Provider accounts
@@ -178,7 +180,8 @@ pnpm package:mac
 
 `package:mac` exports the existing SF Symbol stand-ins, builds the app and
 packages an Apple silicon ZIP with publication disabled. It does not install
-or replace an app. Do not upload this candidate as the current public release.
+or replace an app. Locally packaged output is not the verified public beta
+artifact. Keep the stable release and beta download routes separate.
 Windows packaging, CI, native testing and release remain paused.
 
 electron-builder resolves `pnpm` from PATH when collecting production

diff --git a/README.md b/README.md
@@ -8,20 +8,39 @@ MeterUsage monitors AI coding allowance and usage in a macOS menu bar and
 floating side notch. Electron is the active development target. The legacy
 Swift app remains the stable download and rollback option during migration.
 
-## Choose an edition
+## Download
 
 | Edition | Current status | Setup and behavior |
 | --- | --- | --- |
-| Electron 0.2.41 source candidate | Active feature development; unpublished; native acceptance is incomplete | [Electron guide](docs/electron/README.md) |
+| Electron 0.3.0-beta.1, build 54 | Public beta for Apple silicon, macOS 13+; signed and notarized | [Download beta](https://github.com/pekth/meterusage/releases/tag/v0.3.0-beta.1) · [Beta guide](docs/BETA.md) |
 | Legacy Swift 0.2.41 | Frozen for new features; published stable download and migration rollback | [Swift guide](docs/swift/README.md) |
 
-Both implementations are already in this repository. The shared version number
-does not make the candidate the published download, and it is not a released
-v2.1. New contributions target Electron. Swift receives critical maintenance
-only until verified cutover. See the [staged retirement decision](docs/adr/0024-electron-primary-swift-retirement.md)
-and [version strategy](docs/VERSIONS.md).
+Electron is the active app for new features. Swift remains the stable download
+and rollback reference. The beta is installed manually; the stable updater does
+not offer it. Quit the existing MeterUsage before replacing it, and keep a copy
+for rollback. Both apps share their identity and saved data, so do not run them
+together against a normal profile. See [beta installation and limits](docs/BETA.md)
+and the [version strategy](docs/VERSIONS.md).
 
-## Download and installation
+## Current beta UI
+
+<p>
+  <img src="docs/images/beta-usage-claude.png" alt="Electron beta Claude usage demo with service status and token heatmap" width="300">
+  <img src="docs/images/beta-notch-claude.png" alt="Electron beta hover card and compact side-notch usage rail" width="256">
+</p>
+
+Synthetic demo captures of build 54's renderer. Claude Desktop provides allowance,
+not a chat-history heatmap. See the [full screenshot gallery and capture details](docs/SCREENSHOTS.md)
+for Codex, Claude, side notch and Settings.
+
+The beta includes Codex browser sign-in/account history, optional Claude Desktop
+allowance, existing CLI sources, compact provider tabs and hover cards, provider
+reordering and readable token totals. Account coverage depends on the source.
+Grok remains Beta and CLI-only; Antigravity desktop login is follow-up work.
+Build 54's Settings footer incorrectly says `0.2.41`; the packaged version is
+`0.3.0-beta.1`. See [known beta limits](docs/BETA.md#known-limits).
+
+## Stable Swift installation
 
 The default installation is the published Swift app for Apple silicon Macs
 with macOS 13 or later. No Swift, Xcode, Command Line Tools or Git is required.
@@ -68,8 +87,10 @@ there is no automatic cutover. See [ADR 0010](docs/adr/0010-macos-typescript-ele
 
 ## Documentation
 
-- [Swift guide and older demo screenshots](docs/swift/README.md)
-- [Electron candidate guide and known gaps](docs/electron/README.md)
+- [Beta download, verification and limits](docs/BETA.md)
+- [Current beta screenshots](docs/SCREENSHOTS.md)
+- [Swift guide](docs/swift/README.md)
+- [Electron guide and known gaps](docs/electron/README.md)
 - [Versions and staged Swift retirement](docs/VERSIONS.md)
 - [Contributing](CONTRIBUTING.md)
 - [Project knowledge](docs/KB.md) and [decision index](docs/adr/README.md)
@@ -79,8 +100,11 @@ there is no automatic cutover. See [ADR 0010](docs/adr/0010-macos-typescript-ele
 
 ## Compatibility links
 
-Older root README links continue below. Detailed Swift descriptions and images
-now live in the Swift guide.
+Older root README links continue below. Detailed Swift descriptions remain in
+the Swift guide; product screenshots now show the Electron beta.
+
+<a id="choose-an-edition"></a>
+See [downloads](#download).
 
 <a id="macos-electron-migration-candidate"></a>
 See the [Electron candidate guide](docs/electron/README.md).
@@ -103,7 +127,7 @@ See the [Swift Agent Budget CLI](docs/swift/README.md#agent-budget-cli) and
 <a id="ambient-time-to-empty--side-notch-hud"></a>
 <a id="menu-bar--popover-dashboard"></a>
 <a id="settings-accounts--providers"></a>
-See [older Swift demo screenshots](docs/swift/README.md#showcase).
+See [current beta screenshots](docs/SCREENSHOTS.md).
 
 <a id="provider-matrix"></a><a id="-provider-matrix"></a>
 See the [Swift provider matrix](docs/swift/README.md#provider-matrix).
@@ -118,7 +142,7 @@ See [privacy and data handling](docs/PRIVACY.md).
 See [installation details](docs/swift/README.md#download-and-installation).
 
 <a id="-tldr"></a><a id="tldr"></a>
-See [edition choice](#choose-an-edition).
+See [downloads](#download).
 
 <a id="license--disclaimer"></a><a id="-license--disclaimer"></a>
 ## License and disclaimer

diff --git a/assets/showcase-codex-reset.png b/assets/showcase-codex-reset.png
diff --git a/assets/showcase-menubar.png b/assets/showcase-menubar.png
diff --git a/assets/showcase-popover.png b/assets/showcase-popover.png
diff --git a/assets/showcase-sidenotch.png b/assets/showcase-sidenotch.png
diff --git a/docs/BETA.md b/docs/BETA.md
@@ -0,0 +1,84 @@
+# Electron public beta
+
+MeterUsage **0.3.0-beta.1, build 54** is an opt-in macOS beta. The ZIP supports
+Apple silicon and macOS 13 or later. It is Developer ID signed, notarized and
+stapled. Swift `0.2.41` remains the stable release and updater download.
+
+## Install
+
+1. Download [the beta ZIP](https://github.com/pekth/meterusage/releases/download/v0.3.0-beta.1/MeterUsage-0.3.0-beta.1-mac-arm64.zip)
+   and [SHA256SUMS](https://github.com/pekth/meterusage/releases/download/v0.3.0-beta.1/SHA256SUMS).
+2. Quit MeterUsage and keep a copy of your existing app and its saved data for
+   rollback. The beta shares the app identity and data locations with Swift.
+3. Unzip the download, move `MeterUsage.app` to Applications, and open it.
+4. In Settings, choose an existing CLI source or an optional account connection.
+   Selecting a method alone does not connect it. Use its connection button.
+
+No Node, pnpm, Swift or Xcode installation is needed to use this prebuilt beta.
+Do not run the two editions together against a normal profile. Updating to later
+betas is manual. `Scripts/make-app.sh` still prepares the stable Swift download.
+
+To check the ZIP in its download directory:
+
+```sh
+shasum -a 256 -c SHA256SUMS
+```
+
+Expected ZIP SHA-256:
+
+```text
+ec4e8878e6a35120b397d8c118d023f010e8a6952a257b75764f05ecbc6f52ba
+```
+
+## Provider coverage
+
+- Codex browser sign-in reads allowance and provider-reported daily account
+  tokens when supplied. Missing days remain unavailable. Its account history
+  is separate from this Mac's CLI sessions; universal product/device coverage
+  is not established.
+- Codex CLI reads existing authenticated quota and local rollout activity.
+- Claude Desktop uses explicit consent and a macOS Keychain access prompt to
+  read current allowance through a compatibility endpoint. Some accounts,
+  including free accounts, may have no allowance token. This does not sign the
+  user out of Claude Desktop. Desktop chat/token history is not collected.
+- Claude Code CLI reads local transcript activity. Quota requires an optional
+  companion file. Local activity does not cover other devices.
+- Existing Grok CLI, Antigravity container, OpenCode Go and other adapters retain
+  their source-specific limits. New Antigravity Desktop and Grok/Cursor login
+  integrations are not included. Grok consumer web sign-in is unavailable.
+
+See [source choices](electron/README.md#source-choices),
+[desktop connections](DESKTOP-CONNECTIONS.md) and [privacy](PRIVACY.md).
+
+## Known limits
+
+- Settings displays a hardcoded `0.2.41` footer. The installed bundle and beta
+  download are version `0.3.0-beta.1`, build 54. A footer fix is separate work.
+- Native keyboard/VoiceOver, complete setup/account/offline journeys,
+  notifications/login items, sharing, update/relaunch/rollback and multi-display
+  notch transitions have incomplete acceptance coverage. These are gaps in
+  verification, not confirmed failures.
+- Live Codex refresh was observed. Claude paid-account allowance was not
+  live-tested. Optional support-report delivery and deployed relay limits
+  were not verified end to end.
+- Windows support is paused. Intel Mac binaries are not provided by this beta.
+
+Use Settings > Diagnostics for sanitized diagnostics and **Send report**.
+The app limits report attempts to one every ten minutes, including relaunches.
+Review the [report contents and privacy limits](REPORTING.md) before sending.
+Never include tokens, passwords or raw account files in an issue.
+
+## Build and screenshot identity
+
+The signed artifact was built from source
+`6ce695324e54bb09bf6e5ab36fd4733875c94427`. Release documentation and new
+screenshots are a documentation-only descendant; executable inputs are unchanged.
+Source manifests retain `0.2.41`; beta packaging explicitly set `0.3.0-beta.1`.
+
+Matching validation recorded 417 synthetic tests across 19 files, TypeScript
+checking and production bundling. Signing, notarization, stapling, Gatekeeper,
+installed bundle identity and ZIP bytes were verified separately. These checks
+do not close the native acceptance gaps above.
+
+The [screenshot gallery](SCREENSHOTS.md) uses invented demo data and the actual
+release renderer. It replaces old product captures without exposing real accounts.