fix: clarify browser application guidance

src/apps/webapp/README.md

@@ -2,15 +2,39 @@
 
 WebApp is an experimental proof of concept for running Self-hosted LiveSync against a browser-authorised local Vault. It is not a replacement for the Obsidian plug-in, and it does not provide the plug-in's settings screen, command palette, or setup wizard.
 
+## Capabilities
+
+- Runs as a static application in the browser.
+- Reads and writes a user-selected Vault through the File System Access API.
+- Keeps previously selected directory handles in origin-scoped IndexedDB.
+- Loads and saves LiveSync settings in `.livesync/settings.json` inside the selected Vault.
+- Uses CouchDB as its primary continuous remote.
+- Provides optional P2P controls as a secondary connection.
+- Scans the Vault on start-up and when **Scan local files** is selected.
+- Watches external file changes automatically when `FileSystemObserver` is available.
+
+The WebApp itself does not require an application server, but synchronisation still requires a compatible remote or P2P peer.
+
+## Requirements
+
+WebApp requires:
+
+- a secure context, such as HTTPS or `localhost`;
+- `showDirectoryPicker()` and read-write access to the selected directory;
+- IndexedDB for saved directory handles and the local database; and
+- a CouchDB server which permits requests from the WebApp origin when CouchDB is used.
+
+Automated browser coverage uses Chromium. Other browsers, background execution, and remote types other than CouchDB remain experimental. Use feature detection rather than relying on a fixed browser-version list.
+
 ## Use
 
-WebApp requires a browser which provides the File System Access API and IndexedDB. Serve the built files over HTTPS, or from `localhost`, then open `webapp.html`.
+Serve the built files over HTTPS, or from `localhost`, then open `webapp.html`.
 
 1. Select the local Vault root.
 2. Create or edit `.livesync/settings.json` in that Vault.
 3. Reload WebApp to apply the settings.
 
-For example, a manually configured CouchDB connection includes:
+For example, a minimal manually configured CouchDB connection includes:
 
 ```json
 {
@@ -24,9 +48,47 @@ For example, a manually configured CouchDB connection includes:
 }
 ```
 
-The visible P2P controls are optional. Saving them does not select P2P as the main remote or mark an otherwise unconfigured Vault as configured.
+The settings must match the remote database, including any encryption and compatibility settings which are already in use. The file may contain credentials and passphrases, so protect it accordingly. Review individual values instead of copying an Obsidian `data.json` file wholesale.
 
-CouchDB must permit access from the WebApp origin. Other remote types, browser background behaviour, and browsers without the required file-system APIs remain experimental.
+### Optional P2P
+
+The visible P2P controls are optional. Saving them does not select P2P as the main remote or mark an otherwise unconfigured Vault as configured. Use **Scan local files** before offering existing Vault content to a peer when automatic file observation is unavailable.
+
+## Limitations
+
+- There is no general settings screen, setup wizard, or command palette.
+- Object Storage and other main-remote configurations remain experimental and are not covered by the current WebApp browser tests.
+- Without `FileSystemObserver`, external changes are detected only by a start-up or manual scan.
+- A browser may suspend the page, discard permissions, or evict origin-scoped storage.
+- The File System Access API is not available in every browser.
+- Customisation Sync and Obsidian-specific Vault features are unavailable.
+
+## Troubleshooting
+
+### A Vault cannot be opened
+
+- Confirm that WebApp is served over HTTPS or from `localhost`.
+- Grant read-write access when the browser prompts.
+- If a saved handle no longer has permission, select **Choose new vault folder** and choose the same directory again.
+
+### Settings are not loaded
+
+- Confirm that `.livesync/settings.json` exists under the selected Vault root.
+- Confirm that the file contains one valid JSON object.
+- Reload WebApp after editing the file.
+- Check the status line and browser console for the first reported error.
+
+### External file changes are not detected
+
+- Select **Scan local files** after making changes outside WebApp.
+- Check whether the browser provides `FileSystemObserver`.
+- Keep the page open while automatic watching or synchronisation is expected.
+
+### CouchDB does not synchronise
+
+- Confirm the URL, credentials, database name, encryption settings, and compatibility settings.
+- Confirm that CouchDB permits requests from the WebApp origin.
+- Check the browser network inspector and console for the rejected request.
 
 ## Development
 
@@ -41,6 +103,8 @@ npm run test:browser --workspace livesync-webapp
 
 The production files are written to `src/apps/webapp/dist/`. App-owned unit tests are stored in `test/apps/webapp/`, outside the Community Review source boundary. The browser test builds the production artefact, selects an OPFS-backed test Vault in Chromium, and verifies start-up and P2P setting isolation.
 
+## Composition
+
 `WebAppRuntime.ts` owns the LiveSync service composition and lifecycle. `main.ts` owns Vault selection and the small browser shell, while `adapters/`, `managers/`, and `serviceModules/` provide the File System Access API boundary.
 
 ## Licence

src/apps/webapp/managers/FSAPIStorageEventManagerAdapter.ts

@@ -194,11 +194,15 @@ class FSAPIWatchAdapter implements IStorageEventWatchAdapter {
     ) {}
 
     async beginWatch(handlers: IStorageEventWatchHandlers): Promise<void> {
-        // Use FileSystemObserver if available (Chrome 124+)
+        // Use FileSystemObserver when the browser provides it.
         const FileSystemObserver = (compatGlobal as GlobalWithFileSystemObserver).FileSystemObserver;
         if (!FileSystemObserver) {
-            this.addLog("FileSystemObserver is not available; file watching is disabled", LOG_LEVEL_INFO, "fsapi-watch");
-            this.addLog("Chrome 124 or later supports real-time file watching", LOG_LEVEL_INFO, "fsapi-watch");
+            this.addLog(
+                "FileSystemObserver is not available; file watching is disabled",
+                LOG_LEVEL_INFO,
+                "fsapi-watch"
+            );
+            this.addLog("Use 'Scan local files' after external changes", LOG_LEVEL_INFO, "fsapi-watch");
             return Promise.resolve();
         }