From a4f5cdd1d0a6454d50c2295b3b7b8856ed02d6eb Mon Sep 17 00:00:00 2001
From: Philip Withnall <withnall@endlessm.com>
Date: Tue, 2 Apr 2019 17:48:32 +0100
Subject: [PATCH] docs: Expand README to be more informative

Include various architectural-level details of the project.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
---
 README.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 53 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 1a10d53..6afc56e 100644
--- a/README.md
+++ b/README.md
@@ -6,20 +6,66 @@ non-administrator accounts on a Linux system. Typically, when this is
 used, a non-administrator account will be for a child using the system; and the
 administrator accounts will be for the parents.
 
-It provides an accounts service vendor extension for storing an app filter to
+It provides an
+[accounts-service](https://gitlab.freedesktop.org/accountsservice/accountsservice)
+vendor extension for storing an app filter to
 restrict the child’s access to certain applications; and a simple library for
-accessing and applying the app filter.
+accessing and applying the app filter. This results in the policy being stored
+in `/var/lib/AccountsService/users/${user}`, which is a key file readable and
+writable only by the accounts-service daemon. Access to the data is mediated
+through accounts-service’s D-Bus interface, which libmalcontent is a client
+library for
 
 All the library APIs are currently unstable and are likely to change wildly.
 
+Two kinds of policy are currently supported:
+ * A filter specifying whether installed applications are allowed to be run;
+   this is typically set up to restrict access to a limited set of
+   already-installed applications — but it can be set up to only allow access
+   to a fixed list of applications and deny access to all others.
+   Applications which are not currently installed are not subject to this
+   filter.
+ * A set of mappings from [OARS categories](https://hughsie.github.io/oars/) to
+   the maximum ratings for those categories which are permissible for a user to
+   install apps with. For example, a mapping of `violence-realistic=mild` would
+   prevent any applications containing more than ‘mild’ violence from being
+   installed. Applications which are already installed are not subject to this
+   filter.
+
+Additional policies may be added in future.
+
+Example usage
+---
+
+malcontent ships a `malcontent-client` application which can be used to get and
+set parental controls policies for users.
+
+```
+$ # This sets the parental controls policy for user ‘philip’ to allow no \\
+    installation of apps with anything more than ‘none’ for realistic violence, \\
+    and to blacklist running the org.freedesktop.Bustle flatpak:
+$ malcontent-client set philip \\
+    violence-realistic=none \\
+    app/org.freedesktop.Bustle/x86_64/stable
+App filter for user 1000 set
+```
+
+With that policy in place, other applications which are aware of malcontent will
+apply the policy:
+
+```
+$ flatpak run org.freedesktop.Bustle
+error: Running app/org.freedesktop.Bustle/x86_64/stable is not allowed by the policy set by your administrator
+```
+
 Dependencies
 ------------
 
- • accounts-service
- • dbus-daemon
- • gio-2.0 ≥ 2.54
- • glib-2.0 ≥ 2.54
- • gobject-2.0 ≥ 2.54
+ * accounts-service
+ * dbus-daemon
+ * gio-2.0 ≥ 2.54
+ * glib-2.0 ≥ 2.54
+ * gobject-2.0 ≥ 2.54
 
 Licensing
 ---------