README.yard.md in heimdallr-0.0.2 vs README.yard.md in heimdallr-1.0.0.RC2

@@ -17,21 +17,23 @@
   belongs_to :owner, :class_name => 'User'
 
   restrict do |user|
     if user.admin? || user == self.owner
       # Administrator or owner can do everything
-      can :fetch
-      can [:view, :create, :update, :destroy]
+      scope :fetch
+      scope :destroy
+      can [:view, :create, :update]
     else
       # Other users can view only non-classified articles...
-      can :fetch, -> { where('secrecy_level < ?', 5) }
+      scope :fetch, -> { where('secrecy_level < ?', 5) }
 
       # ... and see all fields except the actual security level...
       can    :view
       cannot :view, [:secrecy_level]
 
       # ... and can create them with certain restrictions.
+      can :create, %w(content)
       can [:create, :update], {
         owner:         user,
         secrecy_level: { inclusion: { in: 0..4 } }
       }
     end
@@ -50,24 +52,29 @@
 secure = Article.restrict(johndoe)
 
 # Use any ARel methods:
 secure.pluck(:content)
 # => ["Nothing happens", "Hello World"]
-secure.find(1).secrecy_level
-# => nil
 
 # Everything should be permitted explicitly:
 secure.first.delete
 # ! Heimdallr::PermissionError is raised
+secure.find(1).secrecy_level
+# ! Heimdallr::PermissionError is raised
 
+# There is a helper for views to be easily written:
+view_passed = secure.first.implicit
+view_passed.secrecy_level
+# => nil
+
 # If only a single value is possible, it is inferred automatically:
 secure.create! content: "My second article"
 # => Article(id: 4, owner: johndoe, content: "My second article", security_level: 0)
 
 # ... and cannot be changed:
 secure.create! owner: admin, content: "I'm a haxx0r"
-# ! ActiveRecord::RecordInvalid is raised
+# ! Heimdallr::PermissionError is raised
 
 # You can use any valid ActiveRecord validators, too:
 secure.create! content: "Top Secret", secrecy_level: 10
 # ! ActiveRecord::RecordInvalid is raised
 
@@ -78,27 +85,18 @@
 # -- No, it is not.
 ```
 
 The DSL is described in documentation for {Heimdallr::Model}.
 
-Note that Heimdallr is designed with three goals in mind, in the following order:
+Ideology
+--------
 
- * Preventing malicious modifications
- * Preventing information leaks
- * Being convenient to use
+Heimdallr aims to make security explicit, but nevertheless convenient. It does not allow one to call any
+implicit operations which may be used maliciously; instead, it forces you to explicitly call `#insecure`
+method which returns the underlying object. This single point of entry is easily recognizable with code.
 
-Due to the last one, not all methods will raise an exception on invalid access; some will silently drop the offending
-attribute or simply return `nil`. This is clearly described in the documentation, done intentionally and isn't
-going to change.
-
-REST interface
---------------
-
-Heimdallr also favors REST pattern; while its use is not mandated, a Heimdallr::Resource module is provided, which
-implements all standard REST actions with the extension of allowing to pass multiple models at once, and also enables
-one to introspect all writable fields with `new` and `edit` actions.
-
-The interface is described in documentation for {Heimdallr::Resource}.
+Heimdallr would raise exceptions in all cases of forbidden or potentially unsecure access except for attribute
+reading to allow for writing uncrufted code in templates (particularly [JBuilder](http://github.com/rails/jbuilder) ones).
 
 Compatibility
 -------------
 
 Ruby 1.8 and ActiveRecord versions prior to 3.0 are not supported.
\ No newline at end of file