update docs

Author: ThomasFarstrike

docs/architecture/intents.md

@@ -814,6 +814,78 @@ class WiFiActivity(Activity):
 
 **Pattern:** Method chaining with `startActivityForResult()` for specialized camera modes.
 
+---
+
+## Deep Links & URL Handling
+
+MicroPythonOS supports opening URLs (e.g., from QR codes) through a deep-link mechanism. The system parses the URL and either opens the App Store on a linked app or dispatches an intent to a third-party URL handler.
+
+### Official Store Links
+
+QR codes can point directly to an app in the App Store using these link formats:
+
+```
+https://apps.micropythonos.com/app/<app_id>[?v=<min_version>&s=<source>]
+microPythonOS://app/<app_id>[?...]
+mpos://app/<app_id>[?...]
+```
+
+All three forms are equivalent and case-insensitive (`MPOS://APP/COM.EXAMPLE.PAINT` works too). The link only carries the app's identity — never a download URL — so the App Store resolves it against its trusted catalog.
+
+Opening a store link launches the App Store on the linked app's detail page:
+
+```python
+from mpos.content.deeplink import open_url
+
+open_url("https://apps.micropythonos.com/app/com.example.myapp")
+```
+
+### Third-Party URL Handlers
+
+Apps can register URL handlers in their `MANIFEST.JSON` via a `urlPattern` in an activity's `intent_filters`:
+
+```json
+{
+  "activities": [
+    {
+      "entrypoint": "main.py",
+      "classname": "MainActivity",
+      "intent_filters": [
+        { "action": "view_url", "urlPattern": "https://store.acme.example/app/*" }
+      ]
+    }
+  ]
+}
+```
+
+Rules for `urlPattern`:
+
+- Must look like `scheme://host/...` with a literal host (no wildcards in host).
+- A trailing `*` is the only wildcard allowed and matches any suffix.
+- Patterns matching the official store host (`apps.micropythonos.com`) or the `mpos://` / `microPythonOS://` schemes are reserved for the system and rejected at registration.
+- Matching is a case-insensitive scheme-and-host prefix match.
+
+When a URL is opened, the system checks for matching third-party handlers. One match dispatches directly; several open the chooser. No sticky default is set, so a later-installed app is never permanently shadowed.
+
+```python
+from mpos.content.deeplink import open_url
+
+# Dispatches to the app whose urlPattern matches the URL
+open_url("https://store.acme.example/app/123")
+```
+
+### QR Code Integration
+
+QR scanners (e.g., the Camera app) can check whether decoded text is a dispatchable link:
+
+```python
+from mpos.content.deeplink import open_action_label
+
+label = open_action_label(scanned_text)
+if label:
+    print(f"Offer action: {label}")  # "Open in App Store" or "Open link"
+```
+
 ## Best Practices
 
 ### 1. Choose the Right Intent Type
@@ -991,7 +1063,7 @@ MicroPythonOS Intents are inspired by Android's Intent system but simplified for
 | **Intent Filters** | ✅ Manifest + programmatic | ✅ In manifest | File-type filters in `MANIFEST.JSON`, generic handlers via code |
 | **Categories** | ❌ Not supported | ✅ Supported | Simplified routing |
 | **Data Types** | ⚠️ Path patterns | ✅ MIME types | `pathPattern` suffix matching; `mimeType` is stored but not used for matching |
-| **URI Schemes** | ❌ Not matched | ✅ Supported | No scheme filtering |
+| **URI Schemes** | ✅ `mpos://` / `microPythonOS://` | ✅ Supported | Official schemes reserved for system; third-party `urlPattern` matching available |
 | **Chooser UI** | ✅ ChooserActivity | ✅ Intent chooser | Custom implementation |
 | **Result Callbacks** | ✅ Callback-based | ✅ onActivityResult() | Different mechanism |
 | **Method Chaining** | ✅ putExtra() returns self | ❌ No chaining | MicroPythonOS advantage |

docs/frameworks/download-manager.md

@@ -78,6 +78,17 @@ The `DownloadManager.download_url()` method automatically detects whether it's c
 
 This means you can use the same API in both async and sync code without any wrapper functions.
 
