diff --git a/.gitignore b/.gitignore
index 27384fe..0b1f37c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@
 npm-debug.log
 node_modules
 _book
+repos
 xos/_book
 venv-xosdocs
 .DS_Store
diff --git a/Makefile b/Makefile
index f1d1b93..a084f5f 100644
--- a/Makefile
+++ b/Makefile
@@ -1,93 +1,89 @@
 # Makefile for building CORD docs site, guide.opencord.org
 # Building docs requires the following tools:
 #  - Gitbook toolchain: https://toolchain.gitbook.com/setup.html
+#  - git
 #  - NPM (for Gitbook and Swagger)
-#  - Python (for build glossary script)
 #  - linkchecker (for test target) http://wummel.github.io/linkchecker/
+#  - markdownlint (for lint target) https://github.com/markdownlint/markdownlint
 
 default: serve
 
-# use bash for pushd/popd, and to fail if commands within  a pipe fail
-SHELL = bash -o pipefail
+# use bash for pushd/popd, and to fail quickly
+SHELL = bash -eu -o pipefail
 
-GENERATED_DOCS =
+# Other repos with documentation that's included in the gitbook
+# edit the `git_refs` file with the commit/tag/branch that you want to use
+OTHER_REPO_DOCS ?= cord-tester fabric hippie-oss kubernetes-service olt-service onos-service openolt openstack rcord simpleexampleservice exampleservice vrouter xos xos-gui xos-tosca
+GENERATED_DOCS  ?= # should be 'swagger', but currently broken
+ALL_DOCS        ?= $(OTHER_REPO_DOCS) $(GENERATED_DOCS)
 
-LINT_STYLE ?= mdl_relaxed.rb
-
-serve: setup
+# build targets
+serve: | $(ALL_DOCS) gitbook-setup
 	npm start
 
-build: setup
+build: _book
+
+_book: | $(ALL_DOCS) gitbook-setup
 	gitbook build
 
-setup: automation-tools cord-tester simpleexampleservice openstack fabric hippie-oss kubernetes-service olt-service onos-service openolt rcord vrouter xos xos-gui xos-tosca swagger $(GENERATED_DOCS)
+gitbook-setup:
 	gitbook init
 	gitbook install
 
