diff --git a/README.md b/README.md
index 5e5b965..d4f9e20 100644
--- a/README.md
+++ b/README.md
@@ -55,10 +55,10 @@
    $ git clone https://gerrit.googlesource.com/gerrit
    $ cd gerrit/plugins
    $ ln -s ../../owners/owners* .
-   $ cp -f owners-common/external_plugin_deps.bzl .
+   $ cp -f ../../owners/external_plugin_deps.bzl .
    $ cd ..
-   $ bazel build plugins/owners
-   $ bazel build plugins/owners-autoassign
+   $ bazel test plugins/owners-common:test
+   $ bazel build plugins/owners plugins/owners-autoassign
 ```
 
 NOTE: the owners-common folder is producing shared artifacts for the two plugins
diff --git a/config.md b/config.md
index 6478ab1..c8ba3fd 100644
--- a/config.md
+++ b/config.md
@@ -1,27 +1,45 @@
 ## Configuration
 
 Owner approval is determined based on OWNERS files located in the same
-repository. They are resolved against the state present in the existing master
-branch.
+repository on the target branch of the changes uploaded for review.
 
-The `OWNERS` files are represented by the following YAML structure:
+The `OWNERS` file has the following YAML structure:
 
 ```yaml
 inherited: true
 owners:
-- user-a@example.com
-- user-b@example.com
+  - some.email@example.com
+  - User Name
+matchers:
+  - suffix: .java
+      owners:
+        [...]
+  - regex: .*/README.*
+      owners:
+        [...]
+  - partial_regex: example
+      owners:
+        [...]
+  - exact: /path/to/file.txt
+        [...]
 ```
 
-_NOTE: Be aware to double check the emails values to be correctly registered as
-Gerrit users, invalid emails are just dropped._
+_NOTE: Be aware to double check that emails and full user names correspond to
+valid registered Gerrit users. When owner user full name or e-mail cannot be
+resolved, a corresponding WARN message is logged on Gerrit error_log and the
+user entry dropped._
 
-This translates to inheriting owner email address from any parent OWNER files
-and to allow user-a@example.com and user-b@example.com to approve the change.
+That translates to inheriting owner email address from any parent OWNER files
+and to define 'some.email@example.com' or 'User Name' users as the mandatory
+reviewers for all changes that include modification to those files.
 
-The plugin analyzes the latest patch set by looking at each patch and building
-an OWNERS hierarchy. It stops once it finds an OWNERS file that has “inherited”
-set to false (by default it’s true.)
+Additional owners can be specified for files selected by other matching
+conditions (matchers section). Matching can be done by file suffix, regex
+(partial or full) and exact string comparison.
+
+The plugin analyzes the latest patch set by looking at each file directory and
+building an OWNERS hierarchy. It stops once it finds an OWNERS file that has
+“inherited” set to false (by default it’s true.)
 
 For example, imagine the following tree:
 
@@ -39,12 +57,21 @@
 to true combine it with the owners listed in /OWNERS.
 
 If for each patch there is a reviewer who gave a Code-Review +2 then the plugin
-will not add any labels, otherwise it will add label('Owner-Approval', need(_)).
+will not add any labels, otherwise, it will add ```label('Code-Review from owners', need(_)).```
 
-## Example 1
+## Example 1 - OWNERS file without matchers and default Gerrit submit rules
 
-Here’s a sample rules.pl that uses this predicate to enable the submit rule if
-one of the owners has given a +2
+Given an OWNERS configuration of:
+
+```yaml
+inherited: true
+owners:
+  - John Doe
+  - Doug Smith
+```
+
+And sample rules.pl that uses this predicate to enable the submit rule if
+one of the owners has given a Code Review +2
 
 ```prolog
 submit_rule(S) :-
@@ -54,21 +81,31 @@
   gerrit_owners:add_owner_approval(Approvers, Ds, A),
   S =.. [submit | A].
 ```
-Let's examine how it works:
+
+Then Gerrit would evaluate the Prolog rule as follows:
 
 It first gets the current default on rule which gives ok() if no Code-Review -2
 and at least a Code-Review +2 is being provided.
 
 Then it accumulates in Approvers the list of users who had given Code-Review +2
-and then checks if this list contains at least one of the owners of this path.
+and then checks if this list contains either 'John Doe' or 'Doug Smith'.
 
-If Approvers list does not contain one of the owners then Owner-Approval need() is added thus
-making the change not submittable.
+If Approvers list does not include one of the owners, then Owner-Approval need()
+is added thus making the change not submittable.
 
-## Example 2
+## Example 2 - OWNERS file without matchers and no default Gerrit rules
 
-Here's a rule which makes submittable a change if at least one of the owners has
-given a +1 without taking into consideration any other label.
+Given an OWNERS configuration of:
+
+```yaml
+inherited: true
+owners:
+  - John Doe
+  - Doug Smith
+```
+
+And a rule which makes submittable a change if at least one of the owners has
+given a +1 without taking into consideration any other label:
 
 ```prolog
 submit_rule(S) :-
