From 76203fafaba13b6d88bbcf8abe1641470a763902 Mon Sep 17 00:00:00 2001
From: Julien Vincent <m@julienvincent.io>
Date: Mon, 9 Sep 2024 00:50:39 +0100
Subject: [PATCH] Readme updates

---
 README.md | 79 ++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 58 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 02b8201..b44df65 100644
--- a/README.md
+++ b/README.md
@@ -23,27 +23,26 @@ providing a better understanding of deps.edn projects.
 This project was built with a focus on improving the experience of working in Clojure monorepos but works great in
 standalone projects too.
 
-## Overview
+## Index
 
-- **Workspace features**: Discovers packages and understands relationships between dependencies
-- **Aliases**: Allows dynamically interacting with workspace package aliases in a 'Clojure native' way
-- **Build Tools**: Exposes a suite of libs intended to be used from tools.build programs to build monorepos
-- **Command Runner**: Allows executing Clojure or external commands in workspace packages
-- **Local Deps Overrides**: Allow overriding properties and `deps.edn` config during local development
-
-## Documentation
-
-+ **[kmono-core](https://cljdoc.org/d/com.kepler16/kmono-core)** - The core suite of API's for working with kmono
-packages.
-+ **[kmono-build](https://cljdoc.org/d/com.kepler16/kmono-build)** - A companion lib to `tools.build` which contains
-API's for building jar artifacts or simplifying the use of `tools.build` in a kmono workspace.
-+ **[kmono-version](https://cljdoc.org/d/com.kepler16/kmono-version)** - A set of API's for versioning kmono packages.
++ **[Features](#features)**
++ **[Installation](#installation)**
++ **[Documentation](#Documentation)**
+  + **[Kmono CLI](#kmono-cli)**
+  + **[Example Project](#example-project)**
++ **[Clojure-lsp / Editor Integration](#clojure-lsp-%2F-editor-integration)**
 
-## Example project
+## Features
 
-Take a look at **[the example project](./examples/workspace/)** to get a better idea of the type of project
-structures kmono is built to support and for references on how to correctly use the kmono API's and integrate it into
-your own project.
+- **Workspace features**: Discovers packages and understands relationships between dependencies
+- **Aliases**: Allows working with packages aliases defined in `deps.edn` in a 'Clojure native' way without having to
+pull all alias definitions into root `deps.edn`
+- **Build Tools**: Exposes a suite of libs intended to be used from `tools.build` programs to build and release
+monorepos
+- **Command Runner**: Allows executing Clojure and/or external commands in workspace packages
+- **Local Deps Overrides**: Allow overriding kmono config and `deps.edn` dependencies during local development. Useful
+for providing local paths to in-development libs without committing.
+- **Editor/Clojure-lsp**: Improves developer/editing experience by augmenting the classpath used by clojure-lsp
 
 ## Installation
 
@@ -64,7 +63,45 @@ bash < <(curl -s https://raw.githubusercontent.com/kepler16/kmono/master/install
 Or alternatively binaries for various platforms can be pulled directly from the
 [Releases](https://github.com/kepler16/kmono/releases) page.
 
-### Editor Integration / ClojureLSP
+## Documentation
+
++ **[kmono-core](https://cljdoc.org/d/com.kepler16/kmono-core)** - The core suite of API's for working with kmono
+packages.
++ **[kmono-build](https://cljdoc.org/d/com.kepler16/kmono-build)** - A companion lib to `tools.build` which contains
+API's for building jar artifacts or simplifying the use of `tools.build` in a kmono workspace.
++ **[kmono-version](https://cljdoc.org/d/com.kepler16/kmono-version)** - A set of API's for versioning kmono packages.
+
+#### Kmono CLI
+
+```bash
+❯ kmono
+NAME:
+ kmono - A cli for managing clojure (mono)repos
+
+USAGE:
+ kmono [global-options] command [command options] [arguments...]
+
+VERSION:
+ 4.2.0
+
+COMMANDS:
+   cp                   Produce a classpath string from a clojure project
+   repl                 Start a clojure repl
+   exec                 Run a command in each package
+   run                  Run an alias in project packages
+
+GLOBAL OPTIONS:
+   -d, --dir S  Run commands as if in this directory
+   -?, --help
+```
+
+#### Example project
+
+Take a look at **[the example project](./examples/workspace/)** to get a better idea of the type of project
+structures kmono is built to support and for references on how to correctly use the kmono API's and integrate it into
+your own project.
+
+## Clojure-lsp / Editor Integration
 
 One of the things that kmono enables is integration into your editor by acting as a drop-in replacement for `clojure
 -Spath` which is used by default by clojure-lsp.
@@ -72,7 +109,7 @@ One of the things that kmono enables is integration into your editor by acting a
 If we instead use `kmono cp` to generate the classpath then your clojure-lsp server will be able to provide better
 analysis.
 
-##### Project local Clojure-LSP config
+#### Project local Clojure-LSP config
 
 ```clojure
 ;; .lsp/config.edn
@@ -80,7 +117,7 @@ analysis.
                   :classpath-cmd ["kmono" "cp"]}]}
 ```
 
-##### Neovim / nvim-lspconfig
+#### Neovim / nvim-lspconfig
 
 ```lua
 local lspconfig = require('lspconfig')