add to the README.md

1 files changed, 45 insertions, 0 deletions

diff --git a/README.md b/README.md
index f97c6b0..2fba282 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,18 @@
+This repository contains 4 things:
+ 1. Information about Parabola contributors
+ 2. `Makefile` and `bin/`: tools for working with that information
+ 3. `misc/git-shell-commands`: for use with git-shell
+ 4. `misc/git-hooks`: git hooks
+
+Honestly, the latter two probably don't belong, but they've always
+been in this repository, so I didn't want to just delete them.  If you
+remove git-shell-hooks in the future, be warned that
+/srv/git/git-shell-commands is currently a symlink to there; you'll
+want to change that.
+
+Adding users
+============
+
 Users ("hackers") are added by creating a file in the `users/`
 directory.  The file should be named `users/${UID}.yml` where UID is
 the numeric POSIX user ID for that user.  See
@@ -13,3 +28,33 @@ Images in `dev-imgs/`:
 
 The files in `bin/` are configured with `cfg_*` variables at the top
 of each file.
+
+Using the tools (make)
+======================
+
+There are 2 `make` targets of interest: `pacman-keyring` and
+`postfix-virtual-map`.  `make [all]` makes both of them.  The output
+of each goes in `output/{pacman-keyring,postfix-virtual-map}`
+respectively.
+
+`pacman-keyring` makes the Pacman keyring that we package up as the
+`parabola-keyring` package.
+
+`postfix-virual-map` makes a map for postfix email aliases we provide
+to our developers.
+
+Using the tools (scripts)
+=========================
+
+Most of the scripts assume that the current directory is the root of
+this repository.
+
+The most important 3 scripts are:
+
+ - `meta-check`: sanity-check the user data
+ - `meta-normalize-stdio`: normalize a user YAML file
+ - `ssh-list-authorized-keys`: configure sshd to use this for
+   AuthorizedKeysCommand to have it get SSH keys directly from the
+   user data here
+
+The others are all used by `make`.