updated readme

1 files changed, 10 insertions, 2 deletions

diff --git a/README.md b/README.md
index 88f1cfe..c92df66 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,14 @@ node examples/helloworld.js # To try out the hello world (read the code for more
 
 Currently, `socket.js` provides `Socket` which has a few signals and functions (documented in the code, of course) which allow abstracted interfacing with YWOT. However, certain facilities available in the old version like queuing or fetch division were scrapped in favor of more direct limits due to the unmaintainability of the old style.
 
-`space.js` provides some dense spatial data management with `Space`, which is really good for specific dialogs and tests, but there may be some more work to be done to create a sparse storage device.
+`space.js` provides some dense spatial data management with `Space`, which is really good for specific dialogs and tests, but constructs like `tools/search.js` are more useful for storing world updates.
 
-`examples/helloworld.js` can get you started. Everything in the core API (`utils`, `socket.js`, `space.js`) should be pretty stable, but please don't hesitate to report a bug.
+`examples/helloworld.js` can get you started. Everything in the core API (`socket.js`, `space.js`) should be pretty stable, but please don't hesitate to report a bug.
+
+## Directory Structure
+
+Top-level scripts are part of the core API: `socket.js` and `space.js` are pretty portable and abstract a lot of the ugly parts of yourworldoftext (like 8x16 tiles).
+
+Then, `examples/` provides use cases for it. `helloworld.js` is a basic "Hello World" printer, `spam.js` spams one message without attempting to conserve bandwidth, and `jarvis.js` provides the most advanced example (responds to the word `jarvis` by overwriting it with `yes, my liege`, but is capable of much more complex behavior).
+
+`tools` and `utils` are similar to eachother in that they aren't very useful on their own, but are mostly distinct tools from the core API or user-facing scripts. The main difference is complexity: `tools` is reserved for complex (often persistent) utilities like `search` and `utils` for simple one-off functions like vector arithmetic, a min/max calculator for an array of coordinates, or helper tools for `space.comb`. They have been primarily motivated by attempts to discretize `examples`.