diff --git a/README.md b/README.md
index 87374bc..28bb36e 100644
--- a/README.md
+++ b/README.md
@@ -10,16 +10,13 @@ A Clojure interpreter running on [Janet](https://janet-lang.org). Jolt reads Clo
 git clone https://github.com/jolt-lang/jolt.git
 cd jolt
 git submodule update --init   # pulls vendor/sci
-jpm build                     # compiles build/jolt
+jpm build                     # builds build/jolt and build/jolt-deps
 ```
 
-Requires `jpm` and a recent Janet — developed and CI-tested against **1.41**. The
-futures and core.async layers rely on Janet's threaded `ev/` channels (`ev/thread`,
-`ev/thread-chan`), so an older Janet may not run the full suite.
-
-`jpm build` doesn't always detect source changes — run `jpm clean && jpm build`
-after editing `src/` to be sure `build/jolt` is current. The test suite (`jpm
-test`) runs against the source directly, so it never goes stale.
+Requires `jpm` and a recent Janet (CI-tested against 1.41). See
+[doc/building-and-deps.md](doc/building-and-deps.md) for build details, the
+`jpm clean` caveat, how namespaces are resolved (`JOLT_PATH`), and pulling
+Clojure libraries from a `deps.edn` with the `jolt-deps` tool.
 
 ## Run
 
diff --git a/doc/building-and-deps.md b/doc/building-and-deps.md
new file mode 100644
index 0000000..0c63634
--- /dev/null
+++ b/doc/building-and-deps.md
@@ -0,0 +1,97 @@
+# Building and dependencies
+
+How to build Jolt from source and how to pull Clojure libraries into a project.
+
+## Building
+
+```bash
+git clone https://github.com/jolt-lang/jolt.git
+cd jolt
+git submodule update --init   # vendor/sci (used by the SCI bootstrap tests)
+jpm build
+```
+
+This produces two executables under `build/`:
+
+- **`jolt`** — the runtime: REPL, file/expr runner, nREPL server.
+- **`jolt-deps`** — a separate tool that resolves a `deps.edn` (see below). It
+  sits beside the runtime the way `jpm` sits beside `janet`; the runtime itself
+  knows nothing about deps.edn.
+
+Needs `jpm` and a recent Janet — developed and CI-tested against **1.41**. The
+futures and core.async layers use Janet's threaded `ev/` channels (`ev/thread`,
+`ev/thread-chan`), so older Janets may not run the full suite.
+
+`jpm build` doesn't always notice source changes; run `jpm clean && jpm build`
+after editing `src/` to be sure the binaries are current. `jpm test` runs against
+the source directly, so it never goes stale.
+
+## How namespaces are found
+
+`(require ...)` resolves a namespace to a file by searching an ordered list of
+source roots — the stdlib first, then any extra roots — trying `<ns>.clj` then
+`<ns>.cljc` (dots become directories, dashes become underscores). Extra roots
+come from:
+
+- `JOLT_PATH` — a colon-separated list of directories (like a classpath), applied
+  at runtime;
+- the `:paths` option to `init` when embedding Jolt as a library.
+
+So you can point Jolt at a directory of Clojure source with no deps machinery at
+all:
+
+```bash
+JOLT_PATH=/path/to/lib/src build/jolt myfile.clj
+```
+
+## Dependencies via deps.edn
+
+`jolt-deps` reads a `deps.edn` in the current directory, fetches its
+dependencies, and runs `jolt` with the resolved source directories on
+`JOLT_PATH`.
+
+```bash
+jolt-deps path             # print the resolved roots (':'-joined)
+jolt-deps run FILE [args]  # resolve, then run `jolt FILE …`
+jolt-deps repl             # resolve, then start a REPL
+jolt-deps -e EXPR [args]   # resolve, then evaluate EXPR
+```
+
+`jolt-deps` launches the `jolt` binary it finds on `PATH` (override with
+`$JOLT_BIN`).
+
+Example `deps.edn`:
+
+```clojure
+{:paths ["src"]
+ :deps {weavejester/medley {:git/url "https://github.com/weavejester/medley"
+                            :git/tag "1.0.0"}
+        my/helpers          {:local/root "../helpers"}}}
+```
+
+```bash
+jolt-deps run -m myapp.main
+```
+
+### What's supported
+
+- **git deps** — `{:git/url … :git/tag …}` or `{:git/url … :git/sha …}` (use a
+  full SHA; `git fetch` can't resolve a short one). Transitive deps from each
+  dependency's own `deps.edn` are resolved too.
+- **local deps** — `{:local/root "../path"}`.
+- The project's own `:paths` (default `["src"]`) are included.
+
+Resolution reuses jpm's git fetch and cache (a dependency is cloned once into
+`jpm_tree/.cache` and reused). Resolved roots are cached on a hash of `deps.edn`,
+so an unchanged `deps.edn` doesn't re-fetch.
+
+### What's not
+
+- **No Maven.** `:mvn/version` deps are ignored — git and local only.
+- **Pure `clj`/`cljc` only.** A library that needs the JVM (Java interop, host
+  classes) or a `clojure.core` feature Jolt doesn't implement will fail to load
+  or fail at a call. Coverage is per-function: a namespace can load with most
+  functions working and a few not.
+
+See [`tools-deps.md`](tools-deps.md) for the design rationale and the road to
+compiling used dependency namespaces into the build.