docs: Update regal docs for 0.41.1 release (#8730)

https://github.com/open-policy-agent/regal/releases/tag/v0.41.1

Signed-off-by: Charlie Egan <charlie_egan@apple.com>

docs/projects/regal/custom-rules/roast.md

@@ -234,15 +234,11 @@ expressions found in template strings, and is thus either `true` or missing, nev
 Following the Roast convention of omitting boolean attributes that are `false`, the `multi_line` attribute found
 on template string nodes is only present when `true`.
 
-### Fixed inconsistencies in the original Rego AST
+### Module comments represented as arrays of location strings
 
-A few inconsistencies exist in the original AST JSON format:
-
-- `comments` attributes having a `Text` attribute rather than the expected `text`
-- `comments` attributes having a `Location` attribute rather than the expected `location`
-
-Fixing these in the original format would be a breaking change. The Roast format corrects these inconsistencies, and
-uses `text` and `location` consistently.
+Since a comment is simply text at a given location, they are simply represented as location strings. OPA's AST format
+adds a redundant extra text atttribute only to strip off the leading `#` from the comment text, and is additionally
+inconsistent with the rest if its format, as both the `text` and `location` attributes are title-cased.
 
 ## Performance
 

docs/projects/regal/language-server.md

@@ -67,7 +67,21 @@ or expanded, which may be useful for hiding content that is not relevant to the
   src={require('./assets/lsp/folding.png').default}
   alt="Screenshot of folding ranges as displayed in Zed"/>
 
-Regal supports folding ranges for blocks, imports and comments.
+Regal provides folding ranges for all AST nodes that may span more than a single line, like rules, functions,
+comprehensions, collection literals, and more. The server additionally provides folding ranges for import and comment
+"blocks", where consecutive imports and comments are grouped together in a single folding range.
+
+The language server specification allows editors to present a few
+[capabilities](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#foldingRangeClientCapabilities)
+related to folding ranges. The two most relevant to Regal are both supported by the language server:
+
+- `lineFoldingOnly` tells Regal that the editor only supports folding whole lines, and that folding always starts and
+  ends at the beginning of a line. When set to `true` (which it commonly is by default), Regal will skip calculating
+  character positions for where folding should start and end, which generally results in faster rendering of the folding
+  ranges.
+- `rangeLimit` is a positive integer value that when provided tells Regal the maximum number of folding ranges that the
+  server should return. While Regal honors this setting, the number is commonly in the thousands (for example, VS Code's
+  default is 5000), which is much higher than the number of folding ranges that a typical Rego file would have.
 
 ### Document and workspace symbols
 

docs/projects/regal/pre-commit-hooks.md

@@ -49,3 +49,32 @@ Runs Regal against all staged `.rego` files, aborting the commit if any fail.
 Runs Regal against all staged `.rego` files, aborting the commit if any fail.
 
 - Downloads the latest `regal` binary from Github.
+
+### `regal-fix`
+
+![commit-msg hook](https://img.shields.io/badge/hook-pre--commit-informational?logo=git)
+
+Runs `regal fix` against all staged `.rego` files, applying any
+auto-fixable rule violations in place. Use this alongside `regal-lint` when you
+want the hook to repair style-level issues automatically rather than asking the
+contributor to re-run `regal fix` themselves.
+
+- requires the `go` build chain is installed and available on `$PATH`
+- will build and install the tagged version of Regal in an isolated `GOPATH`
+- ensures compatibility between versions
+
+### `regal-fix-use-path`
+
+![commit-msg hook](https://img.shields.io/badge/hook-pre--commit-informational?logo=git)
+
+Same as `regal-fix`, but uses the `regal` binary already on `$PATH`.
+
+- requires the `regal` package is already installed and available on `$PATH`.
+
+### `regal-fix-download`
+
+![commit-msg hook](https://img.shields.io/badge/hook-pre--commit-informational?logo=git)
+
+Same as `regal-fix`, but downloads the latest `regal` binary from GitHub instead of building or relying on `$PATH`.
+
+- Downloads the latest `regal` binary from Github.