Update documentation

docs/sync-details.md

@@ -9,6 +9,20 @@ This page aims to describe how Rojo turns files on the filesystem into Roblox ob
 | `*.lua`        | `ModuleScript`      |
 | `*.csv`        | `LocalizationTable` |
 | `*.txt`        | `StringValue`       |
+| `*.model.json` | Any                 |
+| `*.rbxm`       | Any                 |
+| `*.rbxmx`      | Any                 |
+
+## Limitations
+Not all property types can be synced by Rojo in real-time due to limitations of the Roblox Studio plugin API. In these cases, you can usually generate a place file and open it when you start working on a project.
+
+Some common cases you might hit are:
+
+* Binary data (Terrain, CSG, CollectionService tags)
+* `MeshPart.MeshId`
+* `HttpService.HttpEnabled`
+
+For a list of all property types that Rojo can reason about, both when live-syncing and when building place files, look at [rbx_tree's type coverage documentation](https://github.com/LPGhatguy/rbx-tree/tree/master/rbx_tree#coverage).
 
 ## Folders
 Any directory on the filesystem will turn into a `Folder` instance unless it contains an 'init' script, described below.
@@ -20,16 +34,68 @@ If a directory contains a file named `init.server.lua`, `init.client.lua`, or `i
 
 For example, these files:
 
-* my-game
-    * init.client.lua
-    * foo.lua
+<div align="center">
+    <a href="../images/sync-example-files.svg">
+        <img src="../images/sync-example-files.svg" alt="Tree of files on disk" />
+    </a>
+</div>
 
 Will turn into these instances in Roblox:
 
-![Example of Roblox instances](/images/sync-example.png)
+<div align="center">
+    <a href="../images/sync-example-instances.svg">
+        <img src="../images/sync-example-instances.svg" alt="Tree of instances in Roblox" />
+    </a>
+</div>
 
 ## Localization Tables
 Any CSV files are transformed into `LocalizationTable` instances. Rojo expects these files to follow the same format that Roblox does when importing and exporting localization information.
 
 ## Plain Text Files
-Plain text files (`.txt`) files are transformed into `StringValue` instances. This is useful for bringing in text data that can be read by scripts at runtime.
+Plain text files (`.txt`) files are transformed into `StringValue` instances. This is useful for bringing in text data that can be read by scripts at runtime.
+
+## JSON Models
+Files ending in `.model.json` can be used to describe simple models. They're designed to be hand-written and are useful for instances like `RemoteEvent`.
+
+A JSON model describing a folder containing a `Part` and a `RemoteEvent` could be described as:
+
+```json
+{
+    "Name": "My Cool Model",
+    "ClassName": "Folder",
+    "Children": [
+        {
+            "Name": "RootPart",
+            "ClassName": "Part",
+            "Properties": {
+                "Size": {
+                    "Type": "Vector3",
+                    "Value": [4, 4, 4]
+                }
+            }
+        },
+        {
+            "Name": "SendMoney",
+            "ClassName": "RemoteEvent"
+        }
+    ]
+}
+```
+
+It would turn into instances in this shape:
+
+<div align="center">
+    <a href="../images/sync-example-json-model.svg">
+        <img src="../images/sync-example-json-model.svg" alt="Tree of instances in Roblox" />
+    </a>
+</div>
+
+## Binary and XML Models
+Rojo supports both binary (`.rbxm`) and XML (`.rbxmx`) models generated by Roblox Studio or another tool.
+
+Not all property types are supported!
+
+For a rundown of supported types, see:
+
+* [rbxm Type Coverage](https://github.com/LPGhatguy/rbx-tree/tree/master/rbx_binary#coverage)
+* [rbxmx Type Coverage](https://github.com/LPGhatguy/rbx-tree/tree/master/rbx_xml#coverage)