diff --git a/web/gui/doc/README.user.md b/web/gui/doc/README.user.md
new file mode 100644
index 0000000..cb7206f
--- /dev/null
+++ b/web/gui/doc/README.user.md
@@ -0,0 +1,231 @@
+ONOS Web UI - User Documentation
+================================
+
+#### Note to Reader
+
+This document provides a brief overview of the _User Documentation_ for 
+the _ONOS Web UI_. For more detailed documentation (including screenshots), 
+please see [The ONOS Web GUI][owg] on the ONOS wiki. 
+ 
+Further content (subsections) may be found in files named `README.user.*.md`
+
+Placeholders for screenshots / images are marked thusly:
+
+![sample image placeholder][pic]
+
+[owg]: https://wiki.onosproject.org/display/ONOS/The+ONOS+Web+GUI
+[pic]: picture-icon.png 
+
+
+
+Introduction
+------------
+
+#### Overview
+
+The ONOS GUI is a _single-page web application_, providing a visual
+interface to the ONOS controller (or cluster of controllers).
+
+For documentation on the design of the GUI, see [Web UI Architecture][ua] in
+the Architecture Guide.
+
+For documentation on how applications running on ONOS can inject content
+into the GUI at runtime, see the [Web UI Tutorials][ut] page.
+
+The [Developer Guide][dg] includes documentation on the Web UI framework 
+libraries (for both _client-side_ and _server-side_ modules), to help app
+developers re-use common coding patterns.
+
+
+[ua]: https://wiki.onosproject.org/display/ONOS/Web+UI+Architecture
+[ut]: https://wiki.onosproject.org/display/ONOS/Web+UI+Tutorials
+[dg]: https://wiki.onosproject.org/display/ONOS/Appendix+F%3A+Web+UI+Framework+Libraries
+
+
+----
+#### Configuration Notes
+
+* The **_onos-gui_** feature must be installed in ONOS
+* The GUI listens on port **_8181_**
+* The base url is `/onos/ui`
+  + for example, to access the GUI on _localhost_, use
+    `http://localhost:8181/onos/ui`   
+* The GUI has been developed to work on _Google Chrome_. 
+  The GUI has been tested on _Safari_ and _Firefox_ and minor compatibility 
+  adjustments have been made; these and other browsers may work, but have 
+  not been extensively tested, and are not actively supported, at this time.
+* The key bindings associated with any view will work on any keyboard. 
+  The "Cmd" (⌘) key on an Apple keyboard is bound to the same key as 
+  the "Windows" or "Alt" keys on Windows or other keyboards.
+
+
+----
+#### Session Notes
+
+Note that the current version of the GUI does not fully support the concept
+of individual user accounts, however, login credentials are required.
+
+On launching the GUI you should see the login screen:
+
+![image of login screen][pic]
+
+Default username and password are `onos/rocks`. 
+
+If ONOS was installed via `onos-install` and configured by `onos-secure-ssh`
+(developer / test tools), then the _username / password_ may be different; 
+examine the `$ONOS_WEB_USER` and `$ONOS_WEB_PASS` environment variables to
+discover what they are.
+
+After a successful login, you should see a screen that looks like this:
+
+![image of topology view][pic]
+
+The dark bar at the top is the _Masthead_, which provides a location for
+general GUI controls:
+
+- Navigation Menu Button
+- ONOS logo and title
+- Context help button (click to open web URL specific to view)
+- User name (click to access `logout` action)
+
+(In future versions, the masthead may include session controls such as 
+user preferences, global search, etc.)
+
+The remainder of the screen is the "view", which defaults to the 
+Topology View when the GUI is first loaded – a cluster-wide view of the 
+network topology.
+
+* The _ONOS Cluster Node Panel_ indicates the cluster members 
+  (controller instances) in the cluster.
+* The _Summary Panel_ gives a brief summary of properties of the 
+  network topology.
+* The _Topology Toolbar_ (initially hidden) provides 
+  push-button / toggle-button actions that interact with the topology view.
+  
+For more detailed information about this view, see the [Topology View][topo] page.
+
+
+----
+#### Navigation
+
+Other views can be "navigated to" by clicking on the _Navigation Menu Button_ 
+in the masthead, then selecting an item from the dropdown menu:
+
+![image of navigation menu][pic]
+
+----
+#### Views
+
+The GUI is cacapable of supporting multiple views. As new views are added 
+to the base release, they will be documented here.
+
+> NOTE:
+> The capability of adding views to the GUI dynamically at run-time is also 
+> available to developers, allowing, for example, an ONOS App developer to 
+> create GUI content that works specifically with their application. 
+> The content will be injected dynamically into the GUI when the app is 
+> installed, and removed automatically from the GUI when the app is 
+> uninstalled. For more details on this feature, see the 
+> [Web UI tutorials][ut].
+
+The views currently included in the base release are:
+
+- Platform Category
+  + Applications
+    + The [Application View][app] provides a listing of installed
+      applications, as well as the ability to _install, start, stop
+      and uninstall_ them.
+  + Settings
+    + The [Settings View][set] provides information about all configurable
+      settings in the system. (Currently this is a readonly view, but 
+      future releases may provide setting adjustments from here).
+  + Cluster Nodes
+    + The [Cluster Node View][cnode] provides a top level listing of all
+      the nodes (ONOS instances) in the cluster.
+  + Packet Processors
+    + The [Packet Processors View][pkt] shows the currently configured
+      components that participate in the processing of packets
+      sent to the controller.
+  + Partitions
+    + The [Partitions View][part] shows the cluster partitions.
+  
+- Network Category
+  + Topology
+    + The [Topology View][topo] provides an interactive visualization of the
+      network topology, including an indication of which devices (switches)
+      are mastered by each ONOS controller instance.
+  + Topology 2 (experimental)
+    + The [Topology 2 View][topo2] is a "region aware" view of the topology
+      which can take advantage of an administrator configuring the network
+      into regions.
+      * Note that this view is _currently experimental_
+  + Devices
+    + The [Devices View][dev] provides a top level listing of the 
+      devices in the network. Note that when a device in the table is
+      selected, additional views (not directly available from the navigation
+      menu) become available for that device:
+      + [Flows][flow]: shows all flows for the selected device
+      + [Ports][port]: shows all ports for the selected device
+      + [Groups][group]: shows all groups for the selected device
+      + [Meters][meter]: shows all meters for the selected device
+  + Links 
+    + The [Links View][link] provides a top level listing of all the
+      links in the network.
+  + Hosts
+    + The [Hosts View][host] provides a top level listing of all the
+      hosts in the network.
+  + Intents
+    + The [Intents View][intent] provides a top level listing of all the
+      intents in the network.
+  + Tunnels
+    + The [Tunnels View][tunnel] provides a top level listing of all
+      tunnels defined in the network.
+    
+[app]: https://wiki.onosproject.org/display/ONOS/GUI+Application+View
+[set]: https://wiki.onosproject.org/display/ONOS/GUI+Settings+View
+[cnode]: https://wiki.onosproject.org/display/ONOS/GUI+Cluster+Node+View
+[pkt]: https://wiki.onosproject.org/display/ONOS/ONOS+Packet+Processors+View
+[part]: https://wiki.onosproject.org/display/ONOS/GUI+Partitions+View
+
+[topo]: https://wiki.onosproject.org/display/ONOS/GUI+Topology+View
+[topo2]: https://wiki.onosproject.org/display/ONOS/GUI+Topology+2+View
+[dev]: https://wiki.onosproject.org/display/ONOS/GUI+Device+View
+[flow]: https://wiki.onosproject.org/display/ONOS/GUI+Flow+View
+[port]: https://wiki.onosproject.org/display/ONOS/GUI+Port+View
+[group]: https://wiki.onosproject.org/display/ONOS/GUI+Group+View
+[meter]: https://wiki.onosproject.org/display/ONOS/GUI+Meter+View
+[link]: https://wiki.onosproject.org/display/ONOS/GUI+Link+View
+[host]: https://wiki.onosproject.org/display/ONOS/GUI+Host+View
+[intent]: https://wiki.onosproject.org/display/ONOS/GUI+Intent+View
+[tunnel]: https://wiki.onosproject.org/display/ONOS/GUI+Tunnel+View
+
+Note that many of the views are table-based, and are similar in look 
+and interaction. For a general overview of tabular usage, see the 
+[Tabular View][table] page.
+
+[table]: https://wiki.onosproject.org/display/ONOS/GUI+Tabular+View
+
+> See `README.user.views.md` for view specific documentation.
+
+[README-user-views]: README.user.views.md
+
+                                                                               
+----
+#### Web UI Applications
+
+ONOS applications may contain Web UI components - either custom views
+or topology overlay behaviors.
+For documentation on application-specific behavior, please see the
+[Web UI Application Index][appidx].
+
+> NOTE: For applications that are distributed with core ONOS, it is expected
+> that the developer provides a wiki page for documentation, and provides a
+> link in the index page.
+
+[appidx]: https://wiki.onosproject.org/display/ONOS/Web+UI+Application+Index
+
+----
+#### Release Nodes
+
+Please see `README.user.releases.md` for a summary of UI features introduced
+at each release of ONOS.
diff --git a/web/gui/doc/README.user.releases.md b/web/gui/doc/README.user.releases.md
new file mode 100644
index 0000000..6e3d005
--- /dev/null
+++ b/web/gui/doc/README.user.releases.md
@@ -0,0 +1,161 @@
+ONOS Web UI - User Documentation
+================================
+
+### Release Notes
+
+This section provides a reverse-chronological summary of changes 
+to the GUI for each release.
+
+----
+#### Kingfisher -- 1.10.0 -- May 2017
++ (to be listed)
+
+----
+#### Junco -- 1.9.0 -- February 2017
++ Region aware topology view _(Topology 2)_
+  + Still WIP
+  + Region transition animation added
+  + Sprite layers added
++ Partitions View added
++ Support for viewing selected intent via topology overlays added
+
+----
+#### Ibis -- 1.8.0 -- November 2016
++ Region aware topology view _(Topology 2)_
+  + Network configurations added for _Regions_ and _TopoLayouts_
++ "Resubmit Intent" action added to _Intents View_
++ Topology View icons updated
++ Cluster View details panel added
++ Local filtering added to _Flow_, _Port_, _Group_, and _Meter_ views.
+
+----
+#### Hummingbird -- 1.7.0 -- August 2016
++ Region aware topology view _(Topology 2)_
+  + Server-side modeling implemented
++ "Brief" mode introduced to _Intent_, _Group_, and _Flow_ views
++ Continued work on re-theming the UI
+
+----
+#### Goldeneye -- 1.6.0 -- May 2016
++ Overhaul of the "Look-n-Feel" (re-skinned)
++ Applications view:
+  + Drag-n-drop of `.oar` files to install and activate, now supported
+  + Auto-prompt user to refresh the UI when components are added / removed
++ Topology view:
+  + "Cluster node ready" checkmark indicator added
+  + Geo-map selection dialog (`G` keystroke) added
+  + Support for topology overlays to provide custom link data
++ Dialog Service:
+  + Support for chained dialog operations added
++ Chart Service added
++ User preferences now persisted server side
++ Logged-in user name displayed in masthead
+
+----
+#### Falcon -- 1.5.0 -- February 2016
++ Topology View:
+  + "Reset node locations" command (`X` keystroke) added
+  + Topology overlay selection with `F1`, `F2`, `F3`, ... keystrokes added
++ Applications View:
+  + Confirmation dialog added for application activate / deactivate /
+    uninstall
+  + Application model enhancements supported:
+    + columns added for additional attributes
+    + details panel displayed when application row selected
+  + Note: applications can now define custom icon and URL (link to docs)
++ Dialog Service:
+  + `Enter` and `Escape` keys bound to _OK_ and _Cancel_ buttons
+
+----
+#### Emu -- 1.4.0 -- November 2015
++ Device View:
+  + Friendly name can be set on a device from the device detail panel
++ Intent View:
+  + Button added to navigate to _Topology View_ and display the
+    selected intent
++ Topology View:
+  + _Traffic Overlay_ now selected by default
+  + Topology overlays can now highlight devices and hosts with badges
+    (small number / text / glyph)
+  + Topology overlays can invoke a dialog box to interact with the user
++ ONOS-Branded "Loading..." animation added
++ Sample application (org.onosproject.uiref) featuring UI content
+  injection techniques added
++ GUI Archetypes (ui, uitab, uitopo) facilitating rapid development of 
+  applications with custom UI content
+  
+----
+#### Drake -- 1.3.0 -- August 2015
++ Authentication enabled by default (login screen; logout action)
++ _Settings_ and _Tunnels_ views added
++ Topology View:
+  + Traffic re-implemented as an "overlay"
+  + Overlay mechanism now programmable from ONOS apps
+    + highlighting / labeling topology links
+    + full control over summary panel content
+    + full control over details panel content
+    
+----
+#### Cardinal -- 1.2.0 -- May 2015
++ Websocket mechanism promoted to be framework-wide; a shared resource 
+  amongst the views
++ More tabular views added:
+  + Links
+  + Hosts
+  + Intents
+  + Applications
+  + Cluster Nodes
+  + Device Flows (hidden view)
+  + Device Ports (hidden view)
+  + Device Groups (hidden view) 
++ Changes to the Topology View:
+  + links are now selectable.
+  + toolbar added (note, keystroke commands still available)
+    + node layer buttons moved from masthead to toolbar
+  + sprite layer added
+  + user selection choices persisted across sessions
+  + summary and detail panels adjust size to window height
++ Changes to the Device View:
+  + slide out details panel appears when a device is clicked on
++ Navigation Menu changes:
+  + glyphs next to links for navigation
+  + views organized into categories
++ Note that the legacy (Avocet) GUI has been deprecated, and that 
+  the (Angular-based) GUI loads by default.
+
+----
+#### Blackbird -- 1.1.0 -- February 2015
++ GUI Framework migrated to use AngularJS
+  + View-agnostic features refactored as Angular Services
++ Topology View refactored to be an Angular module
+  + Topology source code broken out into multiple source files
+  + Port Highlighting on links added
++ Device View added
+  + Implemented as a simple table for now; one device per row, 
+    sortable by column header clicks
++ Sample View added
+  + Skeletal example code
++ Light and Dark themes fully implemented
+  + Press the 'T' key to toggle theme
++ Beginnings of UIExtension mechanism implemented
+  + Over future releases, this will facilitate the ability of 
+    Apps to inject their own content into the GUI
+
+> Note that the new (Angular-based) GUI currently co-exists with the 
+>   old (Avocet) GUI.
+> + By default, the Avocet GUI is launched; 
+>   the base URL `http://localhost:8181/onos/ui` is mapped to 
+>   `http://localhost:8181/onos/ui/legacy/index.html#topo`
+> + The new Angular-based GUI can be launched by manually adjusting 
+>   the URL to be:  `http://localhost:8181/onos/ui/index.html#topo`, 
+>   (that is, remove "legacy/"). 
+
+----
+#### Avocet -- 1.0.0 -- November 2014
++ GUI implemented using a home-grown framework 
++ Single view (_Topology View_) implemented, displaying network topology and
+  providing a certain level of interaction to show traffic & flow information
++ Although the `T` key-binding (toggle theme) is present, the "dark" theme 
+  has not been implemented
+  
+----
diff --git a/web/gui/doc/README.user.views.md b/web/gui/doc/README.user.views.md
new file mode 100644
index 0000000..ea09bab
--- /dev/null
+++ b/web/gui/doc/README.user.views.md
@@ -0,0 +1,148 @@
+ONOS Web UI - Views
+===================
+
+Documentation for the Web UI main views.
+
+> Note that each of these views should have their own wiki page.
+> For convenience, we are documenting them all here in a single document.
+
+[table]: https://wiki.onosproject.org/display/ONOS/GUI+Tabular+View
+[pic]: picture-icon.png 
+
+# Platform Category Views
+
+
+Application View
+----------------
+
+### Overview
+The application view provides a top level listing of, and basic interaction
+with, all installed applications. The applications are displayed in
+[tabular form][table], where each row is a single application.
+
+![screenshot of app view][pic]
+
+Selecting a row will display a detail panel, containing more information 
+about the selected application. Control buttons will also become available, 
+based on the current state of the application.
+
+(to be completed)
+
+
+----
+
+Settings View
+-------------
+
+### Overview
+The settings view ... (to be completed)
+
+
+----
+
+Cluster Node  View
+------------------
+
+### Overview
+The cluster node view ... (to be completed)
+
+
+----
+
+Packet Processors View
+----------------------
+
+### Overview
+The packet processors view ... (to be completed)
+
+----
+
+# Network Category Views
+
+Topology View
+-------------
+
+### Overview
+The topology view ... (to be completed)
+
+----
+
+Topology 2 View
+---------------
+
+### Overview
+The topology 2 view ... (to be completed)
+
+----
+
+Devices View
+------------
+
+### Overview
+The devices view ... (to be completed)
+
+----
+
+Flows View
+----------
+
+### Overview
+The flows view ... (to be completed)
+
+----
+
+Ports View
+----------
+
+### Overview
+The ports view ... (to be completed)
+
+----
+
+Groups View
+-----------
+
+### Overview
+The groups view ... (to be completed)
+
+----
+
+Meters View
+-----------
+
+### Overview
+The meters view ... (to be completed)
+
+----
+
+Links View
+----------
+
+### Overview
+The links view ... (to be completed)
+
+----
+
+Hosts View
+----------
+
+### Overview
+The hosts view ... (to be completed)
+
+----
+
+Intents View
+------------
+
+### Overview
+The intents view ... (to be completed)
+
+----
+
+Tunnels View
+------------
+
+### Overview
+The tunnels view ... (to be completed)
+
+----
\ No newline at end of file
diff --git a/web/gui/doc/picture-icon.png b/web/gui/doc/picture-icon.png
new file mode 100644
index 0000000..3b21d65
--- /dev/null
+++ b/web/gui/doc/picture-icon.png
Binary files differ