flesh out the README some

README.md

@@ -1 +1,81 @@
-This is a distributed, collaborative bug tracker, backed by git.
+Entomologist is a distributed, collaborative, offline-first issue tracker,
+backed by git.
+
+
+# Quick start
+
+Entomologist provides a single executable called `ent` which performs
+all interaction with the issues database.  `ent --help` provides terse
+usage info.
+
+No initialization is needed, just start using `ent` inside your git repo:
+
+```
+$ git clone git@server:my-repo.git
+$ cd my-repo
+$ ent list
+# no issues shown, unless my-repo contained some already
+```
+
+Create an issue:
+```
+$ ent new
+# Starts your $EDITOR.  Type in the issue description, "git-commit
+# style" with a title line, optionally followed by an empty line and
+# free form text.
+```
+
+List issues with `ent list`.  Optionally takes a filter argument that
+controls which issues are shown, see `ent list --help` for details.
+For example, to show only new and backlog issues assigned to me or
+unassigned, run `ent list state=new,backlog:assignee=$(whoami),`.
+
+Show all details of an issue with `ent show`.
+
+Modify the state of an issue using `ent state`.  Supported states are New,
+Backlog, InProgress, Done, and WontDo.
+
+Assign an issue to a person using `ent assign`.  The person is just
+a free-form text field for now.  Make it a name, or an email address,
+or whatever you want.
+
+Add a comment on an issue with `ent comment`.
+
+Edit an issue or a comment with `ent edit`.
+
+Add or remove tags on an issue using `ent tag`.
+
+
+# Synchronization
+
+Synchronize your local issue database with the server using `ent sync`.
+This will:
+
+1. Fetch the remote issue database branch into your local repo.
+
+2. Show the list of local changes not yet on the remote.
+
+3. Show the list of remote changes not yet incorporated into the local
+   branch.
+
+4. Merge the branches.
+
+5. Push the result back to the remote.
+
+Step 4 might fail if (for example) both sides edited the same issue in
+a way that git can't merge automatically.  In this case, check out the
+`entomologist-data` branch, merge by hand and resolve the conflicts,
+and run `ent sync` again.
+
+
+# Git storage
+
+Issues are stored in a normal orphan branch in a git repo, next to but
+independent of whatever else is stored in the repo.  The default branch
+name is `entomologist-data`.
+
+Anyone who has a clone of the repo has the complete issue database.
+
+Anyone who has write-access to the repo can modify the issue database.
+The issue database branch can be modified by pull request, same as any
+other branch.