microbit-foundation · microbit-matt-hillsdon · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026 · Apr 28, 2026
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -1,6 +1,6 @@
 # Migration guide (v0 → v1)
 
-These breaking changes are currently available as `0.9.0-apps.alpha.N` pre-releases on npm. Once testing is complete they will be published as `1.0.0`.
+This guide covers the breaking changes between `0.x` and `1.0`.
 
 ## Subpath exports
 

diff --git a/README.md b/README.md
@@ -4,11 +4,11 @@
 
 A TypeScript library for connecting to micro:bit devices via USB and Bluetooth. Works in browsers (via WebUSB and Web Bluetooth) and in native iOS/Android apps (Bluetooth only, via [Capacitor](https://capacitorjs.com/)).
 
-[Available on NPM](https://www.npmjs.com/package/@microbit/microbit-connection). Migrating from an earlier version? See the [migration guide](https://github.com/microbit-foundation/microbit-connection/blob/apps/MIGRATION.md).
+[Available on NPM](https://www.npmjs.com/package/@microbit/microbit-connection). Migrating from an earlier version? See the [migration guide](https://github.com/microbit-foundation/microbit-connection/blob/main/MIGRATION.md).
 
 ### Demo apps
 
-- [Demo app](https://microbit-connection.pages.dev/) ([source](apps/demo/)) — WebUSB, Web Bluetooth, and Capacitor for native mobile
+- [Demo app](https://microbit-connection.pages.dev/) ([source](https://github.com/microbit-foundation/microbit-connection/tree/main/apps/demo)) — WebUSB, Web Bluetooth, and Capacitor for native mobile
 
 ### Projects using this library
 
@@ -112,7 +112,7 @@ To disable this behaviour, pass `pauseOnHidden: false`:
 const usb = createUSBConnection({ pauseOnHidden: false });
 ```
 
-For more examples see the [demo app source](apps/demo/src/).
+For more examples see the [demo app source](https://github.com/microbit-foundation/microbit-connection/tree/main/apps/demo/src).
 
 ### Connect via Bluetooth
 
@@ -129,7 +129,7 @@ await bluetooth.connect();
 console.log("Connection status: ", bluetooth.status); // "Connected"
 ```
 
-For more examples see the [demo app source](apps/demo/src/).
+For more examples see the [demo app source](https://github.com/microbit-foundation/microbit-connection/tree/main/apps/demo/src).
 
 ### Error handling
 
@@ -161,11 +161,11 @@ Open link hex files are not common. The most common source is the micro:bit Crea
 
 ### No suitable services on the micro:bit to flash
 
-- **Hex with no partial flashing or DFU control service (V1)**: This is currently the case for CreateAI data collection hex files for micro:bit V1. There's nothing that can be done via Bluetooth. When the apps branch of CreateAI is released this will eventually resolve itself (or at least, we'll stop creating more such micro:bits). Workaround: flash via WebUSB or drag and drop from a computer. The equivalent V2 hex does have the Secure DFU service (but not partial flashing) which we support.
+- **Hex with no partial flashing or DFU control service (V1)**: Some older CreateAI data-collection hex files for micro:bit V1 fall into this category. There's nothing that can be done via Bluetooth. Workaround: flash via WebUSB or drag and drop from a computer. The equivalent V2 hex does have the Secure DFU service (but not partial flashing) which we support.
 
 ## Hardware testing
 
-The [hardware test app](apps/hardware-test/) is a human-in-the-loop test runner for USB flashing. It covers partial and full flash, flash fallback paths, serial data integrity after flash, and reconnection after unplug. Run it with:
+The [hardware test app](https://github.com/microbit-foundation/microbit-connection/tree/main/apps/hardware-test) is a human-in-the-loop test runner for USB flashing. It covers partial and full flash, flash fallback paths, serial data integrity after flash, and reconnection after unplug. Run it with:
 
 ```bash
 cd apps/hardware-test
@@ -178,7 +178,7 @@ The tests prompt you for physical actions (plugging/unplugging) and verify the r
 
 This software is under the MIT open source license.
 
-[SPDX-License-Identifier: MIT](LICENSE)
+[SPDX-License-Identifier: MIT](https://github.com/microbit-foundation/microbit-connection/blob/main/LICENSE.md)
 
 We use dependencies via the NPM registry as specified by the package.json file under common Open Source licenses.
 

diff --git a/packages/microbit-connection/.gitignore b/packages/microbit-connection/.gitignore
@@ -0,0 +1,3 @@
+# Copied in by prepack from the repo root, removed by postpack.
+README.md
+LICENSE.md
diff --git a/packages/microbit-connection/package.json b/packages/microbit-connection/package.json
@@ -5,7 +5,9 @@
   "module": "./build/esm/index.js",
   "types": "./build/esm/index.d.ts",
   "files": [
-    "build"
+    "build",
+    "README.md",
+    "LICENSE.md"
   ],
   "sideEffects": false,
   "exports": {
@@ -67,7 +69,9 @@
     "build": "npm run build:lib",
     "docs": "typedoc",
     "ci": "npm run build:lib && npm run test",
-    "test": "vitest"
+    "test": "vitest",
+    "prepack": "cp ../../README.md ../../LICENSE.md .",
+    "postpack": "rm -f README.md LICENSE.md"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",

diff --git a/packages/microbit-connection/src/device.ts b/packages/microbit-connection/src/device.ts
@@ -30,7 +30,7 @@ export type DeviceErrorCode =
   // -- User cancelled (no error UI needed) --
 
   /**
-   * **BLE.** The operation was cancelled via an {@link AbortSignal}
+   * **BLE.** The operation was cancelled via an `AbortSignal`
    * supplied by the caller. No user-facing error is needed.
    */
   | "aborted"

diff --git a/packages/microbit-connection/src/service-events.ts b/packages/microbit-connection/src/service-events.ts
@@ -54,7 +54,7 @@ export interface PinValue {
  *
  * Contains only the input pins whose values changed since the last
  * notification, up to a firmware limit of 10 pins per event
- * (lowest-numbered first). Use {@link MicrobitBluetoothConnection.readPins}
+ * (lowest-numbered first). Use {@link @microbit/microbit-connection/bluetooth!MicrobitBluetoothConnection.readPins}
  * to read all input pins on demand.
  */
 export interface PinData {
@@ -72,7 +72,7 @@ export interface ButtonActionData {
 
 /**
  * A raw event from the micro:bit's message bus, received via the
- * BLE Event Service. Use {@link MicrobitBluetoothConnection.subscribeToEvent}
+ * BLE Event Service. Use {@link @microbit/microbit-connection/bluetooth!MicrobitBluetoothConnection.subscribeToEvent}
  * to register which events the micro:bit should forward.
  */
 export interface MicrobitEventData {