@@ -78,18 +115,24 @@
      S =.. [submit | A].
 ```
 
+Then Gerrit would make the change Submittable only if 'John Doe' or 'Doug Smith'
+have provided at least a Code-Review +1.
 
-## Example 3
+## Example 3 - OWNERS file without matchers and custom _Owner-Approves_ label
 
-We want to allow an administrator to specify a Code-Review +2 on a change when
-all the path owners give consent with a particular new label without requiring
-them to have +2 rights on the entire project.
+Sometimes to differentiate the _owners approval_ on a change from the code
+review on the entire project. The scenario could be for instance the sign-off of
+the project's build dependencies based on the Company roles-and-responsibilities
+matrix and governance process.
 
-To do that we need (1) to configure in the project a new label and give access
-to it to any registered user and then (2) re-use a small variation of the
-previous rule.
+In this case, we need to grant specific people with the _Owner-Approved_ label
+without necessarily having to give Code-Review +2 rights on the entire project.
 
-(1) Let's define in the project general, edit config a new label with values
+Amend the project.config as shown in (1) and add a new label; then give
+permissions to any registered user. Finally, define a small variant of the
+Prolog rules as shown in (2).
+
+(1) Example fo the project config changes with the new label with values
 (label name and values are arbitrary)
 
 ```
@@ -105,7 +148,7 @@
      label-Owner-Approved = -1..+1 group Registered Users
 ```
 
-(2) Use a slightly modified version of the previous rules.pl:
+(2) Define the project's rules.pl with an amended version of Example 1:
 
 ```prolog
 submit_rule(S) :-
@@ -115,3 +158,87 @@
   gerrit_owners:add_owner_approval(Approvers, Ds, A),
   S =.. [submit | A].
 ```
+
+Given now an OWNERS configuration of:
+
+```yaml
+inherited: true
+owners:
+  - John Doe
+  - Doug Smith
+```
+
+A change cannot be submitted until John Doe or Doug Smith add a label
+"Owner-Approved", independently from being able to provide any Code-Review.
+
+## Example 4 - Owners based on matchers
+
+Often the ownership comes from the developer's skills and competencies and
+cannot be purely defined by the project's directory structure.
+For instance, all the files ending with .sql should be owned and signed-off by
+the DBA while all the ones ending with .css by approved by the UX Team.
+
+Given an OWNERS configuration of:
+
+```yaml
+inherited: true
+matchers:
+  - suffix: .sql
+      owners:
+        - Mister Dba
+  - suffix: .css
+      owners:
+        - John Creative
+        - Matt Designer
+```
+
+And a rules.pl of:
+
+```prolog
+submit_rule(S) :-
+  gerrit:default_submit(L),
+  L =.. [submit | Sr ],
+  gerrit_owners:add_match_owner_approval(Sr,A),
+  S =.. [submit | A ].
+```
+
+Then for any change that contains files with .sql or .css extensions, besides
+to the default Gerrit submit rules, the extra constraints on the additional
+owners of the modified files will be added. The final submit is enabled if both
+Gerrit default rules are satisfied and all the owners of the .sql files
+(Mister Dba) and the .css files (either John Creative or Matt Designer) have
+provided their Code-Review +2 feedback.
+
+## Example 5 - Owners details on a per-file basis
+
+When using the owners with a series of matchers associated to different set of
+owners, it may not be trivial to understand exactly *why* change is not approved
+yet.
+
+We need to define one extra submit rule to scan the entire list of files in the
+change and their associated owners and cross-check with the existing Code-Review
+feedback received.
+
+Given the same OWNERS and rules.pl configuration of Example 4 with the following
+extra rule:
+
+```prolog
+submit_rule(submit(W)) :-
+  gerrit_owners:findall_match_file_user(W).
+```
+
+For every change that would include any .sql or .css file (e.g. my-update.sql
+and styles.css) Gerrit will display as additional description on the "need" code
+review labels section of the change screen:
+
+```
+Code-Review from owners
+Mister Dba owns my-update.sql
+John Creative, Matt Designer own styles.css
+```
+
+As soon as the owners reviews are provided, the corresponding entry will be
+removed from the "need" section of the change.
+
+In this way, it is always clear which owner needs to provide their feedback on
+which file of the change.
\ No newline at end of file