Improve project documentation

Author: julienvincent

README.md

@@ -23,19 +23,23 @@ This is the overall structure of the project:
 
 In this structure we have two packages - `a` and `b` where package `b` depends on package `a`.
 
-This project demonstrates a workflow where: 
+> [!NOTE]
+>
+> Run `kmono query` to inspect the workspace package graph and see how packages relate
 
-1) Packages are built and released when PR's are merged to master.
-2) Only packages that have changed since their previous version are build and released.
-3) The project uses convensional-commits and package versions are derived from commits.
+This project demonstrates a workflow where:
+
+1. Packages are built and released when PR's are merged to master.
+2. Only packages that have changed since their previous version are build and released.
+3. The project uses conventional-commits and package versions are derived from commits.
 
 The above requirements aren't needed to make use of kmono - this just serves to demonstrate a particular workflow and
 how you might use kmono to achieve it.
 
 ## Building/Releasing
 
 The build and release workflow described above is entirely encapsulated in the `build.clj` file using `tools.build` and
-kmono-* APIs.
+kmono-\* APIs.
 
 Packages can be built by running:
 
@@ -49,8 +53,8 @@ And the built packages can then be released by running
 clojure -T:build release
 ```
 
-For both building and releasing you can add the `:skip-unchanged true` argument to build and release only packages that
-have changed. The idea being that you would pass this by default during CI.
+For both building and releasing you can add the `:skip-unchanged true` argument to only build and release packages that
+have changed since their last release. The idea being that you would pass this by default during CI.
 
 ```bash
 clojure -T:build build :skip-unchanged true
@@ -61,16 +65,16 @@ development to build all packages.
 
 ---
 
-Take a look at the [example GitHub workflow file](./.github/workflows/release.yaml) for how you might set up your CI
+Have a look at the [example GitHub workflow file](./.github/workflows/release.yaml) for how you might set up your CI
 pipeline for release.
 
 ## Testing
 
 To run the tests for each package you can run the command
 
 ```bash
+# Run `clojure -M` in each package (indicated by the `*`) that has a `:test` alias.
 kmono run -M ':*/test'
 ```
 
-This means run `clojure -M` in each package (indicated by the `*`) that has a `:test` alias. Each respective packages'
-`:test` alias will then be appended to the command when it is run, like so: `clojure -M:test`.
+Each respective packages' `:test` alias will then be appended to the command when it is run, like so: `clojure -M:test`.

examples/workspace/README.md

@@ -68,8 +68,8 @@
           :repository "clojars"})
 
         ;; Create tags after successfully releasing the package.
-        ;;
+        ;; 
         ;; This will require calling `git push --tags` separately but you could
-        ;; just as easilly call it here too.
+        ;; just as easily call it here too.
         (git.tags/create-tags
          project-root {:tags [(kmono.version/create-package-version-tag pkg)]})))))

examples/workspace/build.clj

@@ -0,0 +1,39 @@
+Run Clojure CLI commands with workspace packages and aliases automatically integrated.
+
+Drop-in replacement for the standard `clojure` CLI enhanced with workspace awareness.
+Automatically includes workspace packages and their aliases, allowing you to work with
+your entire monorepo as a single project.
+
+Examples:
+
+```bash
+# Start a REPL with workspace packages available
+kmono clojure
+
+# Run with specific aliases
+kmono clojure -A :dev
+
+# Use package aliases (e.g., all :test aliases from packages)
+kmono clojure -P ':*/test' -M :test
+
+# Run a main function with workspace awareness
+kmono clojure -M :my-main-alias
+
+# Execute a tool
+kmono clojure -T :build
+
+# Run with exec
+kmono clojure -X :my-exec-alias
+
+# Pass through standard clojure arguments
+kmono clojure -M:test -- -m kaocha.runner
+
+# Combine workspace and package aliases
+kmono clojure -A :dev -P ':*/dev,:*/test'
+```
+
+The command automatically creates aliases for workspace packages and lifts
+package-specific aliases to the root level with namespaced names.
+
+Use the global `-v` flag to see the actual `clojure` command being executed for debugging
+classpath issues.

packages/kmono-cli/resources/k16/kmono/docs/clojure.md

@@ -0,0 +1,30 @@
+Generate a classpath string from a Clojure project, augmented with workspace package
+information and aliases.
+
+Similar to `clojure -Spath` but enhanced with kmono's workspace awareness. Particularly
+useful for editor integration (clojure-lsp), custom tooling, and debugging classpath
+issues.
+
+Examples:
+
+```bash
+# Basic classpath generation
+kmono cp
+
+# Include specific root aliases
+kmono cp -A :dev,:test
+
+# Include package aliases (e.g., all :test aliases from workspace packages)
+kmono cp -P ':*/test'
+
+# Combine root and package aliases
+kmono cp -A :dev -P ':*/test,:*/dev'
+```
+
+For clojure-lsp integration, use as a drop-in replacement for `clojure -Spath`:
+
+```clojure
+;; .lsp/config.edn
+{:project-specs [{:project-path "deps.edn"
+                  :classpath-cmd ["kmono" "cp"]}]}
+```

packages/kmono-cli/resources/k16/kmono/docs/cp.md

