Update modeling-introduction.md

Add Viewing Changes article

articles/accounts/changing-your-email.md

@@ -7,7 +7,7 @@ Changing your email address is easy as pie
 
 ## How 
 1. Click on your **username** in the top right 
-2. Click on the **Account** button.
+2. Click on the **Account** button
 3. In the **Basic Info** section, replace the email listed with one you would like to change to 
 4. Click **Save** and you’re all done 
 

articles/accounts/changing-your-username.md

@@ -8,5 +8,5 @@ You can change your username at any time
 ## How 
 1. Click on your current **username** in the top right 
 2. Click on **Account** 
-3. Under **Basic Info** input a new username 
+3. Under **Basic Info**, input a new username 
 4. Click **Save** 

articles/accounts/edit-profile.md

@@ -3,18 +3,18 @@
 ![](../../assets/gifs/account-info.gif)
 
 ## What 
-* In your profile you can edit things like: 
-    * Basic Info 
-        * Username 
-        * Name
-        * Email
-    * Upload a profile image 
-    * Change Password 
+In your profile you can edit things like: 
+* Basic Info 
+    * Username 
+    * Name
+    * Email
+* Upload a profile image 
+* Change Password 
  
 ##  How
 1. Select your **Username** in the top right corner
 2. Click **Account**
-3. Make your edits in **Basic Info** then click **Save** 
+3. Make your edits in **Basic Info**, then click **Save** 
     * You can also click **Reset** if you would like to start from scratch 
 4. Upload a profile image 
 5. Make your edits in Change Password then click **Change Password** 

articles/accounts/manage-password.md

@@ -3,10 +3,10 @@
 ![](../../assets/gifs/account-info.gif)
 
 ## What 
-* If you’ve forgotten the password you use to sign in to Stoplight; you can easily reset it at any time
+If you’ve forgotten the password you use to sign in to Stoplight; you can easily reset it at any time
 
 ## What
-1. At the login page select **Forgot Password?**
+1. At the login page, select **Forgot Password?**
 2. Input your email in the space provided 
 3. Click **Send Email Link** 
 4. An email will be sent with a link to your email address

articles/accounts/sign-in.md

@@ -1,9 +1,9 @@
 # Sign In To Stoplight 
 
 ## What
-* There are two separate options for creating your snazzy new Stoplight account: 
-    * Login with GitHub 
-    * Create a new account 
+There are two separate options for creating your snazzy new Stoplight account: 
+* Login with GitHub 
+* Create a new account 
   
 ## How
 

articles/desktop/overview.md

@@ -21,13 +21,3 @@ When you start the Stoplight desktop app, it will start an instance of Prism on
 
 * The Stoplight desktop app can read/write specification files on your local file system. This is perfect for generating specification outside of Stoplight (like from code), want to use version control systems like Git, or want to use your favorite IDE to work on a spec. 
 * This feature is **NOT** available in the web app 
-
-
-
-
- the web app 
-
-
-<!--stackedit_data:
-eyJoaXN0b3J5IjpbMTU3NDc5MjY0XX0=
--->

articles/editor/view-history-changes.md

@@ -1 +1,32 @@
+# Viewing Changes
 
+As more users edit files within the same project, tracking changes over time
+becomes increasingly difficult. To mitigate these effects, Stoplight provides the full history of changes, which allows you to view and track any changes made.
+
+To see the history of changes for a project, use the 'History' button on the
+navigation bar to the left of the project window (shown below). When the history
+is being viewed, you will see a series of changes for the project, listed in
+descending order by date.
+
+![](../../assets/images/viewing-changes2.png)
+
+Each change event includes:
+
+* The date when the change was made
+
+* The user who made the change
+
+* The files updated by the change
+
+* The differences (known as the 'diff') between each file before and after the
+  change occurred
+
+See the image below for an overview of the contents of the change view.
+
+![](../../assets/images/viewing-changes.png)
+
+---
+
+**Related**
+
+* [Working with Files](./working-with-files.md)

articles/getting-started/what-is-stoplight.md

@@ -29,8 +29,8 @@ Stoplight provides a complete mock server for every API described in the app. Ru
 
 Spinning up your own mock server is as simple as:
 
-# install prism on macOS
+### install prism on macOS
 curl https://raw.githubusercontent.com/stoplightio/prism/master/install.sh | sh
 
