diff --git a/docs/README.md b/docs/README.md
index 76ca47c..33d173e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,7 @@
-# XOS
+# Models for CORD
 
-Welcome to the XOS documentation.
+CORD adopts a model-based architecture, where XOS implements its
+modeling support. This guide describes the how models are expressed in
+XOS, and documents the XOS toolchain used to auto-generate various
+elements of CORD from these models.
 
diff --git a/docs/core_models.md b/docs/core_models.md
new file mode 100644
index 0000000..b2aa20c
--- /dev/null
+++ b/docs/core_models.md
@@ -0,0 +1,133 @@
+#Core Models
+
+CORD adopts a model-based design. Each service configured into a
+given CORD deployment has a service-specific model, but CORD
+also defines a set of core models. Service-specific models are
+anchored in these core models.
+
+CORD's core models are defined by a set of [xproto](dev/xproto.md)
+specifications. They are defined in their full detail in the source
+code. See:
+[core.xproto](https://github.com/opencord/xos/blob/master/xos/core/models/core.xproto).
+The following describes these core models -- along with the
+relationships (bindings) among them -- in words.
+
+* **Service:** Represents an elastically scalable, multi-tenant
+program, including the means to instantiate, control, and scale
+functionality.
+
+   - Bound to a set of Slices that contains the collection of
+      virtualized resources (e.g., compute, network) in which the Service runs.
+
+   - Bound to a set of Controllers that represents the service's control 
+      interface.
+
+* **ServiceDependency:** Represents a dependency between a *Subscriber*
+Service on a *Provider*  Service. The set of ServiceDependency 
+and Service models defined in CORD collectively represent the edges
+and verticies of a *Service Graph*. (There is no explicit **ServiceGraph** model.)
+The dependency between a pair of services is parameterized by the method
+by which they are interconnected in the data plane. Connect methods include:
+
+   - **None:** The two services are not connected in the data plane.
+   - **Private:** The two services are connected by a common private network.
+   - **Public:** The two services are connected by a publicly routable network.
+
+* **Slice:** A distributed resource container that includes the compute and 
+network resources that belong to (are used by) some Service.
+
+   - Bound to a (possibly empty) set of Instances that provide compute
+      resources for the Slice. 
+
+   - Bound to a set of Networks that connect the Slice's Instances to
+      each other, and connect this Slice to the Slices of other Services.
+  
+   - Bound to a Flavor that defines how the Slice's Instances are 
+      scheduled. 
+
+   - Bound to an Image that boots in each of the Slice's Instances. 
+
+* **Instance:** Represents a single compute instance associated
+   with a Slice and instantiated on some physical Node. Each Instance
+   is of some isolation type:
+
+   - **VM:** The instance is implemented as a KVM virtual machine.
+   - **Container:** The instance is implemented as a Docker container.
+   - **Container-in-VM:** The instance is implemented as a Docker
+      container running inside a KVM virtual machine.
+
+* **Network:** A virtual network associated with a Slice. Networks are
+of one of the following types:
+
+   - **PRIVATE:** Virtual network for the instances in the same service
+   - **PUBLIC:** Externally accessible network
+   - **MANAGEMENT_LOCAL:** Instance management network which does not span
+      compute nodes, only accessible from the host machine
+   - **MANAGEMENT_HOST:** Real management network which spans compute and
+ 	  head nodes
+   - **ACCESS_AGENT:** Network for access agent infrastructure service
+
+* **Image:** A bootable image that runs in a virtual machine. Each 
+  Image implies a virtualization layer (e.g., Docker, KVM), so the latter 
+  need not be a distinct object. 
+
+* **Flavor:** Represents a bundle of resources (e.g., disk, memory,
+   and cores) allocated to an instance. Current flavors borrow from EC2. 
+
+* **Controller:** Represents the binding of an object
+  in the data model to a back-end element (e.g., an OpenStack head
+  node).  Includes the credentials required to invoke the backend
+  resource.
+
+* **Node:** A physical server that can be virtualized and host Instances.
+
+   - Bound to the Site where the Node is physically located.
+
+   - Bound to a Deployment that defines the policies applied to the 
+     Node. 
+
+##Principals and Access Control
+
+* **User:** Represents an authenticated principal that is granted a set of
+  privileges to invoke operations on a set of models, objects, and
+  fields in the data model.
+
+* **Privilege:** Represents the right to perform a set of read, write,
+  or grant operations on a set of models, objects, and fields.
+
+##Sites and Deployments
+
+The typical use case involves one configuration of a CORD POD
+deployed at a single location. However, the underlying core includes
+two models for multi-site/multi-configuration deployments:
+
+* **Site:** A logical grouping of Nodes that are co-located at the
+  same geographic location, which also typically corresponds to the
+  Nodes' location in the physical network.
+
+  - Bound to a set of Users that are affiliated with the Site.
+
+  - Bound to a set of Nodes located at the Site.
+
+  - Bound to a set of Deployments that the Site may access.
+
+* **Deployment:** A logical grouping of Nodes running a compatible set
+  of virtualization technologies and being managed according to a
+  coherent set of resource allocation policies.
+
+  - Bound to a set of Users that establish the Deployment's policies.
+
+  - Bound to a set of Nodes that adhere to the Deployment's policies.
+
+  - Bound to a set of supported Images that can be booted on the
+    Deployment's nodes.
+
+  - Bound to a set of Controllers that represent the back-end
+    infrastructure service that provides cloud resources (e.g., an
+    OpenStack head node).
+
+Sites and Deployments are often one-to-one, which corresponds
+to a each Site establishing its own policies, but in general,
+Deployments may span multiple Sites. It is also possible that a single
+Site hosts Nodes that belong to more than one Deployment. 
+
diff --git a/docs/example_service.md b/docs/example_service.md
new file mode 100644
index 0000000..efb5336
--- /dev/null
+++ b/docs/example_service.md
@@ -0,0 +1,3 @@
+# Example Service
+
+A placeholder for the Example Service Tutorial (from the wiki).
diff --git a/docs/modeling_conventions.md b/docs/modeling_conventions.md
new file mode 100644
index 0000000..3011b90
--- /dev/null
+++ b/docs/modeling_conventions.md
@@ -0,0 +1,3 @@
+#Modeling Conventions
+
+A placeholder for the modeling conventions document (from the wiki)
diff --git a/docs/modules/xosconfig.md b/docs/modules/xosconfig.md
index 5cf2d9d..fcfebc4 100644
--- a/docs/modules/xosconfig.md
+++ b/docs/modules/xosconfig.md
@@ -1,65 +1,88 @@
-# Xos Config
+# Configuring XOS
 
-This module is responsible to read, validate and distribute the configuration for all
-the XOS based components.
+The `xosconfig` module is used to read, validate and distribute
+configuration information for all XOS-related components.
 
 _The code for this module can be found in lib/xos-config_
 
-The `xosconfig` module use a combination of parameters provided via a `.yaml` file and a service discovery mechanism.
+The `xosconfig` module uses a combination of parameters provided
+via a `.yaml` file and a service discovery mechanism.
 
-## How to use this module
+## How to Use This Module
 
-This module needs to be initialized once (and only once) when you application start, you can do it with:
+This module needs to be initialized once (and only once) when you
+start the application. You can do it with:
+
 ```python
 from xosconfig import Config
 Config.init()
 ```
 
-By default the `xosconfig` module will look for a configuration file in `/opt/xos/config.yaml`, if for any reason you need to pass a different config file it can be done with:
+By default, `xosconfig` looks for a configuration file
+in `/opt/xos/config.yaml`. Passing a
+different config file can be done with:
+
 ```python
 from xosconfig import Config
 Config.init("/path/to/my/config.yaml")
 ```
 
-### Configuration defaults
-Note that defaults are defined for some of the configuration items. Defaults are defined in `lib/xos-config/xosconfig/default.py`.
+### Configuration Defaults
 
-### Reading data from the configuration file
+Defaults are defined for some of the configuration items
+in `lib/xos-config/xosconfig/default.py`.
 
-To access static information defined in the `config.yaml` file you can use this api:
+### Reading Data from the Configuration File
+
+To access static information defined in the `config.yaml` file, use
+the following API:
+
 ```python
 from xosconfig import Config
 res = Config.get('database')
 ```
-this call will return something like:
+This call returns something like:
+
 ```python
 {
     'username': 'test',
     'password': 'safe'
 }
 ```
-Since the configuration support nested dictionary is possible to query directly nested values using a `dot` notation, for example:
+
+Since the configuration supports a nested dictionary, it is possible to
+query directly nested values using `dot` notation. For example:
+
 ```python
 from xosconfig import Config
 res = Config.get('database.username')
 ```
-will return:
+
+returns
+
 ```python
 "test"
 ```
+
 **The configuration schema is defined in `/lib/xos-config/config-schema.yaml`**
 
-### Reading service information
+### Reading Service Information
 
-XOS is composed by a plethora of services, to discover them and their address we are using
-a tool called [registrator](https://github.com/gliderlabs/registrator).
+XOS is composed of a set of services. To discover these services and
+their address, use the
+[registrator](https://github.com/gliderlabs/registrator) tool.
  
-#### Retrieve a list of services:
+#### Retrieving a List of Services
+
+Invoking
+
 ```python
 from xosconfig import Config
 Config.get_service_list()
 ```
-this call will return an array of available services, by default:
+
+returns an array of available services; by default:
+
 ```python
 [
   "xos-ws",
@@ -71,17 +94,23 @@
   "consul",
 ]
 ```
+
 >You can get the same information on the `head node` using:
 >```bash
 > curl consul:8500/v1/catalog/services
 >```
 
-#### Retrieve information for a single service:
+#### Retrieve Information for a Single Service
+
+Invoking
+
 ```python
 from xosconfig import Config
 Config.get_service_info('xos-db')
 ```
-that will return:
+
+returns
+
 ```python
 {
     'name': 'xos-db',
@@ -94,12 +123,17 @@
 > curl consul:8500/v1/catalog/service/xos-db
 >```
 
-#### Retrieve endpoint for a single service:
+#### Retrieving Endpoint for a Single Service
+
+Invoking
+
 ```python
 from xosconfig import Config
 Config.get_service_endpoint('xos-db')
 ```
-that will return:
+
+returns
+
 ```python
 "http://172.18.0.4:5432"
-```
\ No newline at end of file
+```
diff --git a/docs/security_policies.md b/docs/security_policies.md
new file mode 100644
index 0000000..d900788
--- /dev/null
+++ b/docs/security_policies.md
@@ -0,0 +1,52 @@
+# Security Policies
+
+CORD security policies are implemented by XOS. These policies answer
+the question: *Who can do what?* The *who* in this case generally
+refers to a user (represented by a *User* model), but it can also
+refer to an API context. The *what* refers to two things: (1) the
+piece of information being accessed (a model, an object, or a field
+within that object), and (2) the access type (whether it is a read, a
+write, or a privilege update).
+
+## Summary of Policy Mechanism
+
+The mechanism for expressing these policies is provided by xproto’s
+policy extensions. The policies are enforced at the API boundary. When
+an API call is made, the appropriate policy is executed to determine
+whether or not access should be granted, and an audit trail is left
+behind. (Note: auditing is a TODO). The policy enforcers are
+auto-generated by the generative toolchain as part of the model
+generation process.
+
+Policies are generic logic expressions and can operate on any model
+or on the environment, but they frequently use the *Privilege* model.
+Specifically, when a policy cannot be expressed as a general principle
+(e.g., “a user can do whatever they want to a slice if he or she is
+its creator”) and instead depends on dynamic conditions, then it is
+encoded with the help of Privilege objects. For example, a Privilege
+object may be created to indicate that a user who is not a slice’s
+creator has admin privileges on it.
+
+Details on how policies are encoded can be found elsewhere.
+This document is about the “what” rather than the “how.”
+
+The set of security policies is being bootstrapped into the following
+state:
+
+* Privilege objects are automatically created for Slices. Most access
+control (e.g., to Networks and Instances) is via Slice, so this
+privilege covers the bulk of the access control.
+
+* Privileges for other models need to be created manually via the API
+(e.g., Sites, Services).
+
+* Any principal that has access to object *X* is also granted access
+to object *ControllerX*.
+
+* There are three types of access permissions: *Read*, *Write*, and
+*Grant*. Grant arbitrates access to Privilege objects (e.g., a slice
+admin could grant slice admin privileges to a user).
+
+The current policies are defined as follows:
+
+**To be included...*