release: prepare v0.0.1-rc.4

MIGRATION.md

@@ -1,46 +1,24 @@
 # OpenBitdo Migration Notes
 
-## Scope
-This migration restores the single-command `openbitdo` CLI contract and removes the `ui`/`run` subcommand surface from user-facing usage.
+This file explains the current user and contributor surface after the CLI and packaging cleanup.
 
-## What changed
-- `bitdoctl` was removed.
-- `openbitdo cmd ...` was removed.
-- `openbitdo` now launches interactive TUI directly (with optional `--mock`).
-- subcommand forms `openbitdo ui ...` and `openbitdo run ...` are rejected (historical).
-- headless output modes remain available through the Rust API, not the CLI.
-- Settings schema moved to v2 fields while keeping compatibility defaults for v1 files.
+## Current CLI Contract
 
-## Command mapping
-| Prior command form | Current command |
-| --- | --- |
-| `cargo run -p openbitdo --` | `cargo run -p openbitdo --` |
-| `cargo run -p openbitdo -- --mock` | `cargo run -p openbitdo -- --mock` |
-| `openbitdo ui --mock` (historical) | `openbitdo --mock` |
-| `openbitdo run ...` (historical) | Not supported in CLI |
+- `openbitdo` launches the interactive dashboard.
+- `openbitdo --mock` launches the dashboard without real hardware.
+- Historical subcommand-style entry points are no longer part of the supported CLI.
 
-## New usage
-From `/Users/brooklyn/data/8bitdo/cleanroom/sdk`:
+## Current Packaging Contract
 
-Interactive dashboard:
+- GitHub prereleases are the canonical release source.
+- AUR publishes `openbitdo-bin`.
+- Homebrew publishes through the separate tap repo `bybrooklyn/homebrew-openbitdo`.
+- macOS artifacts remain unsigned and non-notarized until Apple credentials exist.
 
-```bash
-cargo run -p openbitdo --
-cargo run -p openbitdo -- --mock
-```
+## Current Settings Contract
 
-## Historical note
-The temporary subcommand surface (`openbitdo ui` / `openbitdo run`) is historical (historical) and should not be used for current workflows.
+Persisted UI state uses `schema_version = 2` with these fields:
 
-## Headless library API
-Headless automation remains available to Rust callers through `bitdo_tui`:
-
-```bash
-run_headless(core, RunLaunchOptions { output_mode: HeadlessOutputMode::Json, ..Default::default() })
-```
-
-## Settings schema migration
-Current schema is `schema_version = 2` with fields:
 - `advanced_mode`
 - `report_save_mode`
 - `device_filter_text`
@@ -48,10 +26,21 @@ Current schema is `schema_version = 2` with fields:
 - `last_panel_focus`
 
 Compatibility behavior:
-- v1 settings files load with defaults for missing v2 fields.
-- if `advanced_mode = false`, `report_save_mode = off` is normalized to `failure_only`.
 
-## CI note
-The CLI smoke coverage now validates:
-- `openbitdo --help` exposes single-command option usage.
-- `openbitdo ui ...` and `openbitdo run ...` fail as unsupported forms (historical).
+- v1 settings still load with defaults for new fields.
+- invalid settings files now raise a warning and fall back to defaults instead of being silently accepted.
+
+## Current Library Contract
+
+OpenBitdo keeps headless automation as a Rust API, not a public CLI surface.
+The supported entry points remain:
+
+- `bitdo_tui::run_headless`
+- `bitdo_tui::RunLaunchOptions`
+- `bitdo_tui::HeadlessOutputMode`
+
+## Practical Migration Guidance
+
+- If you used the historical CLI subcommands, switch to `openbitdo` or `openbitdo --mock`.
+- If you need automation, call the Rust API instead of expecting a supported headless CLI.
+- If you document install paths, prefer Homebrew tap, AUR, tarball, or source build rather than old ad hoc command forms.