diff --git a/README.md b/README.md
index d8ca797..1b3be7f 100644
--- a/README.md
+++ b/README.md
@@ -93,9 +93,6 @@ Flags:
 Use "kantra [command] --help" for more information about a command.
 ```
 
-Additionally, two environment variables control the container runtime and the kantra image: `PODMAN_BIN` and `RUNNER_IMG`:
-- `PODMAN_BIN`: path to your container runtime (podman or docker); ie: `PODMAN_BIN=/usr/local/bin/docker`
-- `RUNNER_IMG`: the tag of the kantra image to invoke; ie: `RUNNER_IMG=localhost/kantra:latest`
 
 ### Analyze
 
@@ -210,50 +207,7 @@ To run `transform rules` on application source code, run:
 kantra transform rules --input=<path/to/xmlrules> --output=<path/to/output/dir>
 ```
 
-## Quick Demos
-
-Once you have kantra installed, these examples will help you run both an 
-analyze and a transform command.
-
-### Analyze
-
-- Get the example application to run analysis on  
-`git clone https://github.com/konveyor/example-applications`
-
-- List available target technologies  
-`kantra analyze --list-targets`
-
-- Run analysis with a specified target technology  
-`kantra analyze --input=<path-to/example-applications/example-1> --output=<path-to-output-dir> --target=cloud-readiness`
-
-- Several analysis reports will have been created in your specified output path:
-
-```sh
-$ ls ./output/ -1
-analysis.log
-dependencies.yaml
-dependency.log
-output.yaml
-static-report
-```
-
-`output.yaml` is the file that contains issues report.   
-`static-report` contains the static HTML report.  
-`dependencies.yaml`contains a dependencies report.  
-
-### Transform
-
-- Get the example application to transform source code  
-`git clone https://github.com/ivargrimstad/jakartaee-duke`
-
-- View available OpenRewrite recipes  
-`kantra transform openrewrite --list-targets` 
-
-- Run a recipe on the example application  
-`kantra transform openrewrite --input=<path-to/jakartaee-duke> --target=jakarta-imports`
-
-- Inspect the `jakartaee-duke` application source code diff to see the transformation  
-
+### analyze and transform [examples](./docs/example.md)
 
 ## Code of Conduct
 Refer to Konveyor's Code of Conduct [here](https://github.com/konveyor/community/blob/main/CODE_OF_CONDUCT.md).
diff --git a/docs/analyzer.md b/docs/analyzer.md
new file mode 100644
index 0000000..4c6486b
--- /dev/null
+++ b/docs/analyzer.md
@@ -0,0 +1,11 @@
+## Analyzer-lsp Documentation  
+
+### kantra analyze runs [analyzer-lsp](https://github.com/konveyor/analyzer-lsp) 
+
+- To better understand how rules are used in analysis, see the [rules](https://github.com/konveyor/analyzer-lsp/blob/main/docs/rules.md)
+documentation
+
+- If a rule is matched, it creates a [violation](https://github.com/konveyor/analyzer-lsp/blob/main/docs/violations.md) 
+
+- [Labels](https://github.com/konveyor/analyzer-lsp/blob/main/docs/labels.md) 
+can be used to filter in and out rules
diff --git a/docs/developer.md b/docs/developer.md
new file mode 100644
index 0000000..b42161e
--- /dev/null
+++ b/docs/developer.md
@@ -0,0 +1,16 @@
+### Running kantra
+
+Two environment variables control the container runtime and the kantra image: `PODMAN_BIN` and `RUNNER_IMG`:
+- `PODMAN_BIN`: path to your container runtime (podman or docker)
+- `RUNNER_IMG`: the tag of the kantra image to invoke
+
+#### example:
+
+`podman build -f Dockerfile -t kantra:dev`
+
+`RUNNER_IMG=kantra:dev PODMAN_BIN=/usr/local/bin/podman go run main.go analyze --input=<path-to-src-application> --output=./output`
+
+#### Helpful flags:
+
+- To increase logs for debugging, you can set `--log-level` (default is 5)
+- ie: `--log-level=7`
diff --git a/docs/example.md b/docs/example.md
new file mode 100644
index 0000000..a4b96d8
--- /dev/null
+++ b/docs/example.md
@@ -0,0 +1,41 @@
+Once you have kantra installed, these examples will help you run both an 
+analyze and a transform command.
+
+### Analyze
+
+- Get the example application to run analysis on  
+`git clone https://github.com/konveyor/example-applications`
+
+- List available target technologies  
+`kantra analyze --list-targets`
+
+- Run analysis with a specified target technology  
+`kantra analyze --input=<path-to/example-applications/example-1> --output=<path-to-output-dir> --target=cloud-readiness`
+
+- Several analysis reports will have been created in your specified output path:
+
+```sh
+$ ls ./output/ -1
+analysis.log
+dependencies.yaml
+dependency.log
+output.yaml
+static-report
+```
+
+`output.yaml` is the file that contains issues report.   
+`static-report` contains the static HTML report.  
+`dependencies.yaml`contains a dependencies report.  
+
+### Transform
+
+- Get the example application to transform source code  
+`git clone https://github.com/ivargrimstad/jakartaee-duke`
+
+- View available OpenRewrite recipes  
+`kantra transform openrewrite --list-targets` 
+
+- Run a recipe on the example application  
+`kantra transform openrewrite --input=<path-to/jakartaee-duke> --target=jakarta-imports`
+
+- Inspect the `jakartaee-duke` application source code diff to see the transformation  
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..f08ad5a
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,15 @@
+## Output
+
+
+#### Default rules:
+
+- the analyze command runs against a set of packaged rules [here](https://github.com/konveyor/rulesets/)
+- `--label-selector` and/or `--target` can filter these rules
+- `--rules` can be provided to run analyze on rules outside of this set
+
+#### `--rules` + `--target`
+
+- In kantra, if a rule is given as well as a target, but the given rule **does not**
+have the target label, the given rule will not match. 
+    - You must add the target label to the custom rule (if applicable) in
+    order to run this rule.