Merge branch 'main' into BenLloydPearson-patch-3

docs/how-it-works.md

@@ -3,11 +3,14 @@ title: How gitStream Works
 description: Learn how gitStream automates code review workflows.
 ---
 # How gitStream Works
-You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab organization. These files end with a `.cm`  extension, and they outline automations that will run whenever someone opens a new PR or makes changes to an existing PR. 
+You can configure gitStream via one or more Continuous Merge (CM) files inside your git repository or GitHub/GitLab organization. These files end with a `.cm`  extension, and they outline automations that will run for your repo's pull requests. 
 ## Syntax Overview
 CM files contain a combination of YAML and Jinja2 to build rules that follow an "if this, then that" approach to triggering and executing automations. This, combined with templating and gitStream-specific functions gives you a highly-flexible framework for building custom CM automations.
 
-All CM files must have a section that starts with `automations:` that contains one or more custom automations that will trigger for the repo. gitStream is triggered every time someone opens a new PR or changes an existing PR. Once activated, gitStream searches for applicable CM files and executes the automations that are listed inside them.
+All CM files must have a section that starts with `automations:` that contains one or more custom automations that will trigger for the repo. By default, gitStream is triggered every time someone opens a new PR or pushes a commit to an existing PR. Once activated, gitStream searches for applicable CM files and executes the automations that are listed inside them.
+
+!!! tip "Explicit Triggers"
+    You can configure gitStream to trigger for other PR interactions, including comments, labels, and merge status. Read more about the [gitStream execution model](/execution-model).
 
 Here is an example of the basic components that are required in every CM file.
 
@@ -83,6 +86,20 @@ Jinja templating makes it easy to write custom expressions that can be invoked e
       - src/app/resources/
     ```
 
+### Built-in Functions
+gitStream is built on top of Jinja2 and provides all [default filters](https://mozilla.github.io/nunjucks/templating.html#builtin-filters) from that library. gitStream also includes extra filters on top of Jinja2 that are specific to git repo workflow automations.
+
+!!! warning
+    Don't use these terms when naming automations, plugins, custom expressions, or any other component of gitStream because this will lead to naming conflicts
+
+gitStream filters:
+
+`allDocs` `allImages` `allTests` `automations` `codeExperts` `config` `difference` `estimatedReviewTime` `explainCodeExperts` `explainRankByGitBlame` `extractJitFindings` `extractSonarFindings` `extensions` `every` `filter` `includes` `isFirstCommit` `isFormattingChange` `intersection` `manifest` `map` `mapToEnum` `match` `matchDiffLines` `nope` `rankByGitActivity` `rankByGitBlame` `reject` `some`
+
+[Nunjucks](https://mozilla.github.io/nunjucks/templating.html#builtin-filters) filters:
+
+`abs` `asyncAll` `asyncEach` `batch` `block` `call` `capitalize` `center` `default` `dictsort` `dump` `e` `escape` `extends` `filter` `first` `float` `for` `forceescape` `groupby` `if` `import` `include` `indent` `int` `join` `last` `length` `list` `lower` `macro` `nl2br` `raw` `reject` `rejectattr` `replace` `reverse` `round` `safe` `select` `selectattr` `set` `slice` `sort` `string` `striptags` `sum` `title` `trim` `truncate` `upper` `urlencode` `urlize` `verbatim` `wordcount`
+
 ### Ignore Files or Repos
 
 You can provide gitStream with a list of specific files to ignore for all automations listed in the same CM file. To do so, add a [`configuration:`](/cm-file/#config) section to the CM file that you want to apply the exclusion list to. In the configuration section, add a list of files as an argument to the `ignore_files:` key.
@@ -115,6 +132,10 @@ First, when a repository defines the same automation as an organization-level ru
 
 Second, no priority is given to individual automations. Instead, gitStream collects all applicable automations for a given PR and processes them all at once.
 
+### Plugins
+
+gitStream supports the use of JavaScript plugins to create new filter functions. This enables you to write code that further extends gitStream capabilities and connect gitStream to external API services. Read the guide on writing gitStream
+
 ## Next Step
 !!! tip "Write your first automation."
     The best way to familiarize yourself with CM syntax is to build automations, and we've covered enough info for you to start! 
@@ -174,17 +195,6 @@ Upon completion, gitStream will show one of the following three statuses:
 
 gitStream checks have a 10-minute timeout for fail-safe reasons. If the check exceeds this time limit, the result will be displayed as Neutral - *Skipped*.
 
-### Reserved Words
-Avoid using these words when naming your automations, actions, or other components. 
-
-gitStream reserved words:
-
-`allDocs` `allImages` `allTests` `automations` `codeExperts` `config` `difference` `estimatedReviewTime` `explainCodeExperts` `explainRankByGitBlame` `extractJitFindings` `extractSonarFindings` `extensions` `every` `filter` `includes` `isFirstCommit` `isFormattingChange` `intersection` `manifest` `map` `mapToEnum` `match` `matchDiffLines` `nope` `rankByGitActivity` `rankByGitBlame` `reject` `some`
-
-[Nunjucks](https://mozilla.github.io/nunjucks/templating.html#builtin-filters) reserved words:
-
-`abs` `asyncAll` `asyncEach` `batch` `block` `call` `capitalize` `center` `default` `dictsort` `dump` `e` `escape` `extends` `filter` `first` `float` `for` `forceescape` `groupby` `if` `import` `include` `indent` `int` `join` `last` `length` `list` `lower` `macro` `nl2br` `raw` `reject` `rejectattr` `replace` `reverse` `round` `safe` `select` `selectattr` `set` `slice` `sort` `string` `striptags` `sum` `title` `trim` `truncate` `upper` `urlencode` `urlize` `verbatim` `wordcount`
-
 ### Syntax highlighting
 
 You can add support for `.cm` in your code editor, see [FAQ](https://docs.gitstream.cm/faq/#is-there-cm-syntax-highlighting).