cleanroom: modernize tui diagnostics and align release packaging

MIGRATION.md

@@ -1,54 +1,57 @@
 # OpenBitdo Migration Notes
 
+## Scope
+This migration restores the single-command `openbitdo` CLI contract and removes the `ui`/`run` subcommand surface from user-facing usage.
+
 ## What changed
 - `bitdoctl` was removed.
 - `openbitdo cmd ...` was removed.
-- JSON report/output flags were removed from user-facing flows.
-- OpenBitdo now focuses on a single beginner entrypoint: `openbitdo`.
+- `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.
+
+## 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 |
 
 ## New usage
 From `/Users/brooklyn/data/8bitdo/cleanroom/sdk`:
 
+Interactive dashboard:
+
 ```bash
 cargo run -p openbitdo --
-```
-
-Optional mock mode:
-
-```bash
 cargo run -p openbitdo -- --mock
 ```
 
-## Beginner flow
-1. Launch `openbitdo`.
-2. Select a detected device.
-3. Click or choose an action:
-- `Update` (guided firmware flow)
-- `Diagnose` (quick readiness checks)
-- `Refresh`
-- `Quit`
-4. Confirm with a simple `y`/`yes` prompt before firmware transfer.
+## Historical note
+The temporary subcommand surface (`openbitdo ui` / `openbitdo run`) is historical (historical) and should not be used for current workflows.
 
-## Firmware behavior
-- OpenBitdo first attempts a recommended firmware download.
-- If download or verification fails, it immediately asks for a local firmware file (`.bin`/`.fw`).
-- Detect-only devices remain blocked from firmware write operations with a clear reason.
+## Headless library API
+Headless automation remains available to Rust callers through `bitdo_tui`:
 
-## New device-specific wizards
-- JP108 (`0x5209`/`0x520a`):
-  - Dedicated button mapping for `A`, `B`, and `K1-K8`
-  - Auto-backup before write
-  - One-click restore if needed
-  - Guided button test text after apply
-- Ultimate2 (`0x6012`/`0x6013`):
-  - Slot + mode + core map editing
-  - Auto-backup and rollback path
-  - Guided button test text after apply
+```bash
+run_headless(core, RunLaunchOptions { output_mode: HeadlessOutputMode::Json, ..Default::default() })
+```
 
-## CI changes
-- Hardware CI split into per-family jobs:
-- `hardware-dinput` (required)
-- `hardware-standard64` (required)
-- `hardware-ultimate2` (required)
-- `hardware-108jp` (required)
-- `hardware-jphandshake` (gated until fixture availability)
+## Settings schema migration
+Current schema is `schema_version = 2` with fields:
+- `advanced_mode`
+- `report_save_mode`
+- `device_filter_text`
+- `dashboard_layout_mode`
+- `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).