-# run a fake petstore api on http://localhost:4010
+### run a fake petstore api on http://localhost:4010
 prism run --mock --list --spec http://petstore.swagger.io/v2/swagger.json

articles/hubs/pages.md

@@ -24,7 +24,8 @@ Pages are the macro level building blocks of a Hub. They function as the canvas
     2. Input a **Page Route** (optional) 
     3. **Power the Page** with an External Data Source (optional) 
 
-<callout> Did you know? After creating a new page; a header link will automatically be generated </> 
+<!-- theme: info -->
+ >Did you know? After creating a new page; a header link will automatically be generated
+
 
-<callout> To add content to a page you must add a subpage or a content block </>   
 

articles/hubs/routing.md

@@ -12,26 +12,26 @@ Stoplight’s Hubs features an easy to use routing system to make sure your docs
 - Headers + Footers (link)
 - Links 
 
-<callout>Tips for Friendly URL’s 
 
-Friendly URLs are links that are easily readable, rememberable, and relevant to the content.
+<!-- theme: info -->
+>Friendly URLs are links that are easily readable, rememberable, and relevant to the content.
 Take a look at the URL for this page. Instead of something like https://help.stoplight.io/docs/fnIenof/123, it is https://help.stoplight.io/docs/hosted-documentation/create-friendly-urls, which is much nicer. </>
 
 ## How 
 
 ### Pages & Subpages 
 
-1. Select the Hub you wish to modify 
-2. Add a new page or subpage (link) 
-   a. Select a page title to auto-fill the Page Route or 
-   b. Input a custom page route 
-3. Select an existing page or subpage 
-4. Select the gear icon at the top of the Hub in the center of the page or subpage you wish to modify  
-   a. Input a new URL under Page Route  
+1. Select the **Hub** you wish to modify 
+2. Add a new **page** or **subpage** (link) 
+   1. Select a **page title** to auto-fill the **Page Route** or 
+   2. Input a **custom page route** 
+3. Select an **existing page** or **subpage** 
+4. Select the **gear icon** at the top of the Hub in the center of the page or subpage you wish to modify  
+   1. Input a **new UR**L under Page Route  
 
 ### Headers & Footers 
 
-1. Select the Hub you wish to modify 
-2. Add a new header or footer (link) or
-3. Hover over an existing header or footer and click the gear icon 
-    a. Input a Path to Page or image URL  
+1. Select the **Hub** you wish to modify 
+2. Add a new **header or footer** (link) or
+3. Hover over an existing header or footer and click the **gear icon** 
+    a. Input a **Path to Page** or **image URL**  

articles/hubs/subpages.md

@@ -5,6 +5,9 @@
 ## What
 Subpages are the second tier macro building blocks of Hubs. They function as a canvas for blocks. They are commonly used to house content based on a specific topic.  Subpages can have more subpages nested underneath them, which gives you lots of flexibility to organize your Hub as you see fit. If a subpage has subpages nested inside of it, it will be displayed as a collapsible group in the left sidebar.
 
+<!-- theme: info -->
+>Subpages populate the navigational sidebar of a page.
+
 ### Hubs Architecture Top Down
 - Pages 
     - Subpages 
@@ -24,7 +27,6 @@ Subpages are the second tier macro building blocks of Hubs. They function as a c
     3. Give the Subpage a **Sidebar Token** (optional) 
     4. **Power the Subpage** with an External Data Source (optional) 
 
-<callout> Subpages populate the navigational sidebar of a page. </>
-
-<callout> Just like pages, subpages can have blocks. Any blocks added to a subpage will be displayed when a reader navigates to that subpage in your hub</>
+<!-- theme: info --> 
+>Just like pages, subpages can have blocks. Any blocks added to a subpage will be displayed when a reader navigates to that subpage in your hub
 

articles/modeling/duplication-refs.md

@@ -7,7 +7,7 @@
 - Similar features can be created as reusable definitions and utilized with references
 - These definitions can be hosted on the same server as your OAS file or on a different server 
 - You can reference a definition hosted at any location or server 
-- Apart from defining reusable definitions, you can also define reusable responses and parameters. You can store your reusable definitions, responses, and parameters in a common library. 
+- Apart from defining reusable definitions, you can also define reusable responses and parameters. You can store your reusable definitions, responses, and parameters in a common library
 
 <!-- theme: info --> 
 >Key Terms: A definition is a named schema object. A reference is a path to a declaration within an OAS file.

