diff --git a/Makefile b/Makefile
index 817a93c..58f9574 100644
--- a/Makefile
+++ b/Makefile
@@ -37,7 +37,7 @@
 
 migration-test: venv-xos
 	source ./venv-xos/bin/activate ; set -u ;\
-	xos-migrate -x xos -s core --check
+	xos-migrate --xos-dir . -s core --check
 
 clean:
 	find . -name '*.pyc' | xargs rm -f
diff --git a/VERSION b/VERSION
index ed1fc35..c36c648 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-2.2.16
+2.2.17
diff --git a/containers/chameleon/Dockerfile.chameleon b/containers/chameleon/Dockerfile.chameleon
index 0794cbc..b18ec5c 100644
--- a/containers/chameleon/Dockerfile.chameleon
+++ b/containers/chameleon/Dockerfile.chameleon
@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # xosproject/chameleon
-FROM xosproject/xos-base:2.2.16
+FROM xosproject/xos-base:2.2.17
 
 # xos-base already has protoc and dependencies installed
 
diff --git a/containers/xos/Dockerfile.client b/containers/xos/Dockerfile.client
index 9170f29..e731bcf 100644
--- a/containers/xos/Dockerfile.client
+++ b/containers/xos/Dockerfile.client
@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # xosproject/xos-client
-FROM xosproject/xos-libraries:2.2.16
+FROM xosproject/xos-libraries:2.2.17
 
 # Install XOS client
 COPY lib/xos-api /tmp/xos-api
diff --git a/containers/xos/Dockerfile.libraries b/containers/xos/Dockerfile.libraries
index efa5bfc..f87792f 100644
--- a/containers/xos/Dockerfile.libraries
+++ b/containers/xos/Dockerfile.libraries
@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # xosproject/xos-libraries
-FROM xosproject/xos-base:2.2.16
+FROM xosproject/xos-base:2.2.17
 
 # Add libraries
 COPY lib /opt/xos/lib
diff --git a/containers/xos/Dockerfile.synchronizer-base b/containers/xos/Dockerfile.synchronizer-base
index d240d75..75a9b9e 100644
--- a/containers/xos/Dockerfile.synchronizer-base
+++ b/containers/xos/Dockerfile.synchronizer-base
@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # xosproject/xos-synchronizer-base
-FROM xosproject/xos-client:2.2.16
+FROM xosproject/xos-client:2.2.17
 
 COPY xos/synchronizers/new_base /opt/xos/synchronizers/new_base
 COPY xos/xos/logger.py /opt/xos/xos/logger.py
diff --git a/containers/xos/Dockerfile.xos-core b/containers/xos/Dockerfile.xos-core
index b3dc525..7a71462 100644
--- a/containers/xos/Dockerfile.xos-core
+++ b/containers/xos/Dockerfile.xos-core
@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # xosproject/xos-core
-FROM xosproject/xos-libraries:2.2.16
+FROM xosproject/xos-libraries:2.2.17
 
 # Install XOS
 ADD xos /opt/xos
diff --git a/docs/Makefile b/docs/Makefile
index 60b3b5f..0cd84bd 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -15,12 +15,12 @@
 LINT_STYLE ?= mdl_relaxed.rb
 
 serve: setup
-	gitbook serve
+	gitbook serve --log=debug --debug
 
 build: setup
 	gitbook build
 
-setup: xos-gui xos-tosca kubernetes openstack onos simpleexampleservice exampleservice
+setup:
 	gitbook init
 	gitbook install
 
@@ -37,29 +37,6 @@
 	@echo "---"
 	mdl -s $(LINT_STYLE) `find -L . ! -path "./_book/*" ! -path "./node_modules/*" -name "*.md"`
 