-test: linkcheck lint
+clean:
+	rm -rf _book
+	rm -rf node_modules
+	rm -rf repos/*
+	rm -rf $(ALL_DOCS)
 
-linkcheck: build
-	linkchecker -a _book/
+# testing targets
+test: lint linkcheck
+LINT_STYLE ?= mdl_relaxed.rb
 
-lint:
+lint: | $(OTHER_REPO_DOCS)
 	@echo "markdownlint(mdl) version: `mdl --version`"
 	@echo "style config:"
 	@echo "---"
 	@cat $(LINT_STYLE)
 	@echo "---"
-	mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
+	mdl -s $(LINT_STYLE) `find -L . ! -path "./partials/*" ! -path "./_book/*" ! -path "./repos/*"  ! -path "./node_modules/*" ! -path "./cord-tester/modules/*" -name "*.md"`
 
-# link directories that contain other documentation
-automation-tools:
-	ln -s ../automation-tools automation-tools
+linkcheck: $(ALL_DOCS) _book
+	linkchecker -a _book/
 
-cord-tester:
-	ln -s ../test/cord-tester/docs cord-tester
+# Host holding the git server
+REPO_HOST   ?= https://gerrit.opencord.org
 
-fabric:
-	ln -s ../orchestration/xos_services/fabric/docs fabric
+# checkout the repos inside repos/ dir
+repos:
+	mkdir repos
 
-hippie-oss:
-	ln -s ../orchestration/xos_services/hippie-oss/docs hippie-oss
+# build directory paths in repos/* to perform 'git clone <repo>' into
+CHECKOUT_REPOS=$(foreach repo,$(OTHER_REPO_DOCS),repos/$(repo))
 
-olt-service:
-	ln -s ../orchestration/xos_services/olt-service/docs olt-service
+# For QA patchset validation - set SKIP_CHECKOUT to the repo name and
+# pre-populate it under epos with the specific commit to being validated
+SKIP_CHECKOUT ?=
 
-onos-service:
-	ln -s ../orchestration/xos_services/onos-service/docs onos-service
+# clone (only if doesn't exist), then checkout ref in repos/*
+$(CHECKOUT_REPOS):  git_refs | repos
+	GIT_REF=`grep '^$(@F) ' git_refs | awk '{print $$3}'` ;\
+	if [ ! -d '$@' ] ;\
+	  then git clone $(REPO_HOST)/$(@F) $@ ;\
+	fi ;\
+	if [ "$(SKIP_CHECKOUT)" = "$(@F)" ] ;\
+	  then echo "Skipping checkout of repo $(SKIP_CHECKOUT) as it's being tested" ;\
+	else pushd $@ ;\
+	  git checkout $$GIT_REF ;\
+	  popd ;\
+	fi
 
-kubernetes-service:
-	ln -s ../orchestration/xos_services/kubernetes-service/docs kubernetes-service
+# link subdirectories (if applicable) into main docs dir
+$(OTHER_REPO_DOCS): | $(CHECKOUT_REPOS)
+	GIT_SUBDIR=`grep '^$@ ' git_refs | awk '{print $$2}'` ;\
+	ln -s repos/$(@)$$GIT_SUBDIR $@
 
-openolt:
-	ln -s ../incubator/openolt openolt
-
-rcord:
-	ln -s ../orchestration/profiles/rcord/docs rcord
-
-vrouter:
-	ln -s ../orchestration/xos_services/vrouter/docs vrouter
-
-openstack:
-	ln -s ../orchestration/xos_services/openstack/docs openstack
-
-simpleexampleservice:
-	ln -s ../orchestration/xos_services/simpleexampleservice/docs simpleexampleservice
-
-xos:
-	ln -s ../orchestration/xos/docs xos
-
-xos-gui:
-	ln -s ../orchestration/xos-gui/docs xos-gui
-
-xos-tosca:
-	ln -s ../orchestration/xos-tosca/docs xos-tosca
-
+# swagger docs generation
 swagger: xos
-	pushd ../orchestration/xos/docs/; make swagger_docs; popd;
+	pushd repos/xos/docs; make swagger_docs; popd;
 
-clean:
-	rm -rf $(GENERATED_DOCS)
-	rm -rf _book
-	rm -rf node_modules
-	rm -rf openstack automation-tools cord-tester fabric hippie-oss kubernetes-service olt-service onos-service openolt rcord vrouter test xos xos-gui xos-tosca simpleexampleservice
diff --git a/SUMMARY.md b/SUMMARY.md
index 70dc248..5da0124 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -64,17 +64,17 @@
             * [Synchronizer Reference](xos/dev/sync_reference.md)
         * [Core Models](xos/core_models.md)
         * [Security Policies](xos/security_policies.md)
+        * [Tutorial](xos/tutorials/basic_synchronizer.md)
     * [Developer Workflows](developer/workflows.md)
         * [Working on R-CORD Without an OLT/ONU](developer/configuration_rcord.md)
     * [Building Docker Images](developer/imagebuilder.md)
-    * Tutorials
-        * [Synchronizer Hello World](developer/tutorials/basic-synchronizer/intro.md)
     * [Platform Services](developer/platform.md)
         * [Kubernetes](kubernetes-service/kubernetes-service.md)
         * [OpenStack](openstack/openstack-service.md)
         * [VTN and Service Composition](xos/xos_vtn.md)
     * [Example Services](examples/examples.md)
         * [SimpleExampleService](simpleexampleservice/simple-example-service.md)
+        * [ExampleService](exampleservice/example-service.md)
     * [GUI Development](xos-gui/developer/README.md)
         * [Quickstart](xos-gui/developer/quickstart.md)
         * [GUI Extensions](xos-gui/developer/gui_extensions.md)
diff --git a/examples/examples.md b/examples/examples.md
new file mode 100644
index 0000000..4f484f2
--- /dev/null
+++ b/examples/examples.md
@@ -0,0 +1,8 @@
+# Example Services
+
+There are two examples of services, which show how to create models and
+synchronizers:
+
+- ExampleService, which sets up a VM in Openstack
+- SimpleExampleService, which sets up a container in Kubernetes
+
diff --git a/git_refs b/git_refs
new file mode 100644
index 0000000..7faa57f
--- /dev/null
+++ b/git_refs
@@ -0,0 +1,29 @@
+# git_refs
+#
+# This file contains a list of repos, paths within those repos, and git
+# references (branch/tag/commit hash) that are checked out with `git checkout
+# <ref>` during creation of documentation.
+#
+# - First column is the git repo name
+# - Second column is the subdirectory of the repo to symlink into the
+#   docs directory
+# - Third column is the reference (branch/tag/commit) to checkout
+
+_REPO NAME_           _DIR_    _REF_
+
+cord-tester           /docs    master
+fabric                /docs    master
+hippie-oss            /docs    master
+kubernetes-service    /docs    master
+olt-service           /docs    master
+onos-service          /docs    master
+openolt               /        master
+openstack             /docs    master
+rcord                 /docs    master
+simpleexampleservice  /docs    master
+exampleservice        /docs    master
+vrouter               /docs    master
+xos-gui               /docs    master
+xos-tosca             /docs    master
+xos                   /docs    master
+
diff --git a/operating_cord/rest_apis.md b/operating_cord/rest_apis.md
index 7b29be0..5f3f476 100644
--- a/operating_cord/rest_apis.md
+++ b/operating_cord/rest_apis.md
@@ -1,18 +1,11 @@
 # RESTful APIs
 
 A RESTful interface is available for configuring and controlling CORD. It is
-auto-generated from the set of [models](/xos/README.md) configured
-into the POD manifest, and includes both core and service-specific models.
+auto-generated from the set of [models](/xos/intro.md) configured
+into a POD, and includes both core and service-specific models. Click
+[here](https://guide.opencord.org/master/api/xos/) to see API defined
+for the full set of services checked into [Gerrit](https://gerrit.opencord.org).
 
-* [Core](https://guide.opencord.org/{{ book.branch }}/api/xos/#/core)
-* [Address Manager](https://guide.opencord.org/{{ book.branch }}/api/xos/#/addressmanager)
-* [vTR](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vtr)
-* [vSG](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vsg)
-* [vNoD Local](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vnodlocal)
-* [vRouter](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vrouter)
-* [ONOS Service](https://guide.opencord.org/{{ book.branch }}/api/xos/#/onos)
-* [Fabric Service](https://guide.opencord.org/{{ book.branch }}/api/xos/#/fabric)
-* [Example Service](https://guide.opencord.org/{{ book.branch }}/api/xos/#/exampleservice)
-* [vEE](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vee)
-* [vEG](https://guide.opencord.org/{{ book.branch }}/api/xos/#/veg)
-* [vnaas](https://guide.opencord.org/{{ book.branch }}/api/xos/#/vnaas)
+You can access the REST API specification on a running POD by going to
+the `/apidocs/` URL on the Chameleon REST endpoint (exposed at
+port 30006 by default): <http://pod-ip-or-dns-address:30006/apidocs/>.
diff --git a/prereqs/docker-registry.md b/prereqs/docker-registry.md
index a94587e..cce78ee 100644
--- a/prereqs/docker-registry.md
+++ b/prereqs/docker-registry.md
@@ -27,7 +27,7 @@
 The registry can be queried at any time, for example:
 
 ```shell
-curl -X GET https://KUBERNETES_IP:30500/v2/_catalog
+curl -X GET http://KUBERNETES_IP:30500/v2/_catalog
 ```
 
 {% include "/partials/push-images-to-registry.md" %}
diff --git a/prereqs/hardware.md b/prereqs/hardware.md
index 20eb576..820ff9a 100644
--- a/prereqs/hardware.md
+++ b/prereqs/hardware.md
@@ -72,14 +72,22 @@
         copper cable, 3m length - S/N: QSFP-40G-03C
 
 * **R-CORD Access Devices and Optics**
+    * **GPON**
+        * **OLT**: Celestica CLS Ruby S1010 (experimental, only top-down provisioning is supported - through manual customizations)
+            * Compatible **OLT optics**
+                * OptoWiz LSP4343-CKSA-R GPON SFP OLT Transceiver
+        * **ONUs**:
+            * Celestica Tellion GP-1204
+            * Movistar ONU (with CPE included) (manifactured by Telefonica: <http://www.movistar.es/particulares/movil/moviles/hgu>)
     * **XGS-PON**
         * **OLT**: EdgeCore ASFVOLT16 (for more info <bartek_raszczyk@edge-core.com>)
-        * Compatible **OLT optics**
-            * Hisense/Ligent: LTH7226-PC, LTH7226-PC+
-            ** Source Photonics: XPP-XG2-N1-CDFA
-        * **ONU**: AlphaNetworks PON-34000B (for more info <ed-y_chen@alphanetworks.com>)
-        * Compatible **ONU optics**
-            * Hisense/Ligent: LTF7225-BC, LTF7225-BH+
+            * Compatible **OLT optics**
+                * Hisense/Ligent: LTH7226-PC, LTH7226-PC+
+                * Source Photonics: XPP-XG2-N1-CDFA
+        * **ONUs**:
+            * AlphaNetworks PON-34000B (for more info <ed-y_chen@alphanetworks.com>)
+                * Compatible **ONU optics**
+                    * Hisense/Ligent: LTF7225-BC, LTF7225-BH+
 
 * **M-CORD Specific Requirements**
     * **Servers**: Some components of CORD require at least a Intel XEON CPU with Haswell microarchitecture or better.
diff --git a/prereqs/openstack-helm.md b/prereqs/openstack-helm.md
index d60f9a8..7627a45 100644
--- a/prereqs/openstack-helm.md
+++ b/prereqs/openstack-helm.md
@@ -61,6 +61,15 @@
 ```
 
 ```bash
+cat <<EOF > /tmp/libvirt-cord.yaml
+---
+network:
+  backend: []
+EOF
+export OSH_EXTRA_HELM_ARGS_LIBVIRT="-f /tmp/libvirt-cord.yaml"
+```
+
+```bash
 cat <<EOF > /tmp/nova-cord.yaml
 ---
 labels:
diff --git a/profiles/mcord/enodeb-setup.md b/profiles/mcord/enodeb-setup.md
index 7e2eaa6..a1a7665 100644
--- a/profiles/mcord/enodeb-setup.md
+++ b/profiles/mcord/enodeb-setup.md
@@ -1,2 +1,153 @@
-# eNodeB Setup
+# eNodeB and HSS Database Setup
+
+## Supported eNodeBs
+
+M-CORD's virtual EPC should work with any standard eNodeB. We tested the
+Cavium eNodeB (model CNF7100-REF2-RF17). In this section we describe how
+to configure this eNodeB to work with M-CORD.
+
+## Connect the eNodeB to the pod
+
+For physical connectivity, this eNodeB has a single Ethernet interface. Our
+test setup uses a single physical compute node for hosting the VNFs.  We
+connect the eNodeB to one of the NICs on the compute node.
+
+There are two logical connectivities for a eNodeB: (1) S1MME interface
+connection, between eNodeB and MME for attaching process. (2) S1U interface
+connection, between eNodeB and SPGWU (SGWU+PGWU) for user traffic.  To enable
+this connectivity, on the compute node we add the NIC connected to the eNodeB
+to the `fabric` bridge.
+
+## eNodeB configuration
+
+The configuration file on Cavium eNodeB is located at /mnt/app/startup.cfg.
+Find the following lines and change the values:
+
+```bash
+configure net net u32enbipaddress 119.0.0.10
+configure net net u32enbsubnetmask 255.255.255.0
+configure net net u32enbgwipaddress 119.0.0.254
+...
+configure net mme u32mmeipaddress 0 118.0.0.5
+configure net mme u16mmesctpportnumber 0 36412
+...
+configure net sgw u32sgwipaddress 0 119.0.0.2
+```
+
+`u32enbipaddress` is the eNodeB data plane IP address for S1U interface. The
+default IP address in M-CORD is 119.0.0.10/24. You will need to specify it
+when you create the EPC in XOS; see below.
+
+Since `u32enbipaddress` and SPGWU IP on S1U address are on the
+same flat network inside OVS, `u32enbgwipaddress` (gateway IP) does not matter.
+You can give any IP as long as it is not used by eNodeB or SPGWU.
+
+`u32mmeipaddress`: MME IP address on S1MME interface.
+
+`36412`: the default communication port number.
+
+`u32sgwipaddress`: SPGWU IP address on S1U interface.
+
+Where to get those IP addresses? As described at the end of the [M-CORD quick start
+page](https://guide.opencord.org/profiles/mcord/install.html), the command
+`openstack server list --all-projects` will list the VNFs and their IP
+addresses. For example, the
+`flat_network_s1mme` of MME VM is the `u32mmeipaddress`. The `flat_network_s1u`
+is the `u32sgwipaddress`.
+
+Besides this, you should also config the S1U IP and S1MME interface IP address
+on eNodeB by the following command lines. The default value of S1MME we use is
+118.0.0.10/24, while the default value of S1U is 119.0.0.10/24.
+
+```bash
+sudo ifconfig eth0 119.0.0.10/24
+sudo ip addr add 118.0.0.10/24 dev eth0
+```
+
+## Configure the VNFs on the pod for the eNodeB
+
+Specify the eNodeB IP addresses when creating the EPC in the XOS UI.
+To create one, click on `Add` on the `Virtual Evolved Packet Core ServiceInstances` page.  You will see:
+
+```bash
+Enodeb ip addr s1mme
+118.0.0.10
+external eNodeB IP address of S1-MME
+119.0.0.10
+```
+
+118.0.0.10 is the default S1MME interface IP on the eNodeB.
+
+119.0.0.10 is the default S1U interface IP on the eNodeB.
+
+Make sure that the IP addresses here are the same as the IP addresses you
+configed on your eNodeB.
+
+## Add subscriber infomation to the HSS database
+
+Prepare the three values of a SIM card: IMSI, key, and opc.
+For apn value, we will use the default value "apn1".
+Login to the HSS-DB VM, with user name "c3po" and password "c3po", and run:
+
+```bash
+~/c3po/db_docs/data_provisioning_users.sh <imsi> 1122334456 apn1 <key> 1 <ip>
+```
+
+Then login to the database:
+
+```bash
+cqlsh <ip>
+```
+
+Set the opc value:
+
+```bash
+cqlsh> use vhss;
+cqlsh:vhss> update users_imsi set opc='<opc>' where imsi='<imsi>';
+```
+
+## Connect a phone to the eNodeB
+
+You can use any phone, as long as it supports the same band as your eNodeB.
+Search the mobile networks.  You should see your eNodeB relative name
+as one of the choices.
+
+## Setup verification
+
+Download a ping applicaiton on your phone.  You can ping the SGI interface IP
+address of SPGWU from the phone.
+
+Another way to test is to use our InternetEmulator VM. The username and
+password are also "c3po" and "c3po". You need to modify a route on this machine:
+
+```bash
+sudo route add -net 16.0.0.0/8 gw <SPGWU-SGI-IP> dev ens3
+```
+
+16.0.0.0/8 is the default subnet assigned for the phones, you can ignore it.
+SPGWU-SGI-IP is the SGI interface IP address on SPGWU. You can find this IP
+through the same method as with the `u32mmeipaddress` above.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
diff --git a/profiles/mcord/install.md b/profiles/mcord/install.md
index 4df44df..d97a874 100644
--- a/profiles/mcord/install.md
+++ b/profiles/mcord/install.md
@@ -146,7 +146,7 @@
 | ID                                   | Name            | Status | Networks                                                                                           | Image            | Flavor    |
 +--------------------------------------+-----------------+--------+----------------------------------------------------------------------------------------------------+------------------+-----------+
 | 7e197142-afb1-459d-b421-cad91306d19f | mysite_vmme-2   | ACTIVE | s6a_network=120.0.0.9; flat_network_s1mme=118.0.0.5; management=172.27.0.15; s11_network=112.0.0.2 | image_mme_v0.1   | m1.large  |
-| 9fe385f5-a064-40e0-94d3-17ea87b955fc | mysite_vspgwu-1 | ACTIVE | management=172.27.0.5; sgi_network=115.0.0.3; spgw_network=117.0.0.3; flat_network_s1u=119.0.0.10  | image_spgwu_v0.1 | m1.xlarge |
+| 9fe385f5-a064-40e0-94d3-17ea87b955fc | mysite_vspgwu-1 | ACTIVE | management=172.27.0.5; sgi_network=115.0.0.3; spgw_network=117.0.0.3; flat_network_s1u=119.0.0.2   | image_spgwu_v0.1 | m1.xlarge |
 | aa6805fe-3d72-4f1e-a2eb-5546d7916073 | mysite_hssdb-5  | ACTIVE | management=172.27.0.13; db_network=121.0.0.12                                                      | image_hssdb_v0.1 | m1.large  |
 | e53138ed-2893-4073-9c9a-6eb4aa1892f1 | mysite_vhss-4   | ACTIVE | s6a_network=120.0.0.2; management=172.27.0.4; db_network=121.0.0.5                                 | image_hss_v0.1   | m1.large  |
 | 4a5960b5-b5e4-4777-8fe4-f257c244f198 | mysite_vspgwc-3 | ACTIVE | management=172.27.0.7; spgw_network=117.0.0.8; s11_network=112.0.0.4                               | image_spgwc_v0.1 | m1.large  |