articles/modeling/modeling-introduction.md

@@ -1 +1,32 @@
+# Modeling Introduction 
 
+![video/gif]()
+
+## What is API Design? 
+
+Designing (also known as Modeling) your API involves describing all of the inputs and outputs across the footprint of your entire service. Your API design will answer questions like: 
+
+- What are the different resources and operations available in your API?
+- How does your API authenticate requests? 
+- What are the different data models assoicated with your service? 
+- How does your API handle errors? 
+
+## How does it fit into Stoplight? 
+
+The Stoplight design module is where you and your team will maintain the single source of truth that describes the inputs and outputs of your API. 
+
+Once you have your API described in the Stoplight design module, you can: 
+
+- Publish all or part of your API in our Documentation service 
+- Create API tests from your designs 
+- Send requests to your API to debug it 
+- ...and much more 
+
+## Getting Started 
+
+There are a few ways to get started designing your API with the Stoplight design module, depending on how developed your API is:
+
+- Create an API from scratch [Using the CRUD Builder]()
+- [Reference another API Spec]()
+- [Send HTTP Requests]() to an existing API Spec 
+- [Validate your API Spec]()

articles/modeling/object-inheritance.md

@@ -1,38 +1,143 @@
-# Object Inheritance 
+# Object Inheritance
 
-## What 
-- A **model** contains common resuable information that can be referenced in your endpoint definitions or other models in your API design. 
-- When a model derives its properties from another model, the event is called **inheritance**. 
-- The model which contains the common set of properties and fields becomes a parent to other models, and it is called the **base type**.
-- The model which inherits the common set of properties and fields is known as the **derived type**.
-- If a base type inherits its properties from another model, the derived type automatically inherits the same properties indicating that inheritance is **transitive**. 
-- OpenAPI Specification v2 uses the **allOf** syntax to declare inheritance. 
-- **allOf** obtains a collection of object definitions validated independently but, collectively make up a single object. 
+## What
 
-## Why 
-- Inheritance makes your API design more compact. It helps avoid duplication of common properties and fields. 
+* A **model** contains properties that can be reused and referenced by endpoint
+  definitions, shared objects, and other models. For more information on what
+  models are and how they can be used, please see the API model overview
+  [here](./api-models.md).
 
-## Best Practices 
+* **Inheritance** is when a model derives its properties from another model.
 
-<!-- theme: info --> 
-> Avoid using contradictory declarations such as declaring properties with the samer name but dissimilar data type in your base model and derived model. 
+* When a model inherits properties from another model, the model being inherited from is
+  known as a **base type** (or parent). A model that is inheriting
+  properties from a base type is known as a **derived type** (or child).
 