-# link directories that contain other documentation
-xos-gui:
-	ln -s ../../xos-gui/docs xos-gui
-
-xos-tosca:
-	ln -s ../../xos-tosca/docs xos-tosca
-
-kubernetes:
-	ln -s ../../xos-services/kubernetes-service/docs kubernetes
-
-openstack:
-	ln -s ../../xos-services/openstack/docs openstack
-
-onos:
-	ln -s ../../xos-services/onos-service/docs onos
-
-exampleservice:
-	ln -s ../../xos-services/exampleservice/docs exampleservice
-
-simpleexampleservice:
-	ln -s ../../xos-services/simpleexampleservice/docs simpleexampleservice
-
-
 # HOW TO
 # - load the virtual env (https://guide.opencord.org/xos/dev/local_env.html)
 # - run `make`
@@ -91,4 +68,3 @@
 	rm -rf $(GENERATED_DOCS)
 	rm -rf _book
 	rm -rf node_modules
-	rm -rf xos xos-gui xos-tosca kubernetes openstack onos simpleexampleservice exampleservice
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 84860ec..9580352 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -19,10 +19,10 @@
     * [Tutorial](tutorials/basic_synchronizer.md)
     * [XOS Shell (xossh)](dev/xossh.md)
 * [Platform Services](platform.md)
-    * [Kubernetes](kubernetes/kubernetes-service.md)
-    * [OpenStack](openstack/openstack-service.md)
-    * [ONOS](onos/README.md)
+    * [Kubernetes](./external_content/kubernetes.md)
+    * [OpenStack](./external_content/openstack.md)
+    * [ONOS](./external_content/onos.md)
 * [Example Services](examples.md)
-    * [Simple Example Service](simpleexampleservice/simple-example-service.md)
-    * [Example Service](exampleservice/example-service.md)
+    * [Simple Example Service](./external_content/simpleexampleservice.md)
+    * [Example Service](./external_content/exampleservice.md)
 
diff --git a/docs/dev/xosmigrate.md b/docs/dev/xosmigrate.md
index ac8a189..cce44ef 100644
--- a/docs/dev/xosmigrate.md
+++ b/docs/dev/xosmigrate.md
@@ -25,8 +25,8 @@
 to see the available options:
 
 ```bash
-usage: xos-migrate [-h] -s SERVICE_NAMES [-r REPO_ROOT | -x XOS_ROOT]
-                   [--check] [-v]
+usage: xos-migrate [-h] -s SERVICE_NAMES [-r REPO_ROOT] [-x XOS_ROOT]
+                   [--services-dir SERVICES_ROOT] [--check] [-v]
 
 XOS Migrations
 
@@ -35,9 +35,13 @@
   -r REPO_ROOT, --repo REPO_ROOT
                         Path to the CORD repo root (defaults to '../..').
                         Mutually exclusive with '--xos'.
-  -x XOS_ROOT, --xos XOS_ROOT
+  -x XOS_ROOT, --xos-dir XOS_ROOT
                         Path to directory of the XOS repo. Incompatible with '
-                        --repo' and only works for core migrations.
+                        --repo'.
+  --services-dir SERVICES_ROOT
+                        Path to directory of the XOS services root.
+                        Incompatible with '--repo'.Note that all the services
+                        repo needs to be siblings
   --check               Check if the migrations are generated for a given
                         service. Does not apply any change.
   -v, --verbose         increase log verbosity
@@ -45,7 +49,7 @@
 required arguments:
   -s SERVICE_NAMES, --service SERVICE_NAMES
                         The name of the folder containing the service in
-                        cord/orchestration/xos_services
+                        cord/orchestration/xos-services
 ```
 
 For example, if the code you want to migrate is in `~/Sites` and you
@@ -53,9 +57,15 @@
 following command:
 
 ```bash
-xos-migrate -r ~/Sites -s core -s fabric
+xos-migrate -r ~/Sites/cord -s core -s fabric
 ```
 
