diff --git a/README.md b/README.md
index 822a3d81..47a9a69c 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,19 @@
 [![Build Status](https://github.com/styrainc/regal/workflows/Build/badge.svg?branch=main)](https://github.com/styrainc/regal/actions)
 ![OPA v0.68.0](https://openpolicyagent.org/badge/v0.68.0)
 
-Regal is a linter and language server for [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/), helping
-you write better policies and have fun while doing it!
+**Rego** let's you write **rules**. **Regal** let's you **rule Rego**!
+
+The OPA community's favorite development tool for Open Policy Agent and Rego. Regal is a linter, a language server and
+a debugger implementation for [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/), with the goal of
+making your policy development experience:
+
+- **Educational**: Learn from your mistakes
+- **Secure**: Find bugs and potential issues in your policies before they reach production
+- **Uniform**: Enforce best practices and coding style across your team or organization
+- **Fun!**:
+
+
+TODO: UPDATE
 
 <img
   src="/docs/assets/regal-banner.png"
@@ -356,6 +367,12 @@ ignore:
   files:
     - file1.rego
     - "*_tmp.rego"
+
+project:
+  roots:
+    # declares the 'main' and 'lib/jwt' directories as project roots
+    - main
+    - lib/jwt
 ```
 
 Regal will automatically search for a configuration file (`.regal/config.yaml`) in the current directory, and if not
@@ -509,6 +526,43 @@ for the `regal lint` command:
 
 **Note:** all CLI flags override configuration provided in file.
 
+## Project Roots
+
+While many projects consider the project's root directory (in editors often referred to as **workspace**) their
+"main" directory for policies, some projects may contain code from other languages, policy "subprojects", or multiple
+[bundles](https://www.openpolicyagent.org/docs/latest/management-bundles/). While most of Regal's features have no need
+for this information — linting, for example, doesn't care where in a workspace policies are located as long as those
+locations aren't [ignored](#ignoring-files-globally) — some features, like [fixing](https://docs.styra.com/regal/fixing)
+benefit from knowing when a project contains multiple roots.
+
+To provide an example, consider the
+[directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch) rule, which states
+that a file declaring a `package` path like `policy.permissions.users` should also be located in a directory structure
+that mirrors that package, i.e. `policy/permissions/users`. When a violation against this rule is reported, the
+`regal fix` command, or its equivalent [Code Action](#regal-language-server) in editors, may when invoked remediate the
+issue by moving the file to the correct location. But where should the `policy/permissions/users` directory _itself_
+reside?
+
+By default, the answer to that question would be the **project**, or **workspace** root. But if the file was found
+in a subdirectory containing a **bundle**, the directory naturally belongs under that _bundle's root_ instead. The
+`roots` configuration option under the top-level `project` object allows you to tell Regal where these roots are,
+and have features that depend on this information work as expected.
+
+```yaml
+project:
+  roots:
+    - bundle1
+    - bundle2
+```
+
+The configuration file is not the only way Regal may determine project roots. Other ways include:
+
+- A directory containing a `.manifest` file will automatically be registered as a root
+- A directory containing a `.regal` directory will be registered as a root (this is normally the project root)
+
+If a feature that depends on project roots fails to identify any, it will either fail or fall back on the directory
+in which the command was run.
+
 ## Capabilities
 
 By default, Regal will lint your policies using the
diff --git a/docs/assets/lsp/code_action_fix.png b/docs/assets/lsp/code_action_fix.png
new file mode 100644
index 00000000..c3694019
Binary files /dev/null and b/docs/assets/lsp/code_action_fix.png differ
diff --git a/docs/assets/lsp/code_action_show.png b/docs/assets/lsp/code_action_show.png
new file mode 100644
index 00000000..9942fe62
Binary files /dev/null and b/docs/assets/lsp/code_action_show.png differ
diff --git a/docs/fixing.md b/docs/fixing.md
index c2bfc483..82fb8aba 100644
--- a/docs/fixing.md
+++ b/docs/fixing.md
@@ -1,15 +1,18 @@
 # Fixing Violations
 
-For each violation Regal is able to detect, there is a documentation page
-explaining the issue in detail and how to fix it. For example, here's the one for
-the [`prefer-some-in-iteration`](/regal/rules/style/prefer-some-in-iteration) rule.
+For each violation Regal is able to detect, there is a documentation page explaining the issue in detail and how to fix
+it. For example, here's the one for the [`prefer-some-in-iteration`](/regal/rules/style/prefer-some-in-iteration) rule.
 
-Some rules are automatically fixable, meaning that Regal can fix the violation
-for you. To automatically fix all supported violations, run:
+Some rules are **automatically** fixable, meaning that Regal can fix the violation for you. Note that while most fixes
+will make minor changes to the code, some fixes make more significant modifications. As an example, the
+[directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch) fix will
+automatically move a file to its idiomatic location based on the package path declared in the file.
 
-```shell
-regal fix <path> [path [...]] [flags]
-```
+:::tip
+Before you make any automated fixes, make sure to commit any other changes you may have done in your project! That way
+you can easily revert the changes if anything goes wrong, and this allows you to review the diff before committing the
+fixes.
+:::
 
 Currently, the following rules are automatically fixable:
 
@@ -17,10 +20,86 @@ Currently, the following rules are automatically fixable:
 - [use-rego-v1](/regal/rules/imports/use-rego-v1)
 - [use-assignment-operator](/regal/rules/style/use-assignment-operator)
 - [no-whitespace-comment](/regal/rules/style/no-whitespace-comment)
+- [directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch)
+
+So, how do you go on about automatically fixing reported violations?
+
+## The `regal fix` Command
+
+The first method is to use `regal fix` from the command line. This command can be seen as the remediating counterpart
+to `regal lint`, and most configuration options are the same. For example, a linter rule configured to be ignored by
+the linter will also be ignored by the fixer. Typing `regal fix --help` will show you the available options, as well
+as all the supported "fixers" for your version of Regal. Lets's see what automatically fixing violations looks like!
+
+**Example**: fixing all files in the `bundle` directory:
+
+```shell
+> regal fix bundle
+3 fixes applied:
+In project root: /Users/john/projects/authz/bundle
+
+lib/roles.rego:
+- use-rego-v1
+
+policy.rego -> main/policy.rego:
+- directory-package-mismatch
+- no-whitespace-comment
+```
+
+In the example above, Regal made fixes corresponding to the linter rules `use-rego-v1`, `directory-package-mismatch`,
+and `no-whitespace-comment` in `lib/roles.rego` and `policy.rego`. While the number of fixes applied was reported as 3,
+the number of _violations_ fixed could of course have been higher, as e.g. the `no-whitespace-comment` rule might have
+been violated in multiple places in `policy.rego`. Note also how one of the fixes (`directory-package-mismatch`)
+involved **moving** `policy.rego` to `main/policy.rego`, as that rule requires the file to be in a directory structure
+matching its package path (`package main`).
+
+### Project Roots
+
+All paths are relative to its closest **project root**, as reported in the second line of the output. Most policy
+projects will likely only have one "root", which is the workspace directory itself. More complex projects may however
+host multiple roots inside the workspace, and defining these roots — either by configuration, or by `.manifest` files —
+will in some cases (like the previously mentioned `directory-package-mismatch` fix) help Regal better apply the correct
+fixes. See the documentation on [project roots](https://docs.styra.com/regal#project-roots) for more information.
+
+### Dry Run
+
+Using the `--dry-run` flag is a great way to see what changes will be made without actually applying them. Following our
+example from above, adding the `--dry-run` flag to `regal fix bundle` would have told us beforehand what changes we
+should expect to see. Make it a habit to dry-run your fixes before applying them, and make sure you've commited any
+other changes before running the fixer!
+
+## Fixing Violations in Editors
+
+In addition to the `regal fix` command, users integratiing Regal with their editors can fix violations directly as
+they are reported in the file being edited. This is done by means of Code Actions, which commonly displays a lightbulb
+icon next to where a violation occurs. Clicking on the lightbulb will show a list of available actions, which in Regal's
+case maps directly to the available fix for the violation reported (if any).
+
+Example of code action in VS Code, where available fixes can be listed either by clicking the lightbulb icon to the
+right, or by clicking "Quick Fix..." in the tooltip window:
+
+<img
+  src={require('./assets/lsp/code_action_show.png').default}
+  alt="Screenshot of code action displayed in VS Code"/>
+
+Example of suggested Code Action for the
+[use-assignment-operator](https://docs.styra.com/regal/rules/style/use-assignment-operator) rule. Click to fix!
+
+<img
+  src={require('./assets/lsp/code_action_fix.png').default}
+  alt="Screenshot of code action fix suggestion displayed in VS Code"/>
+
+### Limitations
+
+Compared to `regal fix`, automatically fixing violations in editors has some limitations:
+
+- Normally works on one file at a time, not entire directories
+- No ability to dry-run a fix, but on the other hand, the editor's **Undo** feature will let you easily revert any
+  changes made.
 
 :::tip
-Need to fix individual violations? Checkout the editors Regal supports
-[here](/regal/editor-support).
+If you're curious about using Regal to fix problems directly in your editor, see the docs on editor support
+[here](/regal/editor-support) to learn more!
 :::
 
 ## Community
diff --git a/docs/language-server.md b/docs/language-server.md
index d1026a26..0b04bf69 100644
--- a/docs/language-server.md
+++ b/docs/language-server.md
@@ -137,6 +137,7 @@ Regal currently provides quick fix code actions for the following linter rules:
 - [use-rego-v1](https://docs.styra.com/regal/rules/imports/use-rego-v1)
 - [use-assignment-operator](https://docs.styra.com/regal/rules/style/use-assignment-operator)
 - [no-whitespace-comment](https://docs.styra.com/regal/rules/style/no-whitespace-comment)
+- [directory-package-mismatch](https://docs.styra.com/regal/rules/idiomatic/directory-package-mismatch)
 
 ### Code lenses (Evaluation)