-### Example 
+* When a base type inherits properties from another model, any derived types
+  will also automatically inherit the properties as well. For example, if model
+  C is a derived type of model B, and model B is a derived type of model A, then
+  model C is also a derived type of model A. In mathematics, this is known as
+  the [transitive property](https://en.wikipedia.org/wiki/Transitive_relation).
 
-```
+* To specify that a model should inherit from a base type, use the **allOf**
+  option (under "Combination Types") when building the model. By specifying
+  allOf and referencing the base type, the model will automatically inherit all
+  of the parent model's properties. A model can also inherit from multiple base
+  types as needed.
+
+## Why
+
+* Inheritance makes your API design more compact. It helps avoid duplication of
+  common properties and fields, reducing the complexity of the specification and the chance of errors.
+
+## Best Practices
+
+<!-- theme: info -->
+
+> Avoid using contradictory declarations such as declaring properties with the
+> same name but dissimilar data type in your base model and derived model.
+
+### Example
+
+As an example, imagine you are creating an API that stores and categorizes
+different types of vehicles. To begin working on the API, you will need a base
+"car" model with a few attributes that are common across all vehicles. This
+might look similar to:
+
+```javascript
+// the car base type
 {
-  Vehicle: 
-    type: object
-    properties: 
-      brand: 
-        type: string 
-  Sedan: 
-    allOf: # (This keyword combines the Vehicle model and the Sedan model) 
-      $ref: '#/definitions/Vehicle'
-      type: object
-      properties: 
-        isNew:
-          type: boolean
+  "type": "object",
+  "properties": {
+    // number of wheels
+    "wheels": {
+      "type": "integer"
+    },
+    // number of doors
+    "doors": {
+      "type": "integer"
+    },
+    // brand of car
+    "make": {
+      "type": "string"
+    },
+    // model of car
+    "model": {
+      "type": "string"
+    }
+  }
 }
 ```
 
+<!--FIXME Insert image of creating model from UI -->
+
+Now that we have a base type model, we now need a derived type that extends the
+base type. Since we're dealing with cars, let's create a model that defines a
+SUV type (or a Sport Utility Vehicle):
+
+```javascript
+// the SUV model
+{
+  "allOf": [
+    // a reference to the car base type
+    {
+      "$ref": "#/definitions/car"
+    },
+    // properties that are only applied to the SUV model
+    {
+      "type": "object",
+      "properties": {
+        // whether the vehicle can go "off road"
+        "off-road": {
+          "type": "boolean"
+        },
+        // the amount of ground clearance
+        "ground-clearance": {
+          "type": "integer"
+        }
+      }
+    }
+  ]
+}
+```
+
+<!--FIXME Insert image of creating derived model in UI -->
+
+As shown above, by wrapping our SUV model inside of an `allOf` block, we are
+able to include all of the properties that are included in the car base model
+above.
+
+When fully de-referenced (the car reference is replaced with the car
+properties), the derived SUV model will have the following JSON properties:
+
+```javascript
+{
+  "type": "object",
+  "properties": {
+    // number of wheels
+    "wheels": {
+      "type": "integer"
+    },
+    // number of doors
+    "doors": {
+      "type": "integer"
+    },
+    // brand of car
+    "make": {
+      "type": "string"
+    },
+    // model of car
+    "model": {
+      "type": "string"
+    },
+    // whether the vehicle can go "off road"
+    "off-road": {
+      "type": "boolean"
+    },
+    // the amount of ground clearance
+    "ground-clearance": {
+      "type": "integer"
+    }
+  }
+}
+```

articles/modeling/polymorphic-objects.md

@@ -1,44 +0,0 @@
-# Polymorphic Objects 
-
-## What 
-
-- Resources in your API are polymorphic. They can be returned as XML or JSON and can have a flexible amount of fields. You can also have requests and responses in your API design that can be depicted by a number of alternative schemas. 
-- **Polymorphism** is the capacity to present the same interface for differing underlying forms. 
-- The **discriminator** keyword is used to designate the name of the property that decides which schema definition validates the structure of the model. 
-
-## Why 
-- Polymorphism permits combining and extending model definitions. 
-
-## Best Practices
-
-<!-- theme: warning -->
->The discriminator property **must** be a mandatory or required field. When it is used, the value **must** be the name of the schema or any schema that inherits it. 
-
-### Example 
-
-```
-{
-  definitions:
-  Vehicle:
-    type: object, 
-    discriminator: brand
-    properties:
-      model:
-        type: string
-      color:
-        type: string
-      required:
-    model
-    
-  Sedan: # Sedan is used as the discriminator value 
-  
-    allOf:
-      $ref: '#/definitions/Vehicle'
-      type: object
-        properties:
-          dateManufactured: 
-            type: date
-          required: 
-            dateManufactured
-}
-```

articles/modeling/shared-params-responses.md

@@ -1 +1,194 @@
+# Shared Parameters and Responses
 
+While designing API's in Stoplight, it is common to have multiple endpoints
+share a set of query parameters and API responses. To help reduce extra
+work (and the chance of introducing errors), it is important to: 
+
+* Identify endpoints with common parameters 
+* Use _shared components_ to reference the same property multiple times instead
+  of rewriting the properties for each individual endpoint.
+
+Shared components in Stoplight come in two forms:
+
+* __Parameters__ - These are shared parameters that can be applied to requests
+  across multiple endpoints.
+
+* __Responses__ - These are shared response objects that can be applied to
+  multiple endpoints.
+
+## Parameters
+
+Shared parameters provide a way to use request properties across multiple API
+endpoints without having to duplicate effort.
+
+![](../../assets/gifs/shared-params-responses-param.gif)
+
+Shared parameters are supported in the following request property locations:
+
+  * __path__ - The request URL path
+  * __query__ - The request URL query string
+  * __header__ - The request HTTP Header field object
+  * __body__ - The request HTTP message body
+  * __form-data__ - The request HTTP message body in the `multipart/form-data` format 
+
+<!-- theme: info -->
+> For more information the above properties, see the [OpenAPI v2 Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object)
+
+Similar to generic request parameters, restrictions on the parameter values can
+also be applied based on type, expected default value, minimum/maximum length,
+and regular expression (regex).
+
+![](../../assets/images/shared-params-responses.png)
+
+To use a shared parameter, navigate to an API endpoint's _Request_ section and
+create a reference to the shared parameter using the "chain" button as shown in
+the image above. Once the parameter has been referenced, any updates to the
+shared parameter will automatically be propagated to every endpoint using that
+parameter.
+
+![](../../assets/gifs/shared-params-responses-param2.gif)
+
+Like other references in Stoplight, shared parameters can also be shared across
+files, projects, and other external sources.
+
+### Shared Parameters Example
+
+Let's say you are creating an API to serve thousands of cooking recipes. When dealing with large volumes of
+data, you typically want to avoid sending _all_ data in a request. To help avoid
+sending more data than is necessary, most applications implement a "paging"
+feature that allows clients to retrieve a small portion of results (i.e. a single
+page).
+
+There are multiple ways to approach a paging feature. For this example, we
+want to add two query string parameters to every request:
+
+* `limit` - The number of results to return when viewing a page. For example,
+  setting `limit` to `20` means that, at most, 20 results will be returned in the
+  request.
+* `offset` - The number of results to skip before returning results. For
+  example, setting an `offset` of `20` means that the API will discard the first
+  20 results.
+
+By using the two parameters above, a client can efficiently "page" through
+results, only returning items that are within the requested bounds. To demonstrate, let's use the parameters to display the first page of our recipe
+results:
+
+```
+GET /recipes?limit=20&offset=0
+```
+
+Since the `offset` is set to `0`, the API will not discard any results. Paired
+with a `limit` of `20`, we will only see the first 20 results (1 through 20). 
+
+To view the second page of recipes, we would use:
+
+```
+GET /recipes?limit=20&offset=20
+```
+
+By setting an `offset` of `20`, the API will discard the first 20 results. Paired
+again with a `limit` of `20`, we will see the second page of results (21 through
+40).
+
+### How
+Now that we know how we want the components to behave, let's create them in
+Stoplight. To get started, create a new shared parameter for an OpenAPI file
+under the "Shared" section of the menu.
+
+![](../../assets/images/shared-params-responses2.png)
+
+As shown in the image above, set the properties for each parameter based on our
+requirements:
+
+1. Be sure to set the display names for both components properly. In our
+   example, we only have two parameters, however, if there are multiple shared
+   parameters with similar names, you may want to set a more descriptive name
+   (i.e. 'recipe-limit' instead of 'limit').
+2. Since both components are query string parameters, set the property location
+   for each as 'query'.
+3. Set the name of the parameter, which is how it will be set in HTTP requests.
+4. Optional type restrictions can be applied to the values. In our case, since
+   both parameters are integer values, we can use the 'integer' format
+   restriction.
+5. Setting a default value can be useful if you don't need the client to specify
+   each parameter for every request. For our example, it makes sense to set
+   defaults that will return the first page (limit of 20, offset of 0).
+
+![](../../assets/images/shared-params-responses3.png)
+
+Once the shared parameters are created, reference them in any API endpoint under the
+__Query Parameters__ block of the request section in the editor.
+
+## Shared Responses
+
+Shared responses provide a practical way to re-use response objects across multiple API
+endpoints without having to duplicate effort. Similar to the shared components
+discussed above, shared responses allow you to reference a single response
+multiple times without having to recreate each response manually. The added
+benefit of this approach is that updates to the shared response object are
+automatically propagated to any endpoint using that object, no extra changes
+required.
+
+![](../../assets/gifs/shared-params-responses-response.gif)
+
+Shared responses allow you to configure the following properties:
+
+* Headers - Customize the HTTP Headers returned in the response
+* Response body - Customize the HTTP message body contents using the Stoplight
+  modeling tool (or reference a pre-existing model)
+
+<!-- theme: info -->
+> For more information on the above properties, see the OpenAPI v2 Specification
+  [here](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject)
+
+![](../../assets/gifs/shared-params-responses-response2.gif)
+
+To use a shared response, navigate to an API endpoint's __Response__ section and
+create a reference to the shared response by choosing the _Type_ of the response
+as "Reference". Once the Response type is set to "Reference", you can then
+choose the shared response to use for that endpoint. Shared responses can also
+be shared across files, projects, and other external sources.
+
+### Shared Responses Example
+
+Let's say you have a set of
+API endpoints that should return the same error response when a failure occurs.
+Every time an error is returned from the API, you want to make sure the
+following properties are returned:
+
+* `error_message` - A descriptive error message about the failure in string format.
+* `error_code` - A code representing the category of the failure in integer format.
+* `tracking_id` - A tracking ID that can be used by the caller to follow-up with
+  an administrator for more information (ie, debug an issue with customer
+  support).
+
+Now that we know what should be returned, let's create a shared response in
+Stoplight. To get started, create a new shared response for an OpenAPI file
+under the "Shared" section of the menu.
+
+![](../../assets/images/shared-params-responses4.png)
+
+As shown in the image above, set the properties for each portion of the response
+based on our requirements:
+
+1. Set the name of the shared response. In our example, we only have one error
+   type, however, if there are multiple error responses with similar names, you
+   may want to set a more descriptive name (ie, 'api-tracking-error' instead of
+   'error').
+2. A short description of the error response, such as why it is needed and how
+   it is used.
+3. The contents of the shared response object based on the three required
+   properties above.
+
+![](../../assets/images/shared-params-responses5.png)
+
+Once the shared response is created, it can be referenced in any API endpoint by
+using a _Reference_ type under a response. A shared response can also be used
+multiple times under the same endpoint.
+
+***
+
+**Related**
+
+* [OpenAPI v2 Parameter Objects Reference](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameter-object)
+* [OpenAPI v2 Response Objects Reference](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject)

articles/testing/run-test-terminal.md

@@ -1,80 +1,75 @@
-# Running a Scenario from Terminal
+# Running Prism from the Terminal
 
 It is very easy to run scenario collections, or individual scenarios, on your own computer, completely outside of the Scenarios app.
 
 First, install Prism, our command line tool for running scenarios.
 
-*On macOs or Linux:*
-```
+_On macOS or Linux:_
+
+```bash
 curl https://raw.githubusercontent.com/stoplightio/prism/2.x/install.sh | sh
 ```
 
-*On Windows:*
+<!-- theme: info -->
+
+> When installed through the installation script, Prism will be installed to `/usr/local/bin/prism`
+
+_On Windows:_
+
 ```
 Download from https://github.com/stoplightio/prism/tree/2.x
 ```
 
-After installing, you should be able to run `prism -h` (or `prism.exe -h` in Windows) and see some help text. 
+After installing, you should be able to run `prism -h` (or `prism.exe -h` in Windows) from your CLI and see the Prism help text.
 
-The Scenario app has a convenient display that gives you the exact command required to run the collection or scenario that you are viewing, taking into account your current environment variables. If you have the Scenario editor connected to a local file on your computer, it will use the path to that file, otherwise it will use the Scenario SRN (unique identifier).
+The Scenario app has a convenient display that gives you the exact command required to run the collection or scenario that you are viewing (taking into account your current environment variables). If you have the Scenario editor connected to a local file on your computer, it will use the path to that file, otherwise it will use the Scenario SRN (unique identifier).
 
 <!-- theme: warning -->
+
 > Keep in mind that if you are storing your Scenarios on Stoplight's servers, and running them from the command line, you must save them in the Stoplight app before running! This is because Prism will make a call to the Stoplight API to fetch your Scenario JSON, which it will then run from your computer.
 
 See below for a screenshot of the "Run From Terminal" command generator. The command in this box will update live in response to environment, user, and scenario changes.
 
-![](http://i.imgur.com/mqpNanE.png)
+<!-- FIXME: image showing "Run from Terminal" option under a scenario -->
 
-## Running Local Files
+## Running Scenarios
 
-The `prism conduct` command accepts a filepath. So, if you are working with [local scenario collection](#docTextSection:Ap4Z2B7RgbbLFLjJD) .json files, you can run them with something like:
+To run a local Scenario, you can use the `prism conduct` command. The `conduct`
+command accepts either a local file path or URL. If you are working with a local
+Scenario `collection.json` file, you can run the Scenario using the following
+command:
 
 ```bash
+# Run a local scenario
 prism conduct /path/to/collection.json
+
+# Run a remote scenario by URL
+prism conduct "https://export.stoplight.io/1234/master/main.scenarios.yml"
 ```
 
-## Including Specs For Contract Testing
+For more information on Scenarios and how they can be used, see [here](./scenarios-introduction.md).
 
-If you are using [contract testing](#docTextSection:tFWniZdshJYLLtKms), you will need to include the filepath to the API specification as part of the command. This is what that looks like:
+## Contract Testing
+
+To use Prism for contract testing (or API validation), you can use the `prism validate` command.
+The `validate` command takes a `--spec` argument, which is either a file path or URL to an OpenAPI specification file.
+To run a contract test against the default API URL set in the specification, use the command:
 
 ```bash
-prism conduct myOrg/scenarios/myScenarios --spec /path/to/my/swagger.json
+prism validate --spec /path/to/my/spec.json
 ```
 
-## Continuous integration
+You can also run a contract test against a specific upstream URL with the
+`--upstream` argument.
 
-Most CI products (Circle CI, Travis, Jenkins, Codship, etc) generally function in the same way: setup environment, invoke commands to run tests. With Scenarios + Prism, the process is similar. Install Prism, and then configure the CI process to run the appropriate Prism command. We've included instructions for Circle CI below, but these concepts should loosely apply to other CI products.
-
-#### Circle CI
-
-Integrating [Prism](http://stoplight.io/platform/prism) into Circle CI is easy. All you need to do is install Prism and overide the test command.
-
-To install Prism just add a dependency to your circle config.
-
-
-``` yaml
-dependencies:
-  pre:
-    - curl https://raw.githubusercontent.com/stoplightio/prism/2.x/install.sh | sh
+```bash
+prism validate --spec /path/to/my/spec.json --upstream http://localhost:8080
 ```
 
+For more information on contract testing and how it can be used, see [here](./contract-testing.md).
 
-Then override the default test command for circle in your config.
+## Related
 
-
-``` yaml
-test:
-  override:
-    - prism conduct orgId/scenarios/scenarioId
-```
-
-When running `prism conduct` you can:
-
-- Use the Scenario SRN, as displayed above.
-- Include the Scenario JSON on your CI server, and pass in its absolute file path
-- Pass in the absolute URL to the scenario JSON served up via HTTP.
-
-<!-- theme: warning -->
-> Don't forget to pass in any required environment values with the --env command line flag (or you can provide the filepath to a json file with your environment variables)!
-
-For convenience, you can find the full command to run your scenario collection or individual scenario in the Stoplight app.
+* [Scenarios Overview](./scenarios-introduction.md)
+* [Contract Testing Overview](./contract-testing.md)
+* [Integrating Prism into a CI Pipeline](./continuous-integration.md)

articles/testing/run-test-url.md

@@ -1 +1,120 @@
+# Triggering Scenarios by URL
 
+In addition to being able to run tests [through Stoplight](./run-test-stoplight.md) and [the terminal](./run-test-terminal.md),
+scenarios can also be run by issuing a HTTP request.
+
+To trigger a scenario by URL, there are two methods:
+
+* Issuing a HTTP `GET` request, which runs the collection with the project's default
+  settings and configuration.
+
+* Issuing a HTTP `POST` request, which runs the collection with variables
+  populated by the request's JSON body. This is necessary if you have passwords
+  or other sensitive pieces of data that are not stored in Stoplight, but are
+  required for running the scenario.
+
+## Finding the Scenario URL
+
+Every scenario has a unique URL that can be used to remotely trigger the
+scenario. To find this URL:
+
+* Go to the scenario's summary in Stoplight
+
+* Below the scenario summary is a "Trigger This Collection" section
+
+* Within this section is a "Trigger by URL" containing the URL unique to this
+  scenario
+
+![](../../assets/images/run-test-url.png)
+
+## Triggering Scenarios
+
+If the scenario is part of a public project and does not require any
+customization to be run, then it can be triggered by issuing a simple HTTP `GET`
+request to the scenario's URL, as shown below.
+
+```bash
+$ curl 'https://oihdflk5hiyltnnsxelttmnsw4ylsnfxxgltznvwa.prism.stoplight.io/'
+{
+  "status": "completed",
+  "failCount": 3,
+  "passCount": 6,
+  "time": 555.3748400000001,
+  "env": {
+      ...
+```
+
+To customize the scenario's variables (i.e., to add passwords and other sensitive
+information), they can either be included as URL query parameters in the `GET`
+request, or included within the request body of a `POST` request.
+
+### Customizing Variables with Query String Parameters
+
+You can customize the variables included in the scenario at runtime by adding
+extra [query string parameters](https://en.wikipedia.org/wiki/Query_string) to
+the URL.
+
+For example, if you have an `api_token` variable that is required to run your
+scenario, it can be added to the scenario by attaching the `?api_token=abc123`
+query string to the URL (where `abc123` is the value of the `api_token`
+variable).
+
+### Customizing Variables with a HTTP POST Body
+
+In addition to adding a query string parameter, scenario variables can also be
+updated by using a HTTP `POST` request instead of a `GET` request. When using
+this method, the `POST` body must be composed of JSON with the JSON keys
+corresponding to the variables within the scenario.
+
+Similar to the example above, if you have an `api_token` variable that is
+required to run your scenario, issuing a HTTP `POST` with the following JSON
+body will inject the variable into the scenario runtime.
+
+```json
+{
+  "api_token": "abc123"
+}
+```
+
+To issue a `POST` request from the CLI, you can use the `curl` command. For
+example:
+
+```bash
+$ curl -XPOST \
+     --data-binary '{"api_token":"abc123"}' \
+     'https://oihdflk5hiyltnnsxelttmnsw4ylsnfxxgltznvwa.prism.stoplight.io/'
+{
+  "status": "completed",
+  "failCount": 3,
+  "passCount": 6,
+  "time": 555.3748400000001,
+  "env": {
+      ...
+```
+
+### Triggering Scenarios in Private Projects
+
+Public project scenarios can be triggered directly through the scenario URL with
+no further action needed. Private projects, however, must have an API token
+specified so that the request can be authenticated properly. To generate a new
+API token for your Stoplight acccount, see
+[here](https://next.stoplight.io/profile/access-tokens).
+
+Once you have an API token, set it under the `Private-Token` header in order for
+it to be used to authenticate with the Stoplight API. For example:
+
+```bash
+$ curl -H 'Private-Token: H4BTDASDf5sGHMWJSfE32' ...
+```
+
+<!-- theme: warning -->
+
+> Be sure to keep all private tokens safe! They can be used to authenticate
+> requests with any project that your account has access to.
+
+---
+
+**Related**
+
+* [Running Scenarios through Stoplight](./run-test-stoplight.md)
+* [Running Scenarios from the Terminal](./run-test-terminal.md)

size.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+#set -x 
+
+# Shows you the largest objects in your repo's pack file.
+# Written for osx.
+#
+# @see https://stubbisms.wordpress.com/2009/07/10/git-script-to-show-largest-pack-objects-and-trim-your-waist-line/
+# @author Antony Stubbs
+
+# set the internal field spereator to line break, so that we can iterate easily over the verify-pack output
+IFS=$'\n';
+
+# list all objects including their size, sort by size, take top 10
+objects=`git verify-pack -v .git/objects/pack/pack-*.idx | grep -v chain | sort -k3nr | head`
+
+echo "All sizes are in kB's. The pack column is the size of the object, compressed, inside the pack file."
+
+output="size,pack,SHA,location"
+allObjects=`git rev-list --all --objects`
+for y in $objects
+do
+	    # extract the size in bytes
+	        size=$((`echo $y | cut -f 5 -d ' '`/1024))
+		    # extract the compressed size in bytes
+		        compressedSize=$((`echo $y | cut -f 6 -d ' '`/1024))
+			    # extract the SHA
+			        sha=`echo $y | cut -f 1 -d ' '`
+				    # find the objects location in the repository tree
+				        other=`echo "${allObjects}" | grep $sha`
+					    #lineBreak=`echo -e "\n"`
+					        output="${output}\n${size},${compressedSize},${other}"
+					done
+
+					echo -e $output | column -t -s ', '