README.md in gds-sso-11.2.1 vs README.md in gds-sso-12.0.0

@@ -57,16 +57,66 @@
 
 ```ruby
 serialize :permissions, Array
 ```
 
-If your app is using `rspec`, there is a [shared examples spec](/lib/gds-sso/lint/user_spec.rb) that can be used to verify that your `User` model implements the necessary methods for `gds-sso` to work correctly. To use it:
+If your app is using `test-unit` or `minitest`, there is a linting test that can verify your `User` model is compatible with `GDS:SSO::User`:
 
 ```ruby
+require 'gds-sso/lint/user_test'
+
+class GDS::SSO::Lint::UserTest
+  def user_class
+    ::User
+  end
+end
+```
+
+Or if your app is using `rspec`, there is a [shared examples spec](/lib/gds-sso/lint/user_spec.rb):
+
+```ruby
 require 'gds-sso/lint/user_spec'
 
 describe User do
   it_behaves_like "a gds-sso user class"
+end
+```
+
+### Usage
+
+[GDS::SSO::ControllerMethods](/lib/gds-sso/controller_methods.rb) provides some useful methods for your application controllers.
+
+To ensure only users who have been granted access to the application can access it use `require_signin_permission!`.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include GDS::SSO::ControllerMethods
+  before_action :require_signin_permission!
+  # ...
+end
+```
+
+If you want to allow access to everyone with an active signon account, use `authenticate_user!`.
+
+```ruby
+class ApplicationController < ActionController::Base
+  include GDS::SSO::ControllerMethods
+  before_action :authenticate_user!
+  # ...
+end
+```
+
+You can refine authorisation to specific controller actions based on permissions using `authorise_user!`. All permissions are assigned via signon.
+
+```ruby
+class PublicationsController < ActionController::Base
+  include GDS::SSO::ControllerMethods
+  before_action :authorise_for_editing!, except: [:show, :index]
+  # ...
+private
+  def authorise_for_editing!
+    authorise_user!('edit_publications')
+  end
 end
 ```
 
 ## Use in development mode