diff --git a/README.mkd b/README.mkd
index 0f9e9a5..e659d5e 100644
--- a/README.mkd
+++ b/README.mkd
@@ -11,6 +11,7 @@ In this document:
* quick install
* what
+ * documentation
* why
* main features
* security
@@ -69,8 +70,15 @@ summary":
* several other neat features described below and elsewhere in the
[doc/][docs] directory.
-Gitolite comes with a **huge** amount of documentation. If you're absolutely
-new, the suggested reading order is this:
+
+
+#### documentation
+
+Gitolite comes with a **huge** amount of documentation. Almost all of it is
+for the *administrator* of a gitolite server. If you're a *user*, you only
+need [this][user].
+
+Otherwise, the suggested reading order is this:
* the README (this document) for a quick intro
* the [INSTALL][install] document
@@ -210,3 +218,4 @@ Gitolite is released under GPL v2. See COPYING for details.
[who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html
[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
[docs]: http://sitaramc.github.com/gitolite
+[user]: http://sitaramc.github.com/gitolite/doc/user-manual.html
diff --git a/contrib/adc/README.mkd b/contrib/adc/README.mkd
index 6061d2e..9d40555 100644
--- a/contrib/adc/README.mkd
+++ b/contrib/adc/README.mkd
@@ -5,7 +5,8 @@
----
**able**: enable/disable push access temporarily (such as for taking backups
-or other admin chores); details [here][able].
+or other admin chores); details [here][able]. This ADC is meant only for
+admins.
[able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily
diff --git a/doc/user-manual.mkd b/doc/user-manual.mkd
new file mode 100644
index 0000000..00a215d
--- /dev/null
+++ b/doc/user-manual.mkd
@@ -0,0 +1,160 @@
+# what users (not admins) need to know about gitolite
+
+...written for the one guy in the world no one will think of as "just a normal
+user" ;-)
+
+This document has some text, and a lot of links. Most of this info *is*
+available in the rest of the documentation, but it's scattered and sparse.
+Collecting all of it, or at least links to it, in one place sounds useful.
+
+In this document:
+
+ * accessing gitolite
+ * always available commands
+ * digression: two kinds of repos
+ * commands only available with "wildrepos" on
+ * listing repos you created
+ * set/get additional permissions for repos you created
+ * adding a description to repos you created
+ * "site-local" commands
+
+----
+
+
+
+### accessing gitolite
+
+The most common setup is based on ssh, where your admin asks you to send him
+your public key, and uses that to setup your access.
+
+Your actual access is either a git command (like `git clone
+git@server:reponame`, and we won't be discussing these any more in this
+document), or an ssh command (like `ssh git@server info`).
+
+Note that you do *not* get a shell on the server -- the whole point of
+gitolite is to prevent that!
+
+
+
+### always available commands
+
+The only command that is *always* available to every user is the [`info`
+command][info], which tells you what version of gitolite and git are on the
+server, and what repositories you have access to. The list of repos is very
+useful if you have doubts about the spelling of some new repo that you know
+was setup.
+
+[info]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_info_command
+
+
+
+### digression: two kinds of repos
+
+Gitolite has two kinds of repos. Normal repos are specified by their full
+names in the config file. "Wildcard" repos are specified by a regex in the
+config file. If you look at the documentation on the [`info` command][info]
+you will see there are a couple of lines that look like regex patterns,
+against which you see an additional "C" permission not available with the
+others.
+
+This means you are allowed to create brand new repos whose names fit that
+pattern. When you create such a repo, your "ownership" of it (as far as
+gitolite is concerned) is noted by creating a 1-line file called "gl-creater"
+(note spelling!) in the repo directory, with just your gitolite userid in it.
+
+This happens automatically. But for repos that were migrated into gitolite
+and whose names fit a pattern, the admin has to manually create those files,
+otherwise you won't be able to execute certain commands that you otherwise
+might have access to.
+
+"Wildrepos" is an optional feature of gitolite that the admin has to "turn
+on".
+
+
+
+### commands only available with "wildrepos" on
+
+
+
+#### listing repos you created
+
+The info command will not show you your own wildcard repos. To get that list,
+try the [`expand` command][expand].
+
+[expand]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_expand_command
+
+
+
+#### set/get additional permissions for repos you created
+
+The gitolite config may have several permissions lines for your repo, like so:
+
+ repo pub/CREATOR/..*
+ RW+ = CREATOR
+ RW = user1 user2
+ R = user3
+
+If that's all it had, you really can't do much. Any changes to access must be
+done by the administrator. (Note that "CREATOR" is a reserved word that gets
+expanded to your userid in some way, so the admin can literally add just the
+first two lines, and *every* authenticated user now has his own personal repo
+namespace, starting with `pub//`).
+
+To give some flexibility to users, the admin could add rules like this:
+
+ RW = WRITERS
+ R = READERS
+
+(he could also add other roles but then he needs to read the documentation).
+
+Once he does this, you can then use the [`setperms` command][setperms] to set
+permissions for other users by specifying which users are in the list of
+"READERS", and which in "WRITERS". That same section also talks about the
+`getperms` command as well.
+
+If you think of READERS and WRITERS as "roles", it will help. You can't
+change what access a role has, but you *can* say which users have that role.
+
+**Note**: there isn't a way for you to see the actual rule set unless you're
+given read access to the special 'gitolite-admin' repo. Sorry. The idea is
+that your admin will tell you what "roles" he added into rules for your repos,
+and what permissions those roles have.
+
+[setperms]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html#_handing_out_rights_to_wildcard_matched_repos
+
+
+
+#### adding a description to repos you created
+
+The `setdesc` and `getdesc` commands work similarly to the `setperms` and
+`getperms` commands. You just say
+
+ echo "some description here" | ssh git@server setdesc pub//
+
+and if you want to check you just say
+
+ ssh git@server getdesc pub//
+
+
+
+### "site-local" commands
+
+The main purpose of gitolite is to prevent you from getting a shell. But
+there are commands that you often need to run on the server (i.e., cannot be
+done by pushing something to a repo).
+
+To enable this, gitolite allows the admin to setup scripts in a special
+directory that users can then run. Gitolite comes with a set of working
+scripts (in "contrib/adc") that your admin may install, or may use as a
+starting point for his own, if he chooses.
+
+Think of these commands as equivalent to those in `COMMAND_DIR` in `man
+git-shell`.
+
+Most of the shipped ADCs are briefly described [here][ADCs], with links to
+more details if available. However, **please understand** that these commands
+may not be available, or their behaviour may have been changed to suit local
+requirements, and of course new ones may have been added. You'll have to ask
+your local admin for answers, not me!
+
+[ADCs]: http://sitaramc.github.com/gitolite/contrib/adc/README.html