update README

README.md

@@ -1,15 +1,21 @@
-scribe
-======
+# scribe
 
 scribe is a host policy evaluator written in Go.
 
 [![Build Status](https://travis-ci.org/mozilla/scribe.svg?branch=master)](https://travis-ci.org/mozilla/scribe)
+[![Go Report Card](https://goreportcard.com/badge/mozilla/scribe "Go Report Card")](https://goreportcard.com/report/mozilla/scribe)
+
+## Overview
 
-Overview
---------
 scribe is a Go library and frontend used to evaluate policies on systems.
-Policies are specified as a JSON document containing a series of tests, and
-these tests return a status indicating if the test criteria passed.
+Policies are specified as a JSON or YAML document containing a series of tests, and
+these tests return a status indicating if the test criteria matched or not.
+
+Tests reference objects in the policy file. An object can be considered an abstraction
+of some data from the system, for example a package version or the contents of a specific
+file. The tests also specify criteria that will be applied to the referenced object. For example,
+if an object returns a line from a given file, the test could indicate that the data must
+match specific content. If the match succeeeds, the test returns true.
 
 It is intended to perform functions such as:
 
@@ -27,6 +33,32 @@ investigators to perform system evaluation by sending a policy to the MIG
 agent for execution. It is also suited to executing policies as part of an
 instance build and testing process, or periodically on an installed system.
 
-Additional documentation
-------------------------
+## Usage
+
+Scribe policies can be evaluated using the scribecmd command line tool, or alternatively the scribe
+library can be included in another go application.
+
+This example shows evaluation of a given policy file, where only tests that return
+true are displayed in the results.
+
+```bash
+$ ./scribecmd -f mypolicy.json -T
+```
+
+scribecmd supports other runtime options, see the usage output for details.
+
+## Vulnerability scanning
+
+scribe can be used to perform vulnerability scanning directly on the system using a suitable
+policy file. The library implements various criteria specifications such as
+EVR (epoch/version/release) testing that can be used to determine if a given package
+version if less than what is required.
+
+scribevulnpolicy is a policy generator that integrates with [clair](https://github.com/coreos/clair)
+for vulnerability data. This tool can be used to generate scribe vulnerability check
+policies for supported platforms. For details on usage see the
+[documentation for scribevulnpolicy](./scribevulnpolicy/README.md).
+
+## Additional documentation
+
 Additional documentation on the library is available at [godoc.org](https://godoc.org/github.com/mozilla/scribe/).