update developer docs

Fixes ibm-functions#1051

docs/dev/README.md

@@ -7,7 +7,7 @@ cross-platform, at least to the extent that the framework has builds
 for Windows, macOS, and Linux.
 
    - [Quick Start Guide](#quick-start-guide)
-   - [Setting up a Local OpenWhisk](#setting-up-a-local-openwhisk)
+   - [Acquiring an OpenWhisk Authorization Key](#acquiring-an-openwhisk-authorization-key)
    - [Lay of the land](lay-of-the-land.md) describes the structure and
      layout of the code
    - [Running Local Tests](local-testing.md) shows how to run the test
@@ -16,25 +16,83 @@ for Windows, macOS, and Linux.
 ## Quick Start Guide
 
 Developing against a local OpenWhisk is highly recommended. This is
-not a strict requirement, for code editing. To run local tests,
-however, a local OpenWhisk is required. Once you have configured your
+not a strict requirement. However, to run local tests, a local
+OpenWhisk is currently required. See below for guidance on acquiring
+an OpenWhisk authorization key. Once you have configured your
 `~/.wskprops` to point to your desired OpenWhisk service, you can
 begin Shell development:
 
 ```bash
-$ cd app
+$ git clone git@github.com:ibm-functions/shell.git
+$ cd shell
 $ npm install
-$ ./bin/fsh shell
+$ ./fsh.js
 ```
 
-If you see the Shell open up, then you are ready to go. For the most
-part, any edits to UI code can be incorporated into that running
-instance by simply reloading the Shell, as you would a browser window;
-e.g. Command+R on macOS, or Control+R on Windows and Linux. This
-allows you to quickly edit and debug changes, without slow rebuild and
-restart steps.
+If you see the help menu in your terminal, then so far, so good. Note:
+if you look at the package.json's `bin` field, you will observe that
+the `fsh.js` launcher is named `fsh` when non-developers install via
+e.g. `npm install ibm-functions/shell`.
 
-## Setting up a Local OpenWhisk
+### Installing the Graphical Bits
+
+By default, this `npm install` will not install the graphical
+components, i.e. Electron. This design allows for lightweight
+installations that support headless environments.  To install the
+graphical bits:
+
+```bash
+npm run install-ui
+./fsh.js shell
+```
+
+If you see the Shell UI open up, then this part was successful.
+
+## The Edit-Debug Cycle
+
+For the most part, any edits to UI code can be incorporated into that
+running instance by simply reloading the Shell, as you would a browser
+window; e.g. Command+R on macOS, or Control+R on Windows and
+Linux. This allows you to quickly edit and debug changes, without slow
+rebuild and restart steps.
+
+### More Advanced Scenarios
+
+There are several cases where a simple reload will not suffice to
+realize your changes.
+
+ 1. **Adding new commands** For efficiency, the Shell relies on a
+    precompiled model of the command tree. This allows the Shell to
+    load plugin code lazily, as needed by command execution. Thus, if
+    you add a new command, you must recompile the command
+    registry: `cd app && npm run compile`
+
+ 2. **Changing code in the main process** Electron applications
+    consist of two groups of processes: the renderer processes
+    (e.g. one per window, one per web view, one per web worker, etc.),
+    and the "main" or server-side processes. The javascript code
+    directly within the `app` directory (e.g. `main.js` and
+    `headless.js`) are run in the main/server process. Thus, changes
+    to these files requires a restart of the application, which you
+    can do by quitting any instances of the the graphical UI and
+    restarting them via `./fsh.js shell`.
+
+## Acquiring an OpenWhisk Authorization Key
+
+Currently, the Shell assumes you have an OpenWhisk authorization
+key. You have two options for acquiring one:
+
+ - Using IBM Cloud Functions
+ - Using a Local OpenWhisk
+
+### Option 1: Using IBM Cloud Functions
+
+ 1. [Install `ibmcloud`](https://console.bluemix.net/docs/cli/reference/bluemix_cli/get_started.html)
+ 2. `ibmcloud login`
+ 3. `ibmcloud target --cf`
+ 4. `ibmcloud wsk list`
+
+### Option 2: Setting up a Local OpenWhisk
 
 For complete details, please consult
 the