add more screenshots and otherwise expand README.md
diff --git a/README.md b/README.md
index 5625fed..d863086 100644
--- a/README.md
+++ b/README.md
@@ -1,45 +1,43 @@
# OpenWhisk Debugger
-This project currently supports debugging OpenWhisk actions written in NodeJS, Python, and Swift. The debugger will arrange things so that the actions you wish to debug will be offloaded from the main OpenWhisk servers and instead run on your laptop. You can then, from within the debugger, inspect and modify values, and even modify code. At this point in time, the modifications will be one-time only. In the near future, we hope to add the ability to push any code updates back to OpenWhisk.
+This project currently supports debugging [OpenWhisk](https://console.ng.bluemix.net/openwhisk) actions written in NodeJS, Python, and Swift. The debugger will arrange things so that the actions you wish to debug will be offloaded from the main OpenWhisk servers and instead run on your laptop. You can then, from within the debugger, inspect and modify values. For NodeJS actions, you can even modify code and publish those changes back to the OpenWhisk servers.
-The debugger currently supports inspecting individual actions and actions within sequences. In the near future, we hope to add the ability to debug actions run from rules as well.
+The debugger currently supports inspecting an individual action, as well as invocations of this action as it occurs within **sequences** or **rules**. For example, if you have an OpenWhisk rule that fires a given action in response to a some trigger, you can attach to that action and debug, on your laptop, invocations triggered by the cloud.
## Usage
Start the debug client:
-```
-% cd client
-% ./wskdb
-Welcome to the OpenWhisk Debugger
-(wskdb)
-```
+
You will now be in the `wsdk` REPL. Issue `help` to see the list of available commands.
-Note: the first time you launch `wskdb`, you will experience a ~60 second delay, as the debugger finishes up the installation. This includes pulling in the package dependencies supported by OpenWhisk. These dependencies will allow you to debug actions that require one or more of the NodeJS [packages supported by OpenWhisk](https://dev-console.stage1.ng.bluemix.net/docs/openwhisk/openwhisk_reference.html#openwhisk_ref_javascript). If you have already initialized the debugger, you can always choose to reinitialize it via `wskdb --reset`; this will reinstall the dependencies.
+Note: the first time you launch `wskdb`, you will experience a ~60 second delay, as the debugger finishes up the installation. This includes pulling in the package dependencies supported by OpenWhisk. These dependencies will allow you to debug actions that require one or more of the [packages supported by OpenWhisk](https://dev-console.stage1.ng.bluemix.net/docs/openwhisk/openwhisk_reference.html#openwhisk_ref_javascript). If you have already initialized the debugger, you can always choose to reinitialize it via `wskdb --reset`; this will reinstall the dependencies.
## Prerequisites
-If you wish to debug NodeJS actions, you must currently have a version of NodeJS installed on your local machine that is compatible with the actions you wish to debug. Also note that `wskdb` currently does not attempt to employ `nvm` in order to leverage a runtime that matches the action being debugged.
+If you wish to debug NodeJS actions, you must currently have a version of NodeJS installed on your local machine that is compatible with the actions you wish to debug. `wskdb` currently does not attempt to employ `nvm` in order to leverage a runtime that matches the action being debugged.
If you wish to debug Swift actions, you must have `swiftc` and `lldb` installed. On MacOS, for example, you can acquire these by installing [XCode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12).
-If you wish to debug Python actions, you must have installed a version of Python compatible with 2.7.12. The Python modules that OpenWhisk includes will not be installed locally. If you wish to set things up for debugging Python actions that depend on one or more of these modules, issue `wskdb --python` for your initial invocation. You can add Python support at any time by issuing `wskdb --reset --python`. You needn't pass the `--python` flag every time, this is merely a one-time setup issue.
+If you wish to debug Python actions, you must have installed a version of Python compatible with 2.7.12. By default, the Python modules that OpenWhisk includes will not be installed locally. If you wish to set things up for debugging Python actions that depend on one or more of these modules, issue `wskdb --python` for your initial invocation. You can add Python support at any time by issuing `wskdb --reset --python`. You needn't pass the `--python` flag every time you use `wskdb`.
-## Invoking an action
-The syntax here is almost identical to that of the `wsk` CLI.
-```
-(wskdb) invoke actionName -p param1 value1 -p param2 value2
-```
+## Basic Commands: List, Inspect, Invoke
-If you haven't yet attached to the action you are invoking, the invocation will proceed as if you weren't in the debugger, and had issued a blocking invocation from the CLI.
+You can list your actions directly from within the debugger REPL.
+
+]
+
+Note that, in this session, the user had already attached to action `a3`. You may wish to inspect the details of an action, or invoke it prior to attaching. If you haven't yet attached to the action you are invoking, the invocation will proceed as if you weren't in the debugger, and had issued a blocking invocation from the CLI.
+
+
+
## Attaching to an action
You can attach to an attach on startup by passing the action name to the initial invocation. Say for example you wish to attach to an action `foo`:
-```
+```ShellSession
% ./wskdb foo
Attaching to foo
Creating action trampoline
@@ -47,7 +45,7 @@
You may also choose to launch the debugger and attach to `foo` later:
-```
+```ShellSession
(wskdb) attach foo
Attaching to foo
Creating action trampoline
@@ -55,7 +53,7 @@
If you wish to extend the instrumentation to include any containing rules or sequences (in this case, the action occurs in a sequence `seq`):
-```
+```ShellSession
(wskdb) attach foo --all
Attaching to foo
Creating action trampoline
@@ -64,10 +62,20 @@
The short-hand for this is `-a`.
-### Getting Help
+## Modifying Code
+
+If you are debugging a NodeJS action, you can elect to modify your code during a debug session. If you choose to do so, please be aware of the following bug in either the node-inspector or in NodeJS itself: if you modify the code of your action *after* it has been invoked, then hit Cmd/Ctrl-S to save your changes, this code change will not be reflected in that invocation, even though the code change itself will have registered.
+
+Thus, please make any code changes prior to the debugger entering your action. When the debugger first starts up, you will be at a breakpoint *outside* of your action. This is your opportunity for modifying the code. Make your changes, hit Cmd/Ctrl-S to save them, then click Continue. You will now be in the body of your modified action, and those code changes will be reflected in the return value of the action when you Continue it through to completion.
+
+Once you return to the `wskdb` REPL, you can choose to publish the changes back to the OpenWhisk servers:
+
+![The diff and publish commands](docs/commands/diff_and_publish.png")
+
+## Getting Help
To learn more about the options for each command, you can issue a `-h` request, e.g.
-```
+```ShellSession
(wskdb) attach -h
Usage: attach [options]
@@ -82,12 +90,21 @@
By default, `wskdb` will prefer to use a browser-based debugger. If instead you wish to use a command-line debugger, pass the `--use-cli-debugger` option to `wskdb`; the short-hand form of this option is `-c`:
-```
-./wskdb -c
+```ShellSession
+% ./wskdb -c
Welcome to the OpenWhisk Debugger
+ Favor the CLI for debug sessions over a GUI
```
+## Examples
+
+### Python
+
+This screenshot illustrates an example session of attaching, invoking, and debugging, a Python action.
+
+
+
+
## Notes on the Architecture
If you are curious as to the inner workings of the debugger, you can read more [here](docs/architecture/architecture.md). In short, `wskdb` operates by graph rewriting. In a way reminiscent of conventional debuggers, `wskdb` will install a *trampoline* that allows insertion of a breakpoint that re-routes invocations to your local machine.
diff --git a/docs/commands/diff_and_publish.png b/docs/commands/diff_and_publish.png
new file mode 100644
index 0000000..71e0fdc
--- /dev/null
+++ b/docs/commands/diff_and_publish.png
Binary files differ
diff --git a/docs/commands/inspect.png b/docs/commands/inspect.png
new file mode 100644
index 0000000..0a3319c
--- /dev/null
+++ b/docs/commands/inspect.png
Binary files differ
diff --git a/docs/commands/invoke.png b/docs/commands/invoke.png
new file mode 100644
index 0000000..2f55366
--- /dev/null
+++ b/docs/commands/invoke.png
Binary files differ
diff --git a/docs/commands/list.png b/docs/commands/list.png
new file mode 100644
index 0000000..9532be9
--- /dev/null
+++ b/docs/commands/list.png
Binary files differ
diff --git a/docs/python/example.png b/docs/python/example.png
new file mode 100644
index 0000000..360e584
--- /dev/null
+++ b/docs/python/example.png
Binary files differ
diff --git a/docs/startup.png b/docs/startup.png
new file mode 100644
index 0000000..7f0baf4
--- /dev/null
+++ b/docs/startup.png
Binary files differ
