diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c6fd80d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# BlenderPackage, the Blender Package Manager (wip)
+
+This is work-in-progress documentation for the work-in-progress package manager
+(the name is also a work-in-progress) As such, everything here is subject to
+change.
+
+# Package
+
+A _package_ consists of an archive containing files to be installed.
+
+Note:  
+I think it would be good to always store `bl_info` metadata with the package,
+but how best to do this while being compatible with existing addons and future
+non-addons remains an open question (perhaps we can always include an
+`__init__.py` even in non-addon packages?)
+
+
+# Repository
+
+A _repository_ consists of a directory containing a "repo.json" file.  This
+repo.json file contains metadata describing each package (`bl_info`) and where
+it may be retrieved from. 
+
+A repo.json file may currently be generated from a directory of addons by
+running `blenderpack.py <path/to/addon/dir>`.
+
+
+# Client
+
+Clients "use" a repository by including its repo.json in packages listed in 
+Clients can be configured to use multiple repositories at once.
+
+In addition, the client maintains it's own "local repository", which is a
+repo.json containing installed packages.
+
+Clients can take the following actions:
+
+## Install
+
+_Installing_ means downloading a single package, adding it to the local
+repository, and extracting/copying the package's file(s) to their
+destination(s).
+
+## Uninstall
+
+_Uninstalling_ means deleting a single package's files, then removing it from
+the local repository.
+
+Note:  
+If some packages store user-created data (e.g. preferences), we may want to
+preserve that somehow.
+
+## Update
+
+_Updating_ means looking for newer addons with the same names as installed
+addons **from the same repository**.
+
+## Fetch
+
+_Fetching_ means checking for modifications to the `repo.json`s of the enabled
+repositories. If there are modifications, then download them.
+This will be done automatically before an _Update_.
+