diff --git a/README.md b/README.md
index 47a7523..8569aec 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ Core capabilities include:
 
 - Docs index: [docs/README.md](docs/README.md)
 - WebUSB / SDR interaction subsystem: [docs/webusb/README.md](docs/webusb/README.md)
+- Manual / hardware tests: [test-apps/README.md](test-apps/README.md)
 
 ## Repository layout
 
@@ -112,11 +113,13 @@ Example test apps live in `test-apps`. To run them:
 ```bash
 cd test-apps
 npm install
-npm run test:usb   # runs the USB test script (requires appropriate permissions/flags)
+npm run test:usb
 ```
 
 Note: WebUSB requires HTTPS or localhost and browser support. Running tests that access USB devices may require additional browser flags or permissions.
 
+Manual test notes and troubleshooting: [test-apps/README.md](test-apps/README.md)
+
 ## Environment / Configuration
 
 - `packages/nestjs-microservice` reads configuration from environment variables (prefixed with `WEBSDR_` in places). See the module entry and code for exact variable names.
diff --git a/docs/README.md b/docs/README.md
index 9497e1d..afe9829 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -22,6 +22,14 @@ Diagrams live in [webusb/diagrams/](webusb/diagrams/) (Mermaid sources `.mmd` an
 
 ---
 
+## Manual / Hardware Tests
+
+Manual (hardware-in-the-loop) testing docs:
+
+- [../test-apps/README.md](../test-apps/README.md)
+
+---
+
 ## Diagram Rendering (Mermaid)
 
 Diagrams are written in **[Mermaid](https://mermaid.js.org/) (`.mmd`)** and rendered to **SVG** for stable display in GitHub.
diff --git a/generate_rst_docs.sh b/generate_rst_docs.sh
index 8ff6db7..5b5ea8a 100755
--- a/generate_rst_docs.sh
+++ b/generate_rst_docs.sh
@@ -11,6 +11,7 @@ pandoc -s -f gfm -t rst --wrap=preserve -o $DIST_DIR/core.rst packages/core/READ
 pandoc -s -f gfm -t rst --wrap=preserve -o $DIST_DIR/frontend-core.rst packages/frontend-core/README.md
 pandoc -s -f gfm -t rst --wrap=preserve -o $DIST_DIR/nestjs-microservice.rst packages/nestjs-microservice/README.md
 pandoc -s -f gfm -t rst --wrap=preserve -o $DIST_DIR/vue3-components.rst packages/vue3-components/README.md
+pandoc -s -f gfm -t rst --wrap=preserve -o $DIST_DIR/test-apps.rst test-apps/README.md
 
 # Update links in the generated .rst files
 sed -E -i \
diff --git a/packages/core/README.md b/packages/core/README.md
index f8fef04..867c86f 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -187,6 +187,8 @@ From the repository root:
 
 ```bash
 npm install
+npm run build
+npm test --workspace=packages/core
 ```
 
 From this package folder:
diff --git a/packages/frontend-core/README.md b/packages/frontend-core/README.md
index dde7bab..7fd92b5 100644
--- a/packages/frontend-core/README.md
+++ b/packages/frontend-core/README.md
@@ -349,6 +349,8 @@ From the repository root:
 
 ```bash
 npm install
+npm run build
+npm test --workspace=packages/frontend-core
 ```
 
 From this package folder:
diff --git a/packages/nestjs-microservice/README.md b/packages/nestjs-microservice/README.md
index b0898fd..acec078 100644
--- a/packages/nestjs-microservice/README.md
+++ b/packages/nestjs-microservice/README.md
@@ -178,6 +178,8 @@ From the repository root:
 
 ```bash
 npm install
+npm run build
+npm test --workspace=packages/nestjs-microservice
 ```
 
 From this package folder:
diff --git a/packages/vue3-components/README.md b/packages/vue3-components/README.md
index b8ceca2..02cbdb2 100644
--- a/packages/vue3-components/README.md
+++ b/packages/vue3-components/README.md
@@ -640,6 +640,8 @@ From the repository root:
 
 ```bash
 npm install
+npm run build
+npm test --workspace=packages/vue3-components
 ```
 
 From this package folder:
diff --git a/test-apps/README.md b/test-apps/README.md
new file mode 100644
index 0000000..52cf8fa
--- /dev/null
+++ b/test-apps/README.md
@@ -0,0 +1,67 @@
+# Test apps
+
+This folder contains **manual / hardware-in-the-loop test scripts** for the WebSDR monorepo.
+
+Currently the main entry is [usb-test.ts](usb-test.ts#L1) — a WebUSB smoke test that opens a device, runs RX streaming, then TX streaming.
+
+## Prerequisites
+
+- **Node.js + npm** installed.
+- A supported SDR device connected via USB.
+- **Permissions to access USB devices** on your OS.
+  - On Linux you might need udev rules (recommended) or to run with elevated privileges depending on your setup.
+
+## USB smoke test (RX + TX)
+
+The script roughly does:
+
+1. Ensure a WebUSB implementation exists (`ensureWebUsb()`).
+2. Initialize control module (`initControl()`).
+3. Request/select a USB device (`requestDevice()`).
+4. Open the device and the control interface.
+5. Run an RX streaming loop and print stats.
+6. Run a TX streaming loop.
+7. Close everything.
+
+### Run
+
+From the repository root:
+
+```bash
+cd test-apps
+npm install
+npm run test:usb
+```
+
+### What you should see
+
+- Logs about selecting/opening the device.
+- `RX stream started` → packet stats → `RX stream stopped`.
+- `TX stream started` → packet stats → `TX stream stopped`.
+- Final `USB test completed`.
+
+### Configuration
+
+You can tune parameters by editing constants near the top of [usb-test.ts](usb-test.ts#L1), for example:
+
+- `packetSize`
+- `rxConfig` / `txConfig` (frequency, bandwidth, samplerate, gain)
+
+### Troubleshooting
+
+- **Permission denied / libusb errors**
+  - Ensure your user has access to the USB device.
+  - On Linux this typically means udev rules.
+
+- **Timeout waiting for packets**
+  - The RX test uses a finite safety timeout while waiting for in-flight packets.
+  - Check USB stability, device firmware, and that streaming is supported.
+
+- **No WebUSB implementation found**
+  - The underlying WebUSB layer attempts to use `usb` (preferred) or fall back to `webusb`.
+  - Verify dependencies are installed and compatible with your platform.
+
+### Safety / regulatory note (TX)
+
+The TX part may cause RF transmission depending on your device and setup.
+Only run TX tests if you understand your hardware chain and comply with local regulations (use appropriate shielding / dummy load where applicable).