readme update

README.md

@@ -7,7 +7,7 @@
 
 # Overview
 
-The Basilisp Kernel enables running Basilisp Clojure code directly within Jupyter notebooks, offering a seamless development experience for both Clojure and Python developers.
+The Basilisp Kernel enables running Basilisp Clojure code directly within Jupyter notebooks.
 
 ## Features
 
@@ -74,9 +74,71 @@ For additional configuration options, such as specifying a port with `:port` or
 
 ## Getting started with Basilisp Notebooks
 
+### Local Basilisp Files
+
+You can seamlessly write and use Basilisp `.lpy` files in the same directory as your Notebook. These files can be required in the Notebook just like standard Basilisp namespaces.
+
+For example, if you create a file named `dev.lpy` with the following content
+
+`./dev.lpy`
+```clojure
+(ns dev)
+
+(defn hello []
+  :hi)
+```
+
+You can load and use it in your Notebook as follows
+
+```Clojure
+[n]: (require 'dev)
+[n+1]: (dev/hello)
+:hi
+```
+
+#### Interactive development with nREPL
+
+You can start an nREPL server directly within a Notebook and connect to it using a Clojure-enabled editor.
+
+##### Start the nREPL server
+
+In a notebook cell:
+
+1. Load the nREPL server namespace:
+```clojure
+[n]: (require '[basilisp-kernel.nrepl-server :as nrepl-server])
+```
+2. Start the nREPL server at a random port
+```Clojure
+[n]: (def server (server-start))
+nREPL server started on port 9998 on host 127.0.0.1 - nrepl://127.0.0.1:9998
+#'user/server
+```
+
+##### Connect to the nREPL Server
+
+To connect your editor to the nREPL server create a `basilisp.edn` file in the same directory as your Notebook.
+
+Open your Clojure-enabled editor and use its nREPL connection commands. The server generated a `.nrepl-port file` in the directory, which helps the editor locate the port.
+
+Both [Emacs/CIDER](https://docs.cider.mx/cider/platforms/basilisp.html) and [VSCode/Calva](https://calva.io/basilisp/) offer explicit support for Basilisp.
+
+#### CIDER (Emacs)
+
+1. Run `M-x cider-connect-clj`.
+2. Select `localhost`.
+3. Select the `<project-dir>:<port number>` option.
+
+#### Calva (VSCode)
+1. Press `Ctrl-Alt-P` to open the Command Palette.
+2. Select `Calva: Connect to a Running REPL Server, in your project`>`basilisp`.
+3. The editor will automatically find the port using `.nrepl-port`.
+
+The Editor should now connect seamlessly to the nREPL server.
+
 ### Batteries Included Project: `basilex-notebook`
 
-The [Basilisp Example Notebook](https://github.com/ikappaki/basilex-notebook) repository, is an good resource for exploring Basilisp notebooks. It includes Jupyter, the Basilisp kernel, a skeleton Basilisp library, and a development notebook to help you get started.
+The [Basilisp Example Notebook](https://github.com/ikappaki/basilex-notebook) repository, is an excellent resource for exploring Basilisp notebooks. It includes Jupyter, the Basilisp kernel, a skeleton Basilisp library, and a development notebook to help you get started.
 
 #### Setup
 
@@ -96,9 +158,9 @@ $ poetry shell
 
 ### Basilisp Example Library Project: `basilex-basilib`
 
-Use the [Basilisp Example Library](https://github.com/ikappaki/basilex-basilib) repository to develop external Basilisp libraries for integration with your notebooks.
+The [Basilisp Example Library](https://github.com/ikappaki/basilex-basilib) repository provides a starting point for setting up an external Basilisp library that can be integrated with your notebooks.
 
-The following instructions assume you are running in a virtual environment where the Basilisp Notebooks will be opened from (e.g. such as in the `basiliex-notebook` clone above). This is indicated by the environment name prefix in your command prompt, such as `<venv>` in the examples below.
+The instructions below assume you are working in a virtual environment where the Basilisp Notebooks will be launched (e.g. the `basiliex-notebook` setup above). This is indicated by the environment name prefix in your command prompt, such as `<venv>` in the examples below.
 
 #### Setup