@@ -0,0 +1,36 @@
+Execute external commands (non-Clojure) across multiple workspace packages.
+
+Runs external commands in each workspace package directory, useful for shell scripts,
+build tools, tests, or any external commands across your monorepo.
+
+Examples:
+
+```bash
+# Run npm test in all packages
+kmono exec npm test
+
+# Run a shell script in all packages
+kmono exec ./scripts/build.sh
+
+# Run tests only in changed packages
+kmono exec --changed npm test
+
+# Run commands in packages that changed since main branch
+kmono exec --changed-since origin/main pytest
+
+# Run in specific packages only
+kmono exec -F :com.example/api,:com.example/web npm run build
+
+# Run with limited concurrency
+kmono exec -c 2 ./slow-command.sh
+
+# Run commands without dependency ordering (faster but potentially unsafe)
+kmono exec --run-in-order=false npm install
+```
+
+Each command is executed with the package directory as the working directory. If any
+command fails, `kmono exec` continues running in other packages and reports failures at
+the end.
+
+By default, commands run in dependency order to respect package relationships, but this
+can be disabled for independent operations like tests or linting.

packages/kmono-cli/resources/k16/kmono/docs/exec.md

@@ -0,0 +1,33 @@
+Query and inspect information about the workspace package graph in various formats.
+
+Provides information about workspace packages and their relationships. Outputs package
+metadata, version information, change tracking, and dependency relationships in JSON or
+EDN format.
+
+Examples:
+
+```bash
+# List all packages in JSON format
+kmono query
+
+# List all packages in EDN format
+kmono query -o edn
+
+# Query specific packages
+kmono query -F :com.example/api,:com.example/web
+
+# Include version information from git tags
+kmono query --with-versions
+
+# Only show packages that have changed since last version
+kmono query --with-changes --filter-unchanged
+
+# Show packages changed since main branch
+kmono query --with-changes-since origin/main --filter-unchanged
+
+# Only include specific fields
+kmono query --include-keys name,version,path
+```
+
+Useful for debugging workspace configuration, building custom tooling, understanding
+package relationships, and identifying changed packages for CI/CD pipelines.

packages/kmono-cli/resources/k16/kmono/docs/query.md

@@ -0,0 +1,34 @@
+Start a Clojure REPL with workspace packages and aliases automatically configured.
+
+Enhanced REPL with workspace awareness that automatically includes workspace packages in
+the classpath and applies configured aliases from both the root project and workspace
+packages.
+
+Configuration example:
+
+```clojure
+;; deps.local.edn
+{:kmono/workspace {;; Always include these aliases when running `kmono repl`
+                   :repl-aliases [:nrepl :cider]
+                   :aliases [:dev]
+                   :package-aliases [:*/dev]}}
+```
+
+Examples:
+
+```bash
+# Start basic REPL with workspace packages
+kmono repl
+
+# Start REPL with additional root aliases
+kmono repl -A :dev,:test
+
+# Start REPL with specific package aliases
+kmono repl -P ':*/test,:a/dev'
+
+# Start REPL with both root and package aliases
+kmono repl -A :cider -P ':*/dev'
+```
+
+Use `deps.local.edn` for personal REPL preferences without affecting the shared project
+configuration.

packages/kmono-cli/resources/k16/kmono/docs/repl.md

@@ -0,0 +1,44 @@
+Execute Clojure commands with aliases across workspace packages that contain the specified
+aliases.
+
+Automatically filters packages based on whether they have the requested alias defined in
+their `deps.edn` file. Useful for running tests, builds, or other Clojure-based tasks
+across multiple packages.
+
+Examples:
+
+```bash
+# Run tests in all packages that have a :test alias
+#
+# This will result in `clojure -M:test` being run in all workspace packages containing
+# a `:test` alias.
+kmono run -M :test
+
+# Run build tools in packages with :build alias
+kmono run -T :build
+
+# Run exec function in packages with :my-exec alias
+kmono run -X :my-exec :fn some-fn
+
+# Run only in changed packages
+kmono run --changed -M :test
+
+# Run in packages changed since main branch
+kmono run --changed-since origin/main -M :test
+
+# Run with package filtering
+kmono run -F :com.example/api -M :test
+
+# Run with limited concurrency
+kmono run -c 2 -M :test
+
+# Pass additional arguments to the Clojure command
+kmono run -M :test --focus my-test-ns
+```
+
+Only executes in packages that actually contain the specified alias, automatically
+skipping packages without the alias. Each command runs with the package directory as the
+working directory.
+
+By default, commands run in dependency order to ensure proper build sequences, but this
+can be disabled for independent operations.

packages/kmono-cli/resources/k16/kmono/docs/run.md

@@ -1,6 +1,7 @@
 (ns k16.kmono.cli.commands.clojure
   (:require
    [babashka.process :as proc]
+   [clojure.java.io :as io]
    [clojure.string :as str]
    [k16.kmono.cli.common.context :as common.context]
    [k16.kmono.cli.common.opts :as opts]
@@ -77,7 +78,8 @@
 
 (def command
   {:command "clojure"
-   :desc "Run an augmented clojure command"
+   :summary "Run an augmented clojure command"
+   :desc (io/resource "k16/kmono/docs/clojure.md")
 
    :options {:package-aliases opts/package-aliases-opt