README.markdown in soundcloud-auth-0.1.0 vs README.markdown in soundcloud-auth-0.1.1

@@ -1,2 +1,75 @@
-SoundCloudAuth
-===========
\ No newline at end of file
+SoundcloudAuth
+===========
+
+SoundcloudAuth aims to provide a complete authentication and API access solution for creating SoundCloud applications in Rails. It provides a generator and all of the necessary components to use Soundcloud as the sole authentication provider for an application using OAuth.
+
+### Major Props
+
+SoundcloudAuth is largely influenced and in a lot of ways identical to [Michael Bleigh's](http://github.com/mbleigh) amazing [TwitterAuth](http://github.com/mbleigh/twitter-auth) plugin. I've used TwitterAuth so many times on my Twitter app development that I found it sorely missed when I tried to tackle the SoundCloud platform.  All props and donations should be forwarded to Michael.
+
+Installation
+============
+
+You can include SoundcloudAuth as a gem in your project like so:
+
+    config.gem `soundcloud-auth`, :lib => `soundcloud_auth`
+
+Or you can install it as a traditional Rails plugin:
+
+    script/plugin install git://github.com/leemartin/soundcloud-auth.git
+
+Note that because SoundcloudAuth utilizes Rails Engines functionality introduced in Rails 2.3, it will not work with earlier versions of Rails.
+
+Usage
+=====
+
+To utilize SoundcloudAuth in your application you will need to run the generator:
+
+    script/generate soundcloud_auth
+
+This will generate a migration as well as set up the stubs needed to use the Rails Engines controllers and models set up by SoundcloudAuth. It will also create a User class that inherits from SoundcloudUser, abstracting away all of the SoundCloud authentication functionality and leaving you a blank slate to work with for your application. 
+
+Finally, it will create a configuration file in `config/soundcloud_auth.yml` in which you should input your OAuth consumer key and secret as well as a custom callback for development (the 'oauth_callback' option is where SoundCloud will send the browser after authentication is complete).
+
+Usage Basics
+------------
+
+SoundcloudAuth borrows heavily from [Restful Authentication](http://github.com/technoweenie/restful-authentication) for its API because it's simple and well-known. Here are some of the familiar methods that are available:
+
+* `login_required`: a before filter that can be added to a controller to require that a user logs in before he/she can view the page.
+* `current_user`: returns the logged in user if one exists, otherwise returns `nil`.
+* `logged_in?`: true if logged in, false otherwise.
+* `redirect_back_or_default(url)`: redirects to the location where `store_location` was last called or the specified default URL.
+* `store_location`: store the current URL for returning to when a `redirect_back_or_default` is called.
+* `authorized?`: override this to add fine-grained access control for when `login_required` is already called.
+
+Accessing the SoundCloud API
+-------------------------
+
+The `User` class will have a `soundcloud` method that provides a generic dispatcher with HTTP verb commands available (`get`, `put`, `post`, and `delete`). These are automatically initialized to the `base_url` you specified in the `twitter_auth.yml` file, so you need only specify a path. Additionally, it will automatically append a .json extension and parse the JSON if you don't provide.
+
+    user.soundcloud.get('/me')
+    # => {'username' => 'leemartin', 'full_name' => 'Lee Martin' ... }
+
+		user.soundcloud.put('/me', 'user[website]=http://lee.ma/rtin')
+		# => {'username' => 'leemartin', 'website' => 'http://lee.ma/rtin'}
+
+If SoundCloud returns something other than a 200 response code, SoundcloudAuth will catch it and try to raise a salient error message. The exception class is `SoundcloudAuth::Dispatcher::Error`.
+
+Customizing SoundcloudAuth
+-----------------------
+
+There are a number of hooks to extend the functionality of SoundcloudAuth. Here is a brief description of each of them.
+
+### Controller Methods
+
+SoundcloudAuth provides some default controller methods that may be overridden in your `ApplicationController` to behave differently.
+
+* `authentication_failed(message)`: called when SoundCloud authorization has failed during the process. By default, simply redirects to the site root and sets the `flash[:error]`.
+* `authentication_succeeded(message=default)`: called when SoundCloud authorization has completed successfully. By default, simply redirects to the site root and sets the `flash[:notice]`.
+* `access_denied`: what happens when the `login_required` before filter fails. By default it stores the current location to return to and redirects to the login process.
+
+Copyright
+---------
+
+**SoundcloudAuth** is Copyright (c) 2010 [Lee Martin](http://lee.ma/rtin), released under the MIT License.