+> NOTE:
+> The command above is equivalent to:
+> ```bash
+> xos-migrate --xos-dir ~/Sites/cord/orchestration/xos --services-dir ~/Sites/cord/orchestration/xos-services/ -s core -s fabric
+> ```
+
 If no migrations were present for your service, you will see a new
 folder `migrations` (a sibling of `models`) that contains the file
 `0001-initial.py`. If the service already had migrations you will see
diff --git a/docs/examples.md b/docs/examples.md
index 170be7e..1d23cc7 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -3,5 +3,5 @@
 This section describes two example services that have been on-boarded
 into XOS.
 
-* [Simple Example Service](simpleexampleservice/simple-example-service.md): Runs a web server in a Kubernetes-managed pod.
-* [Example Service](exampleservice/example-service.md): Runs a web server in an OpenStack-managed VM.
+* [Simple Example Service](./external_content/simpleexampleservice.md): Runs a web server in a Kubernetes-managed pod.
+* [Example Service](./external_content/exampleservice.md): Runs a web server in an OpenStack-managed VM.
diff --git a/docs/external_content/exampleservice.md b/docs/external_content/exampleservice.md
new file mode 100644
index 0000000..2bfd2cf
--- /dev/null
+++ b/docs/external_content/exampleservice.md
@@ -0,0 +1 @@
+{% include git+https://github.com/opencord/exampleservice.git/docs/example-service.md" %}
diff --git a/docs/external_content/kubernetes.md b/docs/external_content/kubernetes.md
new file mode 100644
index 0000000..0f332e9
--- /dev/null
+++ b/docs/external_content/kubernetes.md
@@ -0,0 +1 @@
+{% include "git+https://github.com/opencord/kubernetes-service.git/docs/kubernetes-service.md" %}
diff --git a/docs/external_content/onos.md b/docs/external_content/onos.md
new file mode 100644
index 0000000..9d4d282
--- /dev/null
+++ b/docs/external_content/onos.md
@@ -0,0 +1 @@
+{% include "git+https://github.com/opencord/onos-service.git/docs/README.md" %}
diff --git a/docs/external_content/openstack.md b/docs/external_content/openstack.md
new file mode 100644
index 0000000..13d832c
--- /dev/null
+++ b/docs/external_content/openstack.md
@@ -0,0 +1 @@
+{% include "git+https://github.com/opencord/openstack.git/docs/openstack-service.md" %}
diff --git a/docs/external_content/simpleexampleservice.md b/docs/external_content/simpleexampleservice.md
new file mode 100644
index 0000000..86de35d
--- /dev/null
+++ b/docs/external_content/simpleexampleservice.md
@@ -0,0 +1 @@
+{% include "git+https://github.com/opencord/simpleexampleservice.git/docs/simple-example-service.md" %}
diff --git a/docs/mdl_relaxed.rb b/docs/mdl_relaxed.rb
index bebc671..26076a1 100644
--- a/docs/mdl_relaxed.rb
+++ b/docs/mdl_relaxed.rb
@@ -51,3 +51,9 @@
 
 # Gitbook won't care about multiple blank lines
 exclude_rule 'MD012'
+
+# Gitbook does not care about bare URLs
+exclude_rule 'MD034'
+
+# This is not true in case of "includes" placeholder
+exclude_rule 'MD041'
\ No newline at end of file
diff --git a/docs/platform.md b/docs/platform.md
index 7176cb4..109b1b1 100644
--- a/docs/platform.md
+++ b/docs/platform.md
@@ -9,7 +9,7 @@
 than service extensions. This section describes three example platform
 services in more detail:
 
-* [Kubernetes](kubernetes/kubernetes-service.md)
-* [OpenStack](openstack/openstack-service.md)
-* [ONOS](onos/README.md)
+* [Kubernetes](./external_content/kubernetes.md)
+* [OpenStack](./external_content/openstack.md)
+* [ONOS](./external_content/onos.md)
 
diff --git a/lib/xos-migrate/xosmigrate/main.py b/lib/xos-migrate/xosmigrate/main.py
index 562ee38..e7be104 100644
--- a/lib/xos-migrate/xosmigrate/main.py
+++ b/lib/xos-migrate/xosmigrate/main.py
@@ -32,6 +32,8 @@
 from xosconfig import Config
 from multistructlog import create_logger
 
+REPO_ROOT = "~/cord"
+
 
 def get_abs_path(dir_):
     """ Convert a path specified by the user, which might be relative or based on
@@ -293,22 +295,28 @@
     help="The name of the folder containing the service in cord/orchestration/xos-services"
 )
 
-pathgroup = parser.add_mutually_exclusive_group()
-
-pathgroup.add_argument(
+parser.add_argument(
     "-r",
     "--repo",
-    default=get_abs_path("../.."),
+    default=REPO_ROOT,
     dest="repo_root",
     help="Path to the CORD repo root (defaults to '../..'). Mutually exclusive with '--xos'."
 )
 
-pathgroup.add_argument(
+parser.add_argument(
     "-x",
-    "--xos",
+    "--xos-dir",
     default=None,
     dest="xos_root",
-    help="Path to directory of the XOS repo. Incompatible with '--repo' and only works for core migrations."
+    help="Path to directory of the XOS repo. Incompatible with '--repo'."
+)
+
+parser.add_argument(
+    "--services-dir",
+    default=None,
+    dest="services_root",
+    help="Path to directory of the XOS services root. Incompatible with '--repo'." +
+         "Note that all the services repo needs to be siblings"
 )
 
 parser.add_argument(
@@ -329,6 +337,8 @@
 
 
 def run():
+    service_base_dir = None
+
     # cleaning up from possible incorrect states
     if "INSTALLED_APPS" in os.environ:
         del os.environ["INSTALLED_APPS"]
@@ -339,17 +349,35 @@
 
     print_banner(args.repo_root)
 
+    # validating args, the solution is hacky but it does not fit `add_mutually_exclusive_group`
+    # and it's not complex enough for the solution proposed here:
+    # https://stackoverflow.com/questions/17909294/python-argparse-mutual-exclusive-group
+    if args.service_names != ["core"] and \
+            ((args.xos_root and not args.services_root) or (args.services_root and not args.xos_root)):
+        # if we're only generating migrations for the core,
+        # the --xos-dir is the only think we need
+        log.error("You need to set both --xos-dir and \
+                --services-dir parameters when generating migrations for a service")
+        sys.exit(1)
+
+    if (args.xos_root or args.services_root) and (args.repo_root != REPO_ROOT):
+        log.error("The --xos-dir or --services-dir parameters are not compatible with the --repo parameter")
+        sys.exit(1)
+
     # find absolute path to the code
-    if args.xos_root:  # if args.xos_root is set, testing only the core
-        xos_path = get_abs_path(args.xos_root)
-        if args.service_names != ["core"]:
-            log.error("When using --xos, can only check the core models")
-            sys.exit(1)
+    if args.xos_root or args.services_root:
+        xos_path = get_abs_path(os.path.join(args.xos_root, "xos"))
+        if args.services_root:
+            # NOTE this params is optional (we may be generating migrations for the core only
+            service_base_dir = get_abs_path(args.services_root)
     else:
         xos_path = get_abs_path(os.path.join(args.repo_root, "orchestration/xos/xos/"))
-        service_base_dir = get_abs_path(os.path.join(xos_path, "../../xos_services/"))
-        service_dest_dir = get_abs_path(os.path.join(xos_path, "services/"))
+        service_base_dir = get_abs_path(os.path.join(xos_path, "../../xos-services/"))
 
+    log.debug("XOS Path: %s" % xos_path)
+    log.debug("Service Base Dir: %s" % service_base_dir)
+
+    service_dest_dir = get_abs_path(os.path.join(xos_path, "services/"))
     core_dir = get_abs_path(os.path.join(xos_path, "core/models/"))
 
     # we need to append the xos folder to sys.path