diff --git a/cmd/welcome/README.md b/cmd/welcome/README.md
new file mode 100644
index 0000000..54c0c58
--- /dev/null
+++ b/cmd/welcome/README.md
@@ -0,0 +1,47 @@
+# welcome command
+
+this command is used to exchange a town invite token for a user account. it is
+responsible for:
+
+1. accepting and validating an invite token generated by the `review` command
+2. accepting and validating a new user's username choice (ie enforcing rules and checking for dupes)
+3. accepting and validating a user's email for use in account recovery (defaulting to an email embedded in the invite token)
+4. accepting and validating a display name
+5. asking what shell they'd like
+6. accepting and validating a user's public ssh key
+
+upon receipt of these things a user account is created. if it fails, the user
+is told about the failure and told to email root@tilde.town for guidance; us
+admins get a local mail about the problem.
+
+upon successful creation, `welcome` prints a message on STDOUT suggesting how to log in then quits.
+
+It is risky to let `welcome` create users but no riskier at a high level than the Django admin we had. I can re-use the sudoers trick I did there for the `welcome` user.
+
+## an invite token
+
+an invite token consists of two pieces that are then base64 encoded. the first piece is a random string of 30 characters (alphanumeric and symbols except space) and the second is an email address the invite was sent to; they are separated by a space.
+
+## sudoers config
+
+something like:
+
+```
+welcome ALL=(ALL)NOPASSWD:/usr/sbin/adduser,/usr/sbin/usermod,/bin/mkdir,/town/bin/generate_welcome_present.sh
+```
+
+though I will likely move welcome_present generation inline to `welcome` itself.
+
+## user creation flow
+
+once we accept what we need from the user accepting an invite, the flow looks like:
+
+1. create user account
+  a. run `adduser`, set shell and displayname
+  b. add user to town group
+2. write authorized keys
+  a. create `~/.ssh`
+  b. write `~/.ssh/authorized_keys2` and put their key in there
+  c. write blank `~/.ssh/authorized_keys` with note about adding custom keys
+3. generate welcome gift
+4. alert hooks (more of a future idea; but it would be nice to have a "WELCOME NEW USER!" in the mailing list / IRC / etc)