+## Redirect Handling
+
+DownloadManager follows HTTP redirects with the following constraints:
+
+- **Status codes followed:** 301 (Moved Permanently), 302 (Found), 303 (See Other).
+- **Status codes NOT followed:** 307 (Temporary Redirect), 308 (Permanent Redirect). These are treated as the final response.
+- **Maximum redirects: 1 hop.** The HTTP client (`aiohttp`) makes at most 2 requests per call — the original URL plus one redirect. A chain of 2 or more redirects will fail: the final redirect response body (typically empty) is treated as the download content, resulting in a parse error or corrupt file.
+
+!!! warning
+    If you need to redirect `https://updates.micropythonos.org/...` to `https://updates.micropythonos.com/...`, ensure the `.com` endpoint responds directly with a 200 — do not chain another redirect. A 2-hop chain (`.org` → `.com` → `.com?__direct=1`) will exhaust the redirect budget.
+
 ## API Reference
 
 ### `DownloadManager.download_url()`

docs/frameworks/notification-manager.md

@@ -76,7 +76,11 @@ Available sounds:
 | `Scale up` | `scale_up:d=32,o=5,b=100:c,c#,d#,e,f#,g#,a#,b` |
 | `Superhappy` | `superhappy:d=8,o=5,b=635:c,e,g,c,e,g,c,e,g,c6,e6,g6,c6,e6,g6,c7,e7,g7,c7,e7,g7,c7,e7,g7` |
 
-The default sound is `Coin`. If no buzzer output is available, the notification posts silently. Apps can change the sound programmatically:
+The default sound is `Coin`.
+
+On macOS desktop builds the notification buzzer sound is skipped because it was causing `tests/test_graphical_topmenu_drawer.py` to hang on the GitHub test workflow, possibly because the GitHub CI server doesn't have a sound card. It would be better to only skip this on the CI server, or only skip it if there's no sound card.
+
+On other platforms, if no buzzer output is available, the notification posts silently. Apps can change the sound programmatically:
 
 ```python
 from mpos import SharedPreferences

docs/os-development/automated-testing.md

@@ -63,4 +63,29 @@ To run all unit tests, do:
 ./tests/unittest.sh --ondevice # this takes a long time
 ```
 
+## Test Runner Flags
+
+The `test_runner.py` script (used by `unittest.sh` internally) supports these additional flags:
+
+| Flag | Description |
+|------|-------------|
+| `--no-install-test-apps` | Skip automatic installation of test apps before on-device runs. By default, `--ondevice` runs call `install_test_apps.sh` automatically. |
+| `--logserial <filename>` | Write raw serial output to a file for debugging communication issues. |
+| `--coverage` | Enable code coverage tracking on desktop builds (requires a coverage build — see `./scripts/build_mpos.sh unix coverage`). |
+| `--coverage-save <file.json>` | Save coverage data to a JSON file for later aggregation or HTML report generation. |
+| `--coverage-load <file.json>` | Load previously saved coverage data to merge with the current run. |
+
+### Coverage Example
+
+```
+# Build with coverage support
+./scripts/build_mpos.sh unix coverage
+
+# Run tests with coverage and save results
+python3 scripts/test_runner.py --coverage --coverage-save cov.json tests/test_a.py tests/test_b.py
+
+# Generate an HTML report
+python3 scripts/coverage_report.py cov.json -o coverage/index.html
+```
+
 

docs/os-development/running-on-desktop.md

@@ -112,6 +112,16 @@ Native Windows builds are not supported. [Users report](https://github.com/Micro
 
 ---
 
+## Keyboard shortcuts
+
+The desktop emulator supports these keyboard shortcuts:
+
+| Shortcut | Action |
+|----------|--------|
+| Ctrl+Shift+S (Cmd+Shift+S on macOS) | Save a screenshot as BMP in the working directory |
+
+Screenshots are saved with a timestamped filename like `screenshot-YYYYMMDD-HHMMSS.bmp`. The path is printed to the console so you know exactly where the file was written.
+
 ## Deploying to hardware
 
 Once your app works on desktop, install it on a supported ESP32 device.