feat(launcher): thin primitive architecture + run_osascript hardening

- file_handlers: add script_template param to native:launch-from-cache
  (AppleScript or shell: prefix; falls back to hardcoded defaults when null)
- file_handlers: add native:copy-from-cache-to-temp as composable primitive
  (copies cached file to temp, returns path — caller handles launch logic)
- shell_handlers: harden native:run-osascript with temp .scpt file approach
  (replaces -e flag; handles multi-line scripts and paths with special chars)
- README: rewrite Native Bridge section — full method table, composable
  pattern example, configurable launch scripts note
- deploy/devices.conf: update IPs for devices 03-06, uncomment entries

README.md

@@ -194,35 +194,99 @@ explicitly coordinated across all devices.
 
 The bridge is exposed to the renderer via `contextBridge`. It can be accessed in the web UI via `window.aetherNative`.
 
-### Core Methods
+**Design principle:** The Electron app is a thin OS primitive layer. Business logic (which script
+runs for which file type, how to sequence operations, etc.) belongs in the SvelteKit/Svelte side
+where it can be changed without a rebuild and redeployment. Electron handlers should rarely need
+to change.
+
+### File Cache
 
 | Method | Description |
 | --- | --- |
-| `list_tools()` | Returns a JSON manifest of all available native functions. |
-| `launch_presentation({path, app})` | Launches a presentation with auto-focus and slideshow start. |
-| `control_presentation({app, action})` | Sends `next`, `prev`, `start`, or `stop` to active decks. |
-| `open_folder(path)` | Opens a local directory in the OS file explorer. |
-| `get_device_info()` | Returns hardware metadata (RAM, IPs, Hostname). |
+| `check_cache({cache_root, hash, hash_prefix_length?, verify_hash?})` | Checks if a file exists in the hashed cache. `verify_hash: true` re-hashes the file to confirm integrity. |
+| `download_to_cache({url, cache_root, hash, api_key, account_id, hash_prefix_length?})` | Streams a file from the API into the hashed cache. Verifies SHA-256 integrity before finalizing. |
+| `copy_from_cache_to_temp({cache_root, hash, temp_root, filename, hash_prefix_length?})` | **Preferred primitive.** Copies cached file to temp dir with original filename. Returns `{ success, path }`. The Svelte caller decides what to do next. |
+| `launch_from_cache({cache_root, hash, temp_root, filename, hash_prefix_length?, script_template?})` | Combines copy + launch. If `script_template` is provided, runs it (AppleScript or `shell:` prefixed command) instead of hardcoded extension logic. Falls back to built-in defaults when `null`. |
+
+### Shell & OS
+
+| Method | Description |
+| --- | --- |
+| `run_cmd({cmd, timeout?, return_stdout?})` | Async shell command execution. |
+| `run_cmd_sync({cmd})` | Synchronous shell command execution. |
+| `run_osascript(script)` | **Hardened.** Runs AppleScript via temp `.scpt` file — handles multi-line scripts and paths with spaces/special characters correctly. macOS only. |
+| `open_folder(path)` | Opens a directory in Finder / system file manager. |
+| `open_local_file_v2(path)` | Opens a file with its default OS application. |
+| `open_external({url, app?})` | Opens a URL in Chrome, Firefox, or the default browser. |
+| `kill_processes({process_name_li})` | Terminates processes by name. macOS/Linux: `pkill -f`. Windows: `taskkill /F`. |
+
+### Presentations (Phase 5 — legacy specialized handlers)
+
+| Method | Description |
+| --- | --- |
+| `launch_presentation({path, app?, os?})` | Platform-aware launcher. Resolves `[home]`/`[tmp]` placeholders. **Note:** uses legacy `-e` flag for AppleScript; prefer `copy_from_cache_to_temp` + `run_osascript` for new flows. |
+| `control_presentation({app, action})` | Slide navigation (`next`/`prev`/`start`/`stop`) for PowerPoint or Keynote via AppleScript. macOS only. |
+
+### System Management (Phase 5)
+
+| Method | Description |
+| --- | --- |
+| `get_device_config()` | Returns hydrated device config injected at startup from `seed.json` + API. |
+| `get_device_info()` | Returns OS metadata: platform, hostname, IPs, CPU count, free RAM, home/tmp paths. |
+| `window_control({action, value?})` | Electron window: maximize, minimize, restore, close, fullscreen, kiosk, devtools, reload. |
+| `set_wallpaper({path})` | Sets desktop wallpaper. macOS (AppleScript) + Linux (gsettings/Gnome). |
+| `power_control({action})` | Shutdown, reboot, or sleep. macOS + Linux. Requires sudo for shutdown/reboot. |
+| `set_display_layout({mode, configStr?})` | Mirror/extend displays via bundled `displayplacer` binary. macOS only. |
+| `manage_recording({action, options?})` | Screen recording via bundled `aperture` binary. macOS only. |
+| `update_app(args)` | **Stub.** Downloads update package but does not install. Not functional. |
+| `list_tools()` | Returns a self-describing manifest of all available bridge functions. |
+
+### Example Usage (preferred composable pattern)
 
-### Example Usage (UI Relay)
 ```typescript
 import * as native from '$lib/electron/electron_relay';
 
-// Launch a file from local cache
-await native.launch_presentation({ 
-    path: '[tmp]/my_deck.pptx', 
-    app: 'powerpoint' 
+// Step 1: copy the cached file to temp and get the resolved path
+const copy = await native.copy_from_cache_to_temp({
+    cache_root: $ae_loc.local_file_cache_path,
+    hash: event_file_obj.hash_sha256,
+    temp_root: $ae_loc.host_file_temp_path,
+    filename: event_file_obj.filename
 });
+if (!copy.success) { /* handle error */ return; }
 
-// Navigate slides
-await native.control_presentation({ 
-    app: 'powerpoint', 
-    action: 'next' 
-});
+// Step 2: run whatever script/command you want with that path
+// Option A — AppleScript (macOS):
+await native.run_osascript(`
+    tell application "Microsoft PowerPoint"
+        activate
+        open (POSIX file "${copy.path}")
+        delay 3
+    end tell
+`);
+
+// Option B — shell command:
+await native.run_cmd({ cmd: `open "${copy.path}"` });
+
+// Option C — use a template from device config (data-driven, no rebuild needed):
+const template = $ae_loc.native_device?.launch_scripts?.pptx;
+if (template) {
+    const script = template.replace(/\{\{path\}\}/g, copy.path);
+    await native.run_osascript(script);
+}
 ```
 
+### Configurable Launch Scripts (no rebuild needed)
+
+`launch_from_cache` and `launcher_file_cont.svelte` support per-extension script templates
+stored in `event_device.data_json.launch_scripts`. Keys are lowercase extensions (`pptx`, `key`,
+`pdf`, etc.); `default` is a catch-all. Templates use `{{path}}` as the file path placeholder.
+AppleScript strings run via `run_osascript`; prefix with `shell:` for shell commands.
+
+See `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` Section 8 for full details.
+
 ## 🛠️ Development
 
 - **Preload:** Logic defined in `src/preload/index.ts`.
-- **Handlers:** OS-level logic in `src/main/shell_handlers.ts` and `src/main/file_handlers.ts`.
+- **Handlers:** OS-level logic in `src/main/shell_handlers.ts`, `src/main/file_handlers.ts`, and `src/main/system_handlers.ts`.
 - **Types:** Shared TypeScript interfaces in `src/shared/types.ts`.