Beta documentation superseded by Electron integration #76

README.md

@@ -12,12 +12,13 @@ Swift app remains the stable download and rollback option during migration.
 
 | Edition | Current status | Setup and behavior |
 | --- | --- | --- |
-| Electron 0.3.0-beta.3, build 61 | Public beta for Apple silicon, macOS 13+; signed and notarized | [Download beta](https://github.com/pekth/meterusage/releases/tag/v0.3.0-beta.3) · [Beta guide](docs/BETA.md) |
+| Electron 0.3.0-beta.5, build 74 | Public beta for Apple silicon, macOS 13+; signed and notarized | [Download beta](https://github.com/pekth/meterusage/releases/tag/v0.3.0-beta.5) · [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) |
 
 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
+and rollback reference. Install the beta manually once. From beta 5 it checks
+GitHub for newer betas and offers to install them; the stable updater does
+not offer betas. 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).
@@ -30,7 +31,7 @@ and the [version strategy](docs/VERSIONS.md).
 </p>
 
 Synthetic demo captures of build 61's renderer. Claude Desktop provides allowance,
-not a chat-history heatmap. See the [full screenshot gallery and capture details](docs/SCREENSHOTS.md)
+not chat history; its heatmap shows daily quota used across devices. 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
@@ -71,13 +72,13 @@ All nine provider adapters remain in the retained Swift and candidate source:
 Codex, Claude Code, Antigravity, OpenRouter, Grok, OpenCode Go, Cursor, Copilot
 CLI and Gemini CLI. Their inputs and available measurements differ. The
 [Swift provider matrix](docs/swift/README.md#provider-matrix) describes existing
-CLI/local collection. The [Electron source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#source-choices)
+CLI/local collection. The [Electron source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/electron/README.md#source-choices)
 also describe optional Codex browser sign-in and Claude Desktop allowance.
 
 Local activity covers this Mac. Provider-reported account data has its own
 coverage limits. Missing tokens remain unknown. Local token costs are estimates; optional API
 billing cards label provider-reported amounts separately. Provider dashboards
-remain the billing source of record. Read the [beta privacy contract](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/PRIVACY.md)
+remain the billing source of record. Read the [beta privacy contract](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/PRIVACY.md)
 for Electron or the [Swift privacy contract](docs/PRIVACY.md) before changing a
 data source or sharing screenshots.
 
@@ -87,20 +88,20 @@ The beta tag contains the Electron source and retained Swift tree. The default
 branch retains stable Swift source during migration; the intended end state is one
 Electron app. Normal-profile side-by-side installation is unsafe:
 the app name, bundle ID and default preferences/data locations are shared.
-Use only the documented [isolated candidate QA profiles](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#isolated-qa)
+Use only the documented [isolated candidate QA profiles](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/electron/README.md#isolated-qa)
 for testing. A separate app identity and data root require a later decision;
-there is no automatic cutover. See [ADR 0010](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/adr/0010-macos-typescript-electron.md).
+there is no automatic cutover. See [ADR 0010](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/adr/0010-macos-typescript-electron.md).
 
 ## Documentation
 
 - [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](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md)
+- [Electron guide and known gaps](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/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)
-- [Desktop connections](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/DESKTOP-CONNECTIONS.md), [demo mode](docs/DEMO.md)
+- [Desktop connections](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/DESKTOP-CONNECTIONS.md), [demo mode](docs/DEMO.md)
   and [side notch](docs/SIDE-NOTCH.md)
 - [Concept mockups](docs/mockups/README.md) and [changelog](CHANGELOG.md)
 
@@ -113,11 +114,11 @@ the Swift guide; product screenshots now show the Electron beta.
 See [downloads](#download).
 
 <a id="macos-electron-migration-candidate"></a>
-See the [Electron candidate guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md).
+See the [Electron candidate guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/electron/README.md).
 
 <a id="second-accounts"></a>
 See [Swift additional local accounts](docs/swift/README.md#second-accounts) and
-[Electron advanced local accounts](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#advanced-local-accounts).
+[Electron advanced local accounts](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/electron/README.md#advanced-local-accounts).
 
 <a id="requirements"></a>
 See [Swift requirements](docs/swift/README.md#requirements).
@@ -127,7 +128,7 @@ See [contributor setup](CONTRIBUTING.md).
 
 <a id="agent-budget-cli"></a>
 See the [Swift Agent Budget CLI](docs/swift/README.md#agent-budget-cli) and
-[Electron commands](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#build-and-test).
+[Electron commands](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/electron/README.md#build-and-test).
 
 <a id="showcase"></a><a id="-showcase"></a>
 <a id="ambient-time-to-empty--side-notch-hud"></a>
@@ -150,7 +151,7 @@ See [installation details](docs/swift/README.md#download-and-installation).
 
 <a id="report-a-problem"></a>
 See [beta diagnostics and bug reports](docs/BETA.md#known-limits) and the
-[beta reporting guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/REPORTING.md).
+[beta reporting guide](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/REPORTING.md).
 
 <a id="-tldr"></a><a id="tldr"></a>
 See [downloads](#download).

docs/BETA.md

@@ -1,22 +1,25 @@
 # Electron public beta
 
-MeterUsage **0.3.0-beta.3, build 61** is an opt-in macOS beta. The ZIP supports
+MeterUsage **0.3.0-beta.5, build 74** 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.3/MeterUsage-0.3.0-beta.3-mac-arm64.zip)
-   and [SHA256SUMS](https://github.com/pekth/meterusage/releases/download/v0.3.0-beta.3/SHA256SUMS).
+1. Download [the beta ZIP](https://github.com/pekth/meterusage/releases/download/v0.3.0-beta.5/MeterUsage-0.3.0-beta.5-mac-arm64.zip)
+   and [SHA256SUMS](https://github.com/pekth/meterusage/releases/download/v0.3.0-beta.5/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.
+Do not run the two editions together against a normal profile. Beta 5 and later check GitHub
+hourly while **Check for updates** is on and offer newer betas or a newer
+stable release in the app, with a notification. **Install update** downloads the ZIP, verifies
+its GitHub SHA-256 digest, bundle identity and signature, then replaces the app
+and relaunches. Beta 4 and earlier cannot see betas; install beta 5 manually once. `Scripts/make-app.sh` still prepares the stable Swift download.
 
 To check the ZIP in its download directory:
 
@@ -27,7 +30,7 @@ shasum -a 256 -c SHA256SUMS
 Expected ZIP SHA-256:
 
 ```text
-6bc074f8753330c7b8bcf975ba3696fa249890230737d8c7580e7b93c3321439
+cc5cb4fdb573f37999685e263a574aa7df2d9a07b6ab7cb1d62deabde8afbf4f
 ```
 
 ## Provider coverage
@@ -41,6 +44,14 @@ Expected ZIP SHA-256:
   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.
+- Every provider card with a quota reading shows a **Quota activity** heatmap:
+  the daily rise in that provider's weekly (or longest) allowance, counting
+  desktop, web and other-device use. Each provider keeps its own history.
+  On first run, the current window's usage is spread over its elapsed days and
+  marked estimated; earlier weeks are not backfilled. Days count only while
+  MeterUsage refreshes; offline usage lands on the next reading's day. Values
+  are percentage points, never inferred tokens. Tooltips add measured Claude
+  Code or Codex tokens from this Mac when present.
 - Claude Code CLI reads local transcript activity. Quota requires an optional
   companion file. Local activity does not cover other devices.
 - Antigravity Desktop reads account allowance from one running, signed-in
@@ -61,8 +72,8 @@ Expected ZIP SHA-256:
   preserved and newly pasted keys are not saved. OpenRouter keeps its existing
   balance and aggregate activity source. Read [API setup and limits](API_USAGE_BETA.md).
 
-See [source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/electron/README.md#source-choices),
-[desktop connections](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/DESKTOP-CONNECTIONS.md) and [privacy](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/PRIVACY.md).
+See [source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/electron/README.md#source-choices),
+[desktop connections](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/DESKTOP-CONNECTIONS.md) and [privacy](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/PRIVACY.md).
 
 ## Known limits
 
@@ -85,19 +96,22 @@ See [source choices](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs
 
 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](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/REPORTING.md) before sending.
+Review the [report contents and privacy limits](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/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
-`c2d092cb92180b37a686582a904dbd0129bc371c`. 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.3`.
-
-Matching validation recorded 739 tests across 28 files on macOS, TypeScript
-checking, native helper compilation and production bundling. Exact-source CI
-also passed Swift build and tests. Signing, notarization, stapling, Gatekeeper,
+`321dd8a71474326ec29ce98c9d48d2e69d893933`. Release documentation is a documentation-only descendant; executable
+inputs are unchanged. Screenshots are from build 61 and do not show the Quota
+activity heatmap. Source manifests retain `0.2.41`; beta packaging explicitly
+set `0.3.0-beta.5`.
+
+Matching validation recorded 849 tests across 33 files on macOS, TypeScript
+checking and production bundling. Swift build and tests were not rerun for this
+beta. The installed build was observed recording quota activity for Claude,
+Codex, Antigravity and Grok. Native rendering of filled heatmaps
+remains unverified. Signing, notarization, stapling, Gatekeeper,
 installed bundle identity and ZIP bytes were verified separately. These checks
 do not close the native acceptance gaps above.
 

docs/KB.md

@@ -2,14 +2,15 @@
 
 ## Public beta
 
-Electron **0.3.0-beta.3, build 61** is an opt-in Apple silicon prerelease.
+Electron **0.3.0-beta.5, build 74** is an opt-in Apple silicon prerelease.
 [Installation and limits](BETA.md) and [current screenshots](SCREENSHOTS.md)
 describe it. Swift 0.2.41 remains stable. The default branch retains Swift
 source; Electron source and its full documentation are published at
-[`v0.3.0-beta.3`](https://github.com/pekth/meterusage/tree/v0.3.0-beta.3).
-The source PR stack is unmerged. The beta is a manual download, not an updater
-cutover. New feature development targets Electron. Native acceptance is incomplete
-and disclosed in the beta guide.
+[`v0.3.0-beta.5`](https://github.com/pekth/meterusage/tree/v0.3.0-beta.5).
+The source PR stack is unmerged. The beta is installed manually once; from beta 5 it
+offers newer betas in-app. The stable updater does not offer betas. New feature development targets Electron. Native acceptance is incomplete
+and disclosed in the beta guide. Beta 4 adds per-provider Quota activity
+heatmaps built from each provider's own quota readings.
 
 Build 61 adds separate API connections, explicit legacy saved-key recovery,
 hidden tray preloading, Antigravity Desktop allowance, Grok Bot Desktop Beta

docs/VERSIONS.md

@@ -1,22 +1,32 @@
 # MeterUsage versions
 
-Electron 0.3.0-beta.3, build 61, is the opt-in public beta. Swift 0.2.41 stays
+Electron 0.3.0-beta.5, build 74, is the opt-in public beta. Swift 0.2.41 stays
 stable and remains the updater/installer download. New features target Electron;
 Swift is retained for critical maintenance and rollback.
 
 | Version | Source | Download |
 | --- | --- | --- |
-| Electron beta | [v0.3.0-beta.3](https://github.com/pekth/meterusage/tree/v0.3.0-beta.3) | [Manual signed/notarized Apple silicon ZIP](BETA.md) |
+| Electron beta | [v0.3.0-beta.5](https://github.com/pekth/meterusage/tree/v0.3.0-beta.5) | [Manual signed/notarized Apple silicon ZIP](BETA.md) |
 | Swift stable | Default branch and [v0.2.41](https://github.com/pekth/meterusage/tree/v0.2.41) | [Swift guide](swift/README.md) |
 
 The beta source is published through its tag while the Electron PR stack stays
-unmerged. The tag includes current documentation and synthetic screenshots;
+unmerged. The tag includes current documentation and build 61 synthetic screenshots;
 its executable inputs match build source
-`c2d092cb92180b37a686582a904dbd0129bc371c`. The beta's package version was set
+`321dd8a71474326ec29ce98c9d48d2e69d893933`. The beta's package version was set
 at packaging time; its source manifest retains 0.2.41. Settings shows the
 running bundle version. See [known beta limits](BETA.md#known-limits).
 
 The apps share an identity and normal data locations. Quit one before replacing
 it and preserve a rollback copy. Do not run both against a normal profile.
 Stable cutover and Swift retirement remain separate work, defined in the
-[beta repository strategy](https://github.com/pekth/meterusage/blob/v0.3.0-beta.3/docs/VERSIONS.md).
+[beta repository strategy](https://github.com/pekth/meterusage/blob/v0.3.0-beta.5/docs/VERSIONS.md).
+
+## Update channels
+
+Swift and stable Electron builds read GitHub's `/releases/latest`, which never
+returns prereleases, and expect `MeterUsage-<version>.zip`. Electron builds whose
+version ends in `-beta.N` read the release list instead, skip drafts and pick the
+newest release with a verified `MeterUsage-<version>.zip` or
+`MeterUsage-<version>-mac-arm64.zip` asset. A final release outranks its betas,
+so beta users are offered the stable release that follows. Beta 4 and earlier
+predate this and need one manual install.