Enriched README

README.md

@@ -4,30 +4,144 @@ This extension allows you to run Platypush commands on remote hosts as well as
 custom scripts, build custom actions as scripts that can access both the browser
 API and Platypush API, and attach hooks to events generated by remote Platypush systems.
 
-Article on the motivations behind this extensions and some examples to get started: https://medium.com/@automationguru/one-browser-extension-to-rule-them-all-3118dc7f9c9b
+Article on the motivations behind this extensions and some examples to get started: https://blog.platypush.tech/article/One-browser-extension-to-rule-them-all
+
+This extension is not meant to be used as a standalone browser extension, but rather as a companion to the Platypush server.
+
+It is meant to be used in conjunction with the Platypush server, which provides the backend functionality and APIs that the extension relies on.
+
+**Note**: this extension is currently _only compatible with Firefox_, as it relies on permissions only available on Manifest V2 - now unsupported on Chromium-based browsers.
 
 ## Installation
 
+### Official releases
+
+The official version is available on the [Firefox Add-ons store](https://addons.mozilla.org/en-US/firefox/addon/platypush/).
+
+### Manual installation
+
 Install the dependencies:
 
 ```bash
 npm install
 ```
 
-Dev installation (requires npm+Vue cli tools):
-
-```bash
-npm run build:dev
-```
-
-Production installation (requires npm):
-
-```bash
-npm run build
-```
-
 Generate the extension .zip file:
 
 ```bash
 npm run build-zip
 ```
+
+Open `about:debugging#/runtime/this-firefox` in Firefox, click on "Load
+Temporary Add-on" and select the generated `.zip` file - it should be located
+under the `dist-zip` directory.
+
+### Dev installation
+
+```bash
+npm run build:dev
+```
+
+### Testing
+
+```
+npm run watch:dev
+```
+
+Then follow the procedure for manual installation above to load the extension
+in Firefox. Any changes to the source files will be automatically picked up.
+
+## Configuration
+
+Once installed, click on the popup icon in the browser toolbar and configure your Platypush service.
+
+![Screenshot of the add device form](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/add-device.png)
+
+### Authentication
+
+You have two options to authenticate:
+
+- You can use a Platypush API token, which you can generate in the Platypush web interface.
+  This is probably more portable and reliable, as it does not require you to
+  log in to the Platypush web interface in the browser, and the extension won't
+  stop working if you log out of the web interface.
+
+- You can just enter the URL of your Platypush server and log in with your
+  username and password.
+
+### Backup and restore
+
+You can backup your configuration directly to one of your remote Platypush
+hosts by clicking on the "Backup" button in the configuration tab.
+
+![Screenshot of the configuration tab](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/config.png)
+
+The configuration file will automatically be backed up under
+`<WORKDIR>/webext/config.json` (usually
+`~/.local/share/platypush/webext/config.json`).
+
+From the configuration tab you can also restore the configuration from a remote
+host, a URL or a local file.
+
+It is also possible to manually modify the configuration JSON, if you know what
+you are doing.
+
+## Usage
+
+Once you have your extension configured, you can use it to run commands on your
+Platypush services directly from the browser.
+
+It also provides a native JavaScript API that you can use to run more complex
+commands, or also to run commands that run entirely in your browser - similar
+to what e.g. GreaseMonkey/TamperMonkey do.
+
+### Running and storing actions
+
+Select one of your configured devices and click the "_Run Action_" button to
+run a command on it.
+
+You'll have a nice autocomplete form to help you find the command you want to
+run (your custom defined procedures will also be available in the list), as
+well as documentation about the command and its parameters.
+
+![Screenshot of the run action tab](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/run.png)
+
+Click on _Run_ to execute the command, or on _Save Action_ if you want to save
+it to in your list.
+
+The save action form will let you define a name for the action, a description,
+an icon (it supports [FontAwesome](https://fontawesome.com/icons) classes), an
+icon color, a category, a list of devices (actions can be installed on multiple
+devices), and, quite importantly, a keybinding that can be used to run the
+action anywhere in the browser.
+
+![Screenshot of the save action tab](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/edit-action.png)
+
+I personally find the keybinding the feature of this extension that I use the most.
+
+While it's possible to run actions from the extension popup or the right click,
+I find it very convenient to map the 10 actions I use the most (lights and
+music control, save the current web page to Wallabag etc.) to the
+`Ctrl+Alt+<0-9>` keys, so that I can run them from anywhere in the browser.
+
+### Script mode
+
+The _Request_ mode is the most straightforward way to run commands directly on
+your Platypush services, but you can also configured more complex actions by
+leveraging the _Script_ mode in the _Run_ tab.
+
+![Screenshot of the run action tab in script mode](https://platypush-static.s3.nl-ams.scw.cloud/screenshots/webext/script.png)
+
+In this mode you can write a JavaScript `async` callback that will be run
+when the action is executed.
+
+The callback will receive two arguments:
+
+- `app`: an object that provides access to the Platypush API, which you can use
+  to run commands on your Platypush services.
+- `args`: an object that contains the parameters passed to the action when it
+  was run.
+
+The `app` object exposes many useful methods that you can use to run commands,
+access the browser API, and more. A comprehensive example is available
+[here](https://gist.github.com/BlackLight/d80c571705215924abc06a80994fd5f4).