diff a/hat/docs/JetBrains/intellij-and-clion.md b/hat/docs/JetBrains/intellij-and-clion.md
--- /dev/null
+++ b/hat/docs/JetBrains/intellij-and-clion.md
@@ -0,0 +1,102 @@
+# Intellij and Clion
+[Back to Index ../](../index.md)
+
+## Intellij and Clion
+
+Some of us use JetBrains' `IntelliJ` and `Clion` for dev work and
+decided to leave some project artifacts in the repo.
+
+Care must be taken with Intellij and Clion
+as these tools do not play well together,
+specifically we cannot have `Clion` and `Intellij`
+project artifacts rooted under each other or in the same dir.
+
+## Intellij
+The `intellij` subdir under the root HAT directory
+contains the `.idea` project dir and the various `*.iml` files
+for each of the various `modules`
+(note the use of `Intellji`'s meaning of the word of module here)
+
+As you will note the `intellij` dir is somewhat self contained. the various `*.iml`
+files refer to the source dirs using relative paths.
+
+I tend to add `Intellij` modules by hand. There are gotchas ;)
+
+As with every intellij project, `.idea/modules.xml` 'points' to the iml files for each module (intellij's notion of module ;) )
+```xml
+
+
+
+
+
+
+
+```
+
+The various `.iml` files then have relative paths to their source/resource dirs roots.
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+Making run configurations available to other developers is probably `a bridge too far`
+
+But with some careful XML tooling we can make it easier to add 'run configurations'.
+
+### How intellij stores run configurations
+
+I also tend to hand hack run configurations so will leave this here for reference
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Clion
+
+Thankfully Clion uses cmake, so we get to re-use the CMakeLists.txt in the various backends to build.
+
+The intent is that these cmake artifacts can be run standalone (using cmake in the appropriate dir),
+from within Clion and can be used by maven. So the CMakeLists.txt files have some extra variables to
+help us use them in these three modes.
+
+
+
+