1 files changed, 58 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b11d47
--- /dev/null
+++ b/README.md
@@ -0,0 +1,58 @@
+* Scorpion
+
+** What is it?
+
+Scorpion is a simple dependency injection framework for
+Javascript. It provides the ability to both construct and destroy
+dependencies, as well as injecting a wide variety of things
+(extensible via "plugins").
+
+** How do I use it?
+
+Just include `scorpion.js` or `scorpion.min.js` in your page to get
+started.
+
+Then create an injector with some plugins (this one will use the
+standard "value plugin", which behaves similarly to other dependency
+injection frameworks):
+
+    :::javascript
+    var injector = new Scorpion([new Scorpion.ValuePlugin()]);
+    injector
+        .register("DepA", function() {
+            return "Dependency A";
+        })
+        .register("DepB", ["DepA", function(DepA) {
+            return ["Dependency B", DepA];
+        }]);
+
+Now we can create our dependencies:
+
+    :::javascript
+    // we can just get a value (in a promise)
+    injector.get("DepB").then(function(value) {
+        console.log("Value returned:", value);
+    }, console.error.bind(console));
+
+    // or we can invoke a function (with the result returned in a promise)
+    injector.invoke(["DepA", "DepB", function(DepA, DepB) {
+        return {A: DepA, B: DepB};
+    }]).then(function(value) {
+        console.log("Value returned:", value);
+    }, console.error.bind(console));
+
+Dependencies are constructed asynchronously, which lets us also create
+different types of plugins, like the HTTPPlugin which comes with
+Scorpion:
+
+    :::javascript
+    var injector = new Scorpion([
+        Scorpion.prefixPlugin("http!", new Scorpion.HTTPPlugin()),
+        new Scorpion.ValuePlugin()
+    ]);
+    injector.register("LoginDOM", ["$", "http!/partials/login.html", function($, login) [
+        return $(login);
+    }]);
+    injector.get("LoginDOM").then(function(value) {
+        console.log("dom:", value);
+    });