docs: add details to readme

README.md

@@ -1,11 +1,52 @@
 # react-mutable-store
 
-Mutatable global stores for React, inspired by Vuex.
+Mutatable global stores for React, inspired by Vuex. Uses [immer](https://www.npmjs.com/package/immer) to provide immutable state objects with a mutable API.
 
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/w33ble/react-mutable-store/master/LICENSE)
-[![npm](https://img.shields.io/npm/v/react-mutable-store.svg)](https://www.npmjs.com/package/react-mutable-store)
 [![Project Status](https://img.shields.io/badge/status-experimental-orange.svg)](https://nodejs.org/api/documentation.html#documentation_stability_index)
 
+# Usage
+
+## `createStore(name, spec)`
+
+Used to create a store. You provide a name and a spec, which is very similar to the way you define a store in [Vuex](https://vuex.vuejs.org/guide/).
+
+The `name` value is used to access the store with the `useState` hook (see below).
+
+```js
+createStore('counter', {
+  state: {
+    count: 0
+  },
+  mutations: {
+    increment (state) {
+      state.count++
+    }
+  }
+});
+```
+
+## <StateProvider />
+
+A React component used to provide all of the created stores as context. You can wrap your entire app in this component to get access to all of the stores that exist. Alternatively, the component takes a `names` prop string that you can use to control which store providers are used. The string should be a comma-delimited list of stores by name.
+
+```xml
+<StateProvider>
+  <App />
+</StateProvider>
+```
+
+## useStore(name)
+
+A React [hook](https://reactjs.org/docs/hooks-reference.html) to access the store's state value, and methods to read and update it. The hook returns an object with the following properties:
+
+Property | Description
+-- | --
+`state` | The current state value of the store.
+`commit(name, ...args)` | Executes mutations, which synchronously change the state and update context, causing components that use the context to re-render.
+`dispatch(name, ...args)` | Fires actions, which perform async work and use mutations to update state. Returns a Promise that resolves when the action is complete.
+`get(name, ...args)` | Access to any defined getters in the spec. It's a way to define calculated values from the state.
+
 #### License
 
 MIT © [w33ble](https://github.com/w33ble)