diff --git a/README.md b/README.md
index 41e51f367..183ade9a3 100644
--- a/README.md
+++ b/README.md
@@ -93,7 +93,7 @@ Other options include:
 
 > Note: The Spectral CLI supports both YAML and JSON.
 
-Currently, the CLI supports validation of OpenAPI documents and lints them based on our default ruleset. It does not support custom rulesets at this time. Although if you want to build and run custom rulesets outside of the CLI, see [Customization](#Customization).
+Currently, Spectral CLI CLI supports validation of OpenAPI documents and lints them based on our default ruleset, or you can provide [your own rulesets](docs/rulesets.md).
 
 ## Concepts
 
@@ -105,13 +105,13 @@ There are three key concepts in Spectral: **Rulesets**, **Rules** and **Function
 
 Think of a set of **rules** and **functions** as a flexible and customizable style guide for your JSON objects.
 
-## Programmatic usage
+## Config
 
-Spectral is written in TypeScript (JavaScript) and can be used directly for when you need to use Spectral programatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md).
+Spectral CLI supports [config files](docs/config.md), to avoid typing out CLI options and arguments every single time. 
 
-## Rulesets
+## Programmatic usage
 
-You can find all about [rulesets here](docs/rulesets.md).
+Spectral is written in TypeScript (JavaScript) and can be used directly for when you need to use Spectral programmatically. Take a look at our ["JavaScript API documentation"](docs/js-api.md).
 
 ## FAQs
 
diff --git a/docs/config.md b/docs/config.md
new file mode 100644
index 000000000..672282b7e
--- /dev/null
+++ b/docs/config.md
@@ -0,0 +1,62 @@
+---
+title: Spectral Config
+tags: 
+- Documentation
+- Config
+---
+
+Spectral CLI supports config files, to avoid typing out CLI options and arguments every single time. 
+
+By default Spectral CLI will look for `spectral.yml` in the current working directory, but it could be any JSON or YAML file if you specify it with the `--config` option. 
+
+## Usage
+
+```bash
+spectral lint openapi.yaml --config=spectral.yaml
+```
+
+## Example Config
+
+```yaml
+lint:
+  format: json
+  ruleset: 
+  - http://apis.example.com/governance/core.yml
+  - http://apis.example.com/governance/rest.yml
+  skipRule: 
+  - that-one-rule
+  - broken-rule
+  output: tmp/lint-results.json
+  verbose: true
+```
+
+Right now Spectral only has the one command: `lint`, but other commands in the
+future will have their own config namespace too.
+
+Here are all the available options, with their default values:
+
+```yaml
+lint:
+  encoding: utf8   # text encoding to use
+  format: stylish  # stylish, json
+  output:          # filename for output instead of stdout
+  maxResults:      # only show the first X erros
+  verbose: false   # see more output for debugging
+  ruleset:         # array of local files or URLs
+  quiet: false     # see only results
+  skipRule: []     # array of rule names as strings
+```
+
+The TypeScript interface here looks like this:
+
+```typescript
+export interface ILintConfig {
+  encoding: string;
+  format: ConfigFormat;
+  maxResults?: number;
+  output?: string;
+  ruleset?: string[];
+  skipRule?: string[];
+  verbose: boolean;
+}
+```
diff --git a/docs/rulesets.md b/docs/rulesets.md
index 26b37cece..094a0a3e3 100644
--- a/docs/rulesets.md
+++ b/docs/rulesets.md
@@ -1,4 +1,13 @@
-# Spectral Rulesets
+---
+title: Spectral Rulesets
+tags: 
+- Documentation
+- Rulesets
+---
+
+Rulesets are a container for collections of rules. These rules are essentially calling functions Spectral, and by taking parameters you can make these functions do whatever you want. 
+
+First the rule filters your object (JSON/YAML file) down to a set of target values, and then list what function arguments should be passed in.
 
 ## Usage
 
@@ -6,7 +15,7 @@
 spectral lint foo.yaml --ruleset=path/to/acme-company-ruleset.yaml --ruleset=http://example.com/acme-common-ruleset.yaml
 ```
 
-## Example ruleset file
+## Example Ruleset
 
 We currently support ruleset files in both `yaml` and `json` formats.
 
@@ -28,8 +37,6 @@ Rules are highly configurable. There are only few required parameters but the op
 
 *TODO: generate this table automatically from the TS file.*
 
-### Rule
-
 <table>
   <thead>
     <tr>
@@ -140,14 +147,14 @@ Rules are highly configurable. There are only few required parameters but the op
   </tbody>
 </table>
 
-### Ruleset validation
+## Ruleset Validation
 
 We use JSON Schema & AJV to validate your rulesets file and help you spot issues early.
 
 **Example output**
 
 ```bash
-spectral lint some-oas.yaml --ruleset acme-company.json
+$ spectral lint some-oas.yaml --ruleset acme-company.json
 
 Reading ruleset
 
@@ -158,12 +165,5 @@ Reading ruleset
 /rules/rule-with-invalid-enum/type 	 should be equal to one of the allowed values 
 ```
 
-**Note for developers**
-
-Supporting YAML and JSON file validation doesn't come free. 
-We need to maintain schema files that mirror IRule and IRuleset types (see `/src/meta/*.schema.json`).
-Ideally, we would have a script that converts TS type to JSON Schema and keeps the meta files up to date. As of now we have a helper that partially automates the work.
-
-Execute `yarn schema.update` to recreate the `/src/meta/rule.schema.json`.
-It will take `IRule` type from `types.ts` file and automatically update the JSON Schema file we use to validate yaml/json ruleset files.
-**Warning**: make sure to update *generic* types. Current tools fails to recognize it properly and e.g. treats `string` as `object`.
+These errors should look just like errors you get from Spectral when an API description is invalid, 
+so use them to fix your rules in the same way.
\ No newline at end of file