update docs
document scopes using @jrpereira's API
more work on docs, explain validators