--- a/pyforge/docs/guides/permissions.rst
+++ b/pyforge/docs/guides/permissions.rst
@@ -4,9 +4,35 @@
User/Group model
---------------------------------------------------------------------
+In the pyforge system `users` can be assigned to various `groups` or
+roles on a per-project basis.
+
+Users can be members of many groups, and both `users` and `groups` can
+be assigned a list of `permissions` like `"add_subproject"`,
+`"commit_to_master"`or "admin_users". Plugins can define their own
+set of permissions, for their artifacts. Plugins are encouraged to
+prefix their permissionswith the plugin name so for a pluging called
+"tracker" a good permissin name would be `"tracker_edit_ticket"`
+
Artifacts and ACL's
---------------------------------------------------------------------
+
+There are also likely to be some permissions that you want to assign
+to particular people or roles for a particular `Artifiact` such as
+a particular bug in the ticket tracker. PyForge supports this via
+an acl field on every `Artifact` instance.
+
+Permission calculation
+--------------------------------------------------------------------
+
+Projects and subprojects can define user `groups`, but for any particular
+subproject the groups the user belongs too is additive. This follows
+the basic principle that sub-project permissions and artifiact permissions
+can *allow* additional access, but can't *restrict* it beyond
+what permissions are allowed by a higher level project.
The magic of **predicates**
---------------------------------------------------------------------
+
+