Merge branch 'edge'

For some reason. Removing blocks fixed rendering error

.dockerignore

@@ -1,8 +1,8 @@
-node_modules
 Dockerfile
 .dockerignore
 .gitignore
 .git
 src/logs
-/docs
 .github
+/docs/
+/node_modules/

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [FoxxMD]
+custom: ["bitcoincash:qqmpsh365r8n9jhp4p8ks7f7qdr7203cws4kmkmr8q"]

.github/workflows/dockerhub.yml

@@ -36,8 +36,6 @@ jobs:
             type=raw,value=latest,enable=${{ endsWith(github.ref, 'master') }}
             type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
             type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
           flavor: |
             latest=false
       

.gitignore

@@ -381,4 +381,14 @@ dist
 .pnp.*
 
 **/src/**/*.js
+!src/Web/assets/public/yaml/*
 **/src/**/*.map
+/**/*.sqlite
+/**/*.bak
+*.yaml
+*.json5
+
+!src/Schema/*.json
+!docs/**/*.json5
+!docs/**/*.yaml
+!docs/**/*.json

Dockerfile

@@ -1,13 +1,17 @@
-FROM node:16-alpine3.12
+FROM node:16-alpine3.14 as base
 
 ENV TZ=Etc/GMT
 
-RUN apk update
+# vips required to run sharp library for image comparison
+RUN echo "http://dl-4.alpinelinux.org/alpine/v3.14/community" >> /etc/apk/repositories \
+    && apk --no-cache add vips
 
 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
 
 WORKDIR /usr/app
 
+FROM base as build
+
 COPY package*.json ./
 COPY tsconfig.json .
 
@@ -15,7 +19,13 @@ RUN npm install
 
 ADD . /usr/app
 
-RUN npm run build
+RUN npm run build && rm -rf node_modules
+
+FROM base as app
+
+COPY --from=build /usr/app /usr/app
+
+RUN npm install --production
 
 ENV NPM_CONFIG_LOGLEVEL debug
 

README.md

@@ -1,6 +1,7 @@
-[![Latest Release](https://img.shields.io/github/v/release/foxxmd/context-mod)](https://github.com/FoxxMD/context-mod/releases)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Docker Pulls](https://img.shields.io/docker/pulls/foxxmd/context-mod)](https://hub.docker.com/r/foxxmd/context-mod)
+# ContextMod [![Latest Release](https://img.shields.io/github/v/release/foxxmd/context-mod)](https://github.com/FoxxMD/context-mod/releases) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Docker Pulls](https://img.shields.io/docker/pulls/foxxmd/context-mod)](https://hub.docker.com/r/foxxmd/context-mod)
+
+<img src="/docs/logo.png" align="right"
+alt="ContextMod logo" width="180" height="176">
 
 **Context Mod** (CM) is an event-based, [reddit](https://reddit.com) moderation bot built on top of [snoowrap](https://github.com/not-an-aardvark/snoowrap) and written in [typescript](https://www.typescriptlang.org/).
 
@@ -15,19 +16,24 @@ An example of the above that Context Bot can do now:
 
 Some feature highlights:
 * Simple rule-action behavior can be combined to create any level of complexity in behavior
-* One instance can manage all moderated subreddits for the authenticated account
-* **Per-subreddit configuration** is handled by JSON stored in the subreddit wiki
-* Any text-based actions (comment, submission, message, usernotes, ban, etc...) can be configured via a wiki page or raw text in JSON and support [mustache](https://mustache.github.io) [templating](/docs/actionTemplating.md)
+* Server/client architecture
+  * Default/no configuration runs "All In One" behavior
+  * Additional configuration allows web interface to connect to multiple servers
+  * Each server instance can run multiple reddit accounts as bots
+* **Per-subreddit configuration** is handled by YAML (**like automoderator!**) or JSON stored in the subreddit wiki
+* Any text-based actions (comment, submission, message, usernotes, ban, etc...) can be configured via a wiki page or raw text and supports [mustache](https://mustache.github.io) [templating](/docs/actionTemplating.md)
 * History-based rules support multiple "valid window" types -- [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations), [Day.js Durations](https://day.js.org/docs/en/durations/creating), and submission/comment count limits.
 * Support Activity skipping based on:
   * Author criteria (name, css flair/text, age, karma, moderator status, and [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes))
   * Activity state (removed, locked, distinguished, etc.)
 * Rules and Actions support named references (write once, reference anywhere)
+* [**Image Comparisons**](/docs/imageComparison.md) via fingerprinting and/or pixel differences
+* [**Repost detection**](/docs/examples/repost) with support for external services (youtube, etc...)
 * Global/subreddit-level **API caching**
 * Support for [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes) as criteria or Actions (writing notes)
 * Docker container support
 * Event notification via Discord
-* **Web interface** for monitoring and administration
+* **Web interface** for monitoring, administration, and oauth bot authentication
 
 # Table of Contents
 
@@ -80,7 +86,7 @@ See the [Moderator's Getting Started Guide](/docs/gettingStartedMod.md)
 
 ## Configuration and Documentation
 
-Context Bot's configuration can be written in JSON, [JSON5](https://json5.org/) or YAML. Its schema conforms to [JSON Schema Draft 7](https://json-schema.org/). Additionally, many **operator** settings can be passed via command line or environmental variables.
+Context Bot's configuration can be written in YAML (like automoderator) or [JSON5](https://json5.org/). Its schema conforms to [JSON Schema Draft 7](https://json-schema.org/). Additionally, many **operator** settings can be passed via command line or environmental variables.
 
 * For **operators** (running the bot instance) see the [Operator Configuration](/docs/operatorConfiguration.md) guide
 * For **moderators** consult the [app schema and examples folder](/docs/#configuration-and-usage)
@@ -89,9 +95,12 @@ Context Bot's configuration can be written in JSON, [JSON5](https://json5.org/)
 
 ## Web UI and Screenshots
 
-RCB comes equipped with a web interface designed for use by both moderators and bot operators. Some feature highlights:
+### Dashboard
+
+CM comes equipped with a dashboard designed for use by both moderators and bot operators.
 
 * Authentication via Reddit OAuth -- only accessible if you are the bot operator or a moderator of a subreddit the bot moderates
+* Connect to multiple ContextMod instances (specified in configuration)
 * Monitor API usage/rates
 * Monitoring and administration **per subreddit:**
   * Start/stop/pause various bot components
@@ -100,11 +109,32 @@ RCB comes equipped with a web interface designed for use by both moderators and
   * View **real-time logs** of what the bot is doing on your subreddit
   * **Run bot on any permalink**
 
-![Subreddit View](docs/screenshots/subredditStatus.jpg)
+![Subreddit View](docs/images/subredditStatus.jpg)
 
-Additionally, a helper webpage is available to help initial setup of your bot with reddit's oauth authentication. [Learn more about using the oauth helper.](docs/botAuthentication.md#cm-oauth-helper-recommended)
+### Bot Setup/Authentication
 
-![Oauth View](docs/screenshots/oauth.jpg)
+A bot oauth helper allows operators to define oauth credentials/permissions and then generate unique, one-time invite links that allow moderators to authenticate their own bots without operator assistance. [Learn more about using the oauth helper.](docs/botAuthentication.md#cm-oauth-helper-recommended)
+
+Operator view/invite link generation:
+
+![Oauth View](docs/images/oauth.jpg)
+
+Moderator view/invite and authorization:
+
+![Invite View](docs/images/oauth-invite.jpg)
+
+### Configuration Editor
+
+A built-in editor using [monaco-editor](https://microsoft.github.io/monaco-editor/) makes editing configurations easy:
+
+* Automatic JSON or YAML syntax validation and formatting
+* Automatic Schema (subreddit or operator) validation
+* All properties are annotated via hover popups
+* Unauthenticated view via `yourdomain.com/config`
+* Authenticated view loads subreddit configurations by simple link found on the subreddit dashboard
+* Switch schemas to edit either subreddit or operator configurations
+
+![Configuration View](docs/images/editor.jpg)
 
 ## License
 

app.json

@@ -17,12 +17,22 @@
     "REFRESH_TOKEN": {
       "description": "Refresh token retrieved from authenticating an account with your Reddit Application",
       "value": "",
-      "required": true
+      "required": false
     },
     "ACCESS_TOKEN": {
       "description": "Access token retrieved from authenticating an account with your Reddit Application",
       "value": "",
-      "required": true
+      "required": false
+    },
+    "REDIRECT_URI": {
+      "description": "Redirect URI you specified when creating your Reddit Application. Required if you want to use the web interface. In the provided example replace 'your-heroku-app-name' with the name of your HEROKU app.",
+      "value": "https://your-heroku-6app-name.herokuapp.com/callback",
+      "required": false
+    },
+    "OPERATOR": {
+      "description": "Your reddit username WITHOUT any prefixes EXAMPLE /u/FoxxMD => FoxxMD. Specified user will be recognized as an admin.",
+      "value": "",
+      "required": false
     },
     "WIKI_CONFIG": {
       "description": "Relative url to contextbot wiki page EX https://reddit.com/r/subreddit/wiki/<path>",

cliff.toml

@@ -0,0 +1,67 @@
+# configuration file for git-cliff (0.1.0)
+
+[changelog]
+# changelog header
+header = """
+# Changelog
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+# https://tera.netlify.app/docs/#introduction
+body = """
+{% if version %}\
+    ## [{{ version | replace(from="v", to="") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits
+    | filter(attribute="scope")
+    | sort(attribute="scope") %}
+        - *({{commit.scope}})* {{ commit.message | upper_first }}
+        {%- if commit.breaking %}
+        {% raw %}  {% endraw %}- **BREAKING**: {{commit.breaking_description}}
+        {%- endif -%}
+    {%- endfor -%}
+    {%- for commit in commits %}
+        {%- if commit.scope -%}
+        {% else -%}
+            - *(No Category)* {{ commit.message | upper_first }}
+            {% if commit.breaking -%}
+            {% raw %}  {% endraw %}- **BREAKING**: {{commit.breaking_description}}
+            {% endif -%}
+        {% endif -%}
+    {% endfor -%}
+{% endfor %}
+"""
+# remove the leading and trailing whitespaces from the template
+trim = true
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# allow only conventional commits
+# https://www.conventionalcommits.org
+conventional_commits = true
+# regex for parsing and grouping commits
+commit_parsers = [
+    { message = "^feat", group = "Features"},
+    { message = "^fix", group = "Bug Fixes"},
+    { message = "^doc", group = "Documentation"},
+    { message = "^perf", group = "Performance"},
+    { message = "^refactor", group = "Refactor"},
+    { message = "^style", group = "Styling"},
+    { message = "^test", group = "Testing"},
+    { message = "^chore\\(release\\): prepare for", skip = true},
+    { message = "^chore", group = "Miscellaneous Tasks"},
+    { body = ".*security", group = "Security"},
+]
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# glob pattern for matching git tags
+tag_pattern = "[0-9]*"
+# regex for skipping tags
+skip_tags = "v0.1.0-beta.1"

docs/README.md

@@ -5,6 +5,7 @@
 * [Getting Started](#getting-started)
 * [How It Works](#how-it-works)
 * [Concepts](#concepts)
+  * [Run](#runs)
   * [Check](#checks)
   * [Rule](#rule)
     * [Examples](#available-rules)
@@ -18,6 +19,7 @@
   * [Activities `window`](#activities-window)
   * [Comparisons](#thresholds-and-comparisons)
   * [Activity Templating](/docs/actionTemplating.md)
+  * [Image Comparisons](#image-comparisons)
 * [Best Practices](#best-practices)
   * [Named Rules](#named-rules)
   * [Rule Order](#rule-order)
@@ -35,31 +37,61 @@ Review **at least** the **How It Works** and **Concepts** below, then:
 
 Where possible Context Mod (CM) uses the same terminology as, and emulates the behavior, of **automoderator** so if you are familiar with that much of this may seem familiar to you.
 
+### Diagram
+
+Expand the section below for a simplified flow diagram of how CM processes an incoming Activity. Then refer the text description of the diagram below as well as [Concepts](#Concepts) for descriptions of individual components.
+
+<details>
+<summary>Diagram</summary>
+
+![Flow Diagram](/docs/images/diagram-highlevel.jpg)
+
+</details>
+
 CM's lifecycle looks like this:
 
 #### 1) A new event in your subreddit is received by CM
 
 The events CM watches for are configured by you. These can be new modqueue/unmoderated items, submissions, or comments.
 
-#### 2) CM sequentially processes each Check in your configuration
+#### 2) CM sequentially processes each Run in your configuration
+
+A [**Run**](#Runs) is made up of a set of [**Checks**](#Checks)
+
+#### 3) CM sequentially processes each Check in the current Run
 
 A **Check** is a set of:
 
-* One or more **Rules** that define what conditions should **trigger** this Check
-* One or more **Actions** that define what the bot should do once the Check is **triggered**
+* One or more [**Rules**](#Rule) that define what conditions should **trigger** this Check
+* One or more [**Actions**](#Action) that define what the bot should do once the Check is **triggered**
 
-#### 3) Each Check is processed, *in order*, until a Check is triggered
+#### 4) Each Check is processed, *in order*, until a Check is **triggered**
 
-Once a Check is **triggered** no more Checks will be processed. This means all subsequent Checks in your configuration (in the order you listed them) are basically skipped.
+In CM's default configuration, once a Check is **triggered** no more Checks will be processed. This means all subsequent Checks in this Run (in the order you listed them) are skipped.
 
-#### 4) All Actions from that Check are executed
+#### 5) All Actions from the triggered Check are executed
 
-After all Actions are executed CM returns to waiting for the next Event.
+After all **Actions** from the triggered **Check** are executed CM begins processing the next **Run**
+
+#### 6) Rinse and Repeat from #3
+
+Until all Runs have been processed.
 
 ## Concepts
 
 Core, high-level concepts regarding how CM works.
 
+### Runs
+
+A **Run** is made up of a set of **Checks** that represent a group of related behaviors the bot should check for or perform -- that are independent of any other behaviors the Bot should perform.
+
+An example of Runs:
+
+* A group of Checks that look for missing flairs on a user or a new submission and flair accordingly
+* A group of Checks that detect spam or self-promotion and then remove those activities
+
+Both group of Checks are independent of each other (don't have any patterns or actions in common). Learn more about using [Runs and **Flow Control** to control how CM behaves.](/docs/examples/advancedConcepts/flowControl.md)
+
 ### Checks
 
 A **Check** is the main logical unit of behavior for the bot. It is equivalent to "if X then Y". A Check is comprised of:
@@ -67,7 +99,7 @@ A **Check** is the main logical unit of behavior for the bot. It is equivalent t
 * One or more **Rules** that are tested against an **Activity**
 * One of more **Actions** that are performed when the **Rules** are satisfied
 
-The bot's configuration can be made up of one or more **Checks** that are processed **in the order they are listed in the configuration.**
+A Run can be made up of one or more **Checks** that are processed **in the order they are listed in the Run.**
 
 Once a Check is **triggered** (its Rules are satisfied and Actions performed) all subsequent Checks are skipped.
 
@@ -86,7 +118,7 @@ A **Rule** is some set of **criteria** (conditions) that are tested against an A
 
 There are generally three main properties for a Rule:
 
-* **Critiera** -- The conditions/values you want to test for.
+* **Criteria** -- The conditions/values you want to test for.
 * **Activities Window** -- If applicable, the range of activities that the **criteria** will be tested against.
 * **Rule-specific options** -- Any number of options that modify how the **criteria** are tested.
 
@@ -100,7 +132,8 @@ Find detailed descriptions of all the Rules, with examples, below:
 * [Repeat Activity](/docs/examples/repeatActivity)
 * [History](/docs/examples/history)
 * [Author](/docs/examples/author)
-* Regex
+* [Regex](/docs/examples/regex)
+* [Repost](/docs/examples/repost)
 
 ### Rule Set
 
@@ -118,6 +151,15 @@ It consists of:
 * **rules** -- The **Rules** for the Rule Set.
 
 Example
+
+YAML
+```yaml
+condition: AND
+# rules are an array
+rules:
+ - aRule
+```
+JSON
 ```json5
 {
   "condition": "AND",
@@ -138,6 +180,7 @@ An **Action** is some action the bot can take against the checked Activity (comm
 
 * Remove (Comment/Submission)
 * Flair (Submission)
+* User Flair (Submission/Comment)
 * Ban (User)
 * Approve (Comment/Submission)
 * Comment (Reply to Comment/Submission)
@@ -149,12 +192,12 @@ For detailed explanation and options of what individual Actions can do [see the
 
 ### Filters
 
-**Checks, Rules, and Actions** all have two additional (optional) criteria "tests". These tests behave differently than rule/check triggers in that:
+**Runs, Checks, Rules, and Actions** all have two additional (optional) criteria "tests". These tests behave differently than rule/check triggers in that:
 
 * When they **pass** the thing being tested continues to process as usual
 * When they **fail** the thing being tested **is skipped, not failed.**
 
-For **Checks** and **Actions** skipping means that the thing is not processed. The Action is not run, the Check is not triggered.
+For **Runs**, **Checks**, and **Actions** skipping means that the thing is not processed. The Action is not run, the Check is not triggered.
 
 In the context of **Rules** (in a Check) skipping means the Rule does not get run BUT it does not fail. The Check will continue processing as if the Rule did not exist. However, if ALL Rules in a Check are skipped then the Check does "fail" (is not triggered).
 
@@ -268,6 +311,12 @@ The duration value compares a time range from **now** to `duration value` time i
 
 Refer to [duration values in activity window documentation](/docs/activitiesWindow.md#duration-values) as well as the individual rule/criteria schema to see what this duration is comparing against.
 
+### Image Comparisons
+
+ContextMod implements two methods for comparing **image content**, perceptual hashing and pixel-to-pixel comparisons. Comparisons can be used to filter activities in some activities.
+
+See [image comparison documentation](/docs/imageComparison.md) for a full reference. 
+
 ## Best Practices
 
 ### Named Rules

docs/activitiesWindow.md

@@ -17,7 +17,28 @@ Examples of all of the above
 
 <details>
 
+```yaml
+# count, last 100 activities
+window: 100
+
+# duration, last 10 days
+window: 10 days
+
+# duration object, last 2 months and 5 days
+window:
+  months: 2
+  days: 5
+
+# iso 8601 string, last 15 minutes
+window: PT15M
+
+# ActivityWindowCriteria, last 100 activities or 6 weeks of activities (whichever is found first)
+window:
+  count: 100
+  duration: 6 weeks
 ```
+
+```json5
 // count, last 100 activities
 {
   "window": 100
@@ -49,6 +70,7 @@ Examples of all of the above
   }
 }
 ```
+
 </details>
 
 ## Types of Ranges
@@ -95,6 +117,7 @@ If you need to specify multiple units of time for your duration you can instead
 
 Example
 
+JSON
 ```json
 {
   "days": 4,
@@ -102,6 +125,13 @@ Example
   "minutes": 20
 }
 ```
+YAML
+```yaml
+window:
+  days: 4
+  hours: 6
+  minutes: 20
+```
 
 ##### An ISO 8601 duration string
 
@@ -119,6 +149,7 @@ This is an object that lets you specify more granular conditions for your range.
 
 The full object looks like this:
 
+JSON
 ```json
 {
   "count": 100,
@@ -130,6 +161,19 @@ The full object looks like this:
   }
 }
 ```
+YAML
+```yaml
+window:
+  count: 100
+  duration: 10 days
+  satisfyOn: any
+  subreddits:
+    include:
+      - mealtimevideos
+      - pooptimevideos
+    exclude:
+      - videos
+```
 
 ### Specifying Range
 
@@ -142,7 +186,9 @@ If both range properties are specified then the value `satisfyOn` determines how
 
 If **any** then Activities will be retrieved until one of the range properties is met, **whichever occurs first.**
 
-Example 
+Example
+
+JSON
 ```json
 {
   "count": 80,
@@ -150,6 +196,13 @@ Example
   "satisfyOn": "any"
 }
 ```
+YAML
+```yaml
+window:
+  count: 80
+  duration: 90 days
+  satisfyOn: any
+```
 Activities are retrieved in chunks of 100 (or `count`, whichever is smaller)
 
 * If 90 days of activities returns only 40 activities => returns 40 activities
@@ -160,6 +213,8 @@ Activities are retrieved in chunks of 100 (or `count`, whichever is smaller)
 If **all** then both ranges must be satisfied. Effectively, whichever range produces the most Activities will be the one that is used.
 
 Example
+
+JSON
 ```json
 {
   "count": 100,
@@ -167,6 +222,13 @@ Example
   "satisfyOn": "all"
 }
 ```
+YAML
+```yaml
+window:
+  count: 100
+  duration: 90 days
+  satisfyOn: all
+```
 Activities are retrieved in chunks of 100 (or `count`, whichever is smaller)
 
 * If at 90 days of activities => 40 activities retrieved
@@ -187,6 +249,8 @@ You may filter retrieved Activities using an array of subreddits.
 Use **include** to specify which subreddits should be included from results
 
 Example where only activities from /r/mealtimevideos and /r/modsupport will be returned
+
+JSON
 ```json
 {
   "count": 100,
@@ -196,7 +260,17 @@ Example where only activities from /r/mealtimevideos and /r/modsupport will be r
     "include": ["mealtimevideos","modsupport"]
   }
 }
-
+```
+YAML
+```yaml
+window:
+  count: 100
+  duruation: 90 days
+  satisfyOn: any
+  subreddits:
+    include:
+      - mealtimevideos
+      - modsupport
 ```
 
 #### Exclude
@@ -204,6 +278,8 @@ Example where only activities from /r/mealtimevideos and /r/modsupport will be r
 Use **exclude** to specify which subreddits should NOT be in the results
 
 Example where activities from /r/mealtimevideos and /r/modsupport will not be returned in results
+
+JSON
 ```json
 {
   "count": 100,
@@ -214,4 +290,15 @@ Example where activities from /r/mealtimevideos and /r/modsupport will not be re
   }
 }
 ```
+YAML
+```yaml
+window:
+  count: 100
+  duruation: 90 days
+  satisfyOn: any
+  subreddits:
+    exclude:
+      - mealtimevideos
+      - modsupport
+```
 **Note:** `exclude` will be ignored if `include` is also present.

docs/botAuthentication.md

@@ -12,6 +12,7 @@ At the end of this process you will have this info:
 * clientSecret
 * refreshToken
 * accessToken
+* redirectUri
 
 **Note:** If you already have this information you can skip this guide **but make sure your redirect uri is correct if you plan on using the web interface.**
 
@@ -28,11 +29,11 @@ At the end of this process you will have this info:
 Visit [your reddit preferences](https://www.reddit.com/prefs/apps) and at the bottom of the page go through the **create an(other) app** process.
 * Give it a **name**
 * Choose **web app**
-* If you know what you will use for **redirect uri** go ahead and use it, otherwise use **http://localhost:8085** for now
+* If you know what you will use for **redirect uri** go ahead and use it, otherwise use **http://localhost:8085/callback**
 
 Click **create app**.
 
-Then write down your **Client ID, Client Secret, and redirect uri** somewhere (or keep this webpage open)
+Then write down your **Client ID, Client Secret, and Redirect Uri** somewhere (or keep this webpage open)
 
 # Authenticate Your Bot Account
 
@@ -42,18 +43,31 @@ There are **two ways** you can authenticate your bot account. It is recommended
 
 This method will use CM's built in oauth flow. It is recommended because it will ensure your bot is authenticated with the correct oauth permissions.
 
-### Start CM with Client ID/Secret
+### Start CM with Client ID/Secret and Operator
 
-Start the application while providing the **Client ID** and **Client Secret** you received. Refer to the [operator config guide](/docs/operatorConfiguration.md) if you need help with this.
+Start the application and provide these to your configuration:
+
+* **Client ID** 
+* **Client Secret** 
+* **Redirect URI**
+* **Operator** 
+
+It is important you define **Operator** because the auth route is **protected.** You must login to the application in order to access the route.
+
+Refer to the [operator config guide](/docs/operatorConfiguration.md) if you need help with this.
 
 Examples:
 
-* CLI - `node src/index.js --clientId=myId --clientSecret=mySecret`
-* Docker - `docker run -e "CLIENT_ID=myId" -e "CLIENT_SECRET=mySecret" foxxmd/context-mod`
+* CLI - `node src/index.js --clientId=myId --clientSecret=mySecret --redirectUri="http://localhost:8085/callback" --operator=FoxxMD`
+* Docker - `docker run -e "CLIENT_ID=myId" -e "CLIENT_SECRET=mySecret" -e "OPERATOR=FoxxMD" -e "REDIRECT_URI=http://localhost:8085/callback" foxxmd/context-mod`
 
-Then open the CM web interface (default is [http://localhost:8085](http://localhost:8085))
+### Create An Auth Invite
 
-Follow the directions in the helper to finish authenticating your bot and get your credentials (Access Token and Refresh Token)
+Then open the CM web interface (default is [http://localhost:8085](http://localhost:8085)) and login.
+
+After logging in you should be automatically redirected the auth page. If you are not then visit [http://localhost:8085/auth/helper](http://localhost:8085/auth/helper))
+
+Follow the directions in the helper to create an **auth invite link.** Open this link and then follow the directions to authenticate your bot. At the end of the process you will receive an **Access Token** and **Refresh Token**
 
 ## Aardvark OAuth Helper
 
@@ -88,6 +102,7 @@ At the end of the last step you chose you should now have this information saved
 * clientSecret
 * refreshToken
 * accessToken
+* redirectUri
 
 This is all the information you need to run your bot with CM.
 

docs/examples/README.md

@@ -16,8 +16,12 @@ This directory contains example of valid, ready-to-go configurations for Context
   * [Repeat Activity](/docs/examples/repeatActivity)
   * [History](/docs/examples/history)
   * [Author](/docs/examples/author)
+  * [Regex](/docs/examples/regex)
+  * [Repost](/docs/examples/repost)
+  * [Author and post flairs](/docs/examples/onlyfansFlair)
 * [Toolbox User Notes](/docs/examples/userNotes)
 * [Advanced Concepts](/docs/examples/advancedConcepts)
+  * [Flow Control](/docs/examples/advancedConcepts/flowControl.md)
   * [Rule Sets](/docs/examples/advancedConcepts/ruleSets.json5)
   * [Name Rules](/docs/examples/advancedConcepts/ruleNameReuse.json5)
   * [Check Ordering](/docs/examples/advancedConcepts)

docs/examples/advancedConcepts/README.md

@@ -1,12 +1,14 @@
 ### Named Rules
 
-See [ruleNameReuse.json5](/docs/examples/advancedConcepts/ruleNameReuse.json5)
+See **Rule Name Reuse Examples [YAML](/docs/examples/advancedConcepts/ruleNameReuse.yaml) | [JSON](/docs/examples/advancedConcepts/ruleNameReuse.json5)**
 
-### Check Order
+### Check Order and Flow Control
 
 Checks are run in the order they appear in your configuration, therefore you should place your highest requirement/severe action checks at the top and lowest requirement/moderate actions at the bottom.
 
-This is so that if an Activity warrants a more serious reaction that Check is triggered first rather than having a lower requirement check with less severe actions triggered and causing all subsequent Checks to be skipped.
+This is so that if an Activity warrants a more serious reaction that Check is triggered first rather than having a lower requirement check with less severe actions triggered and causing all subsequent Checks to be skipped. 
+
+This behavior can also be controlled modified using [Flow Control](/docs/examples/advancedConcepts/flowControl.md)
 
 * Attribution >50% AND Repeat Activity 8x AND Recent Activity in 2 subs => remove submission + ban
 * Attribution >20% AND Repeat Activity 4x AND Recent Activity in 5 subs => remove submission + flair user restricted
@@ -23,7 +25,7 @@ The `rules` array on a `Checks` can contain both `Rule` objects and `RuleSet` ob
 
 A **Rule Set** is a "nested" set of `Rule` objects with a passing condition specified. These allow you to create more complex trigger behavior by combining multiple rules. 
 
-See **[ruleSets.json5](/docs/examples/advancedConcepts/ruleSets.json5)** for a complete example as well as consulting the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRuleSetJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json).
+See **ruleSets [YAML](/docs/examples/advancedConcepts/ruleSets.yaml) | [JSON](/docs/examples/advancedConcepts/ruleSets.json5)** for a complete example as well as consulting the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRuleSetJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json).
 
 ### Rule Order
 

docs/examples/advancedConcepts/flowControl.md

@@ -0,0 +1,228 @@
+Context Mod's behavior after a **Check** has been processed can be configured by a user. This allows a subreddit to control exactly what Runs/Checks will be processed based on the outcome (triggered or not) of a Check.
+
+# Table of Contents
+
+- [Post-Check Properties](#post-check-properties)
+    * [State](#state)
+    * [Behavior](#behavior)
+        + [Next](#next)
+        + [Next Run](#next-run)
+        + [Stop](#stop)
+        + [Goto](#goto)
+            - [Goto Syntax](#goto-syntax)
+- [Default Behaviors](#default-behaviors)
+    * [Defining Default Behaviors](#defining-default-behaviors)
+- [Examples](#examples)
+
+# Post-Check Properties
+
+## State
+
+When a Check is finished processing it can be in one of two states:
+
+* **Triggered** -- The **Rules** defined in the Check were **triggered** which caused the **Actions** for the Check to be run
+* **Failure** -- The **Rules** defined in the check were **not triggered**, based on the conditions that were set (either from the [Check condition](/docs/README.md#Checks) or [Rule Sets](/docs/examples/advancedConcepts/README.md#Rule-Sets)), and no **Actions** were run
+
+The behavior CM follows is based on which state it is in. The behavior can be specified **by one or both** of these **state properties** on the Check configuration:
+
+* `postTrigger` -- Specifies what behavior to take when the check is **triggered**
+* `postFail` -- Specifies what behavior to take when the check is **not triggered**
+
+## Behavior
+
+There are **four** behaviors CM can take. Both/either **state properties** can be defined with **any behavior.**
+
+### Next
+
+The **Next** behavior tells CM to continue to whatever comes *after the Check that was just processed.* This could be another Check or, if this is the last Check in a Run, the next Run.
+
+NOTE: `next` is the **default behavior** for the `postFail` state
+
+Example
+
+```yaml
+- name: MyCheck
+  # ...
+  postFail: next # if Check is not triggered then CM will start processing AnotherCheck
+  
+- name: AnotherCheck
+  # ...
+```
+
+### Next Run
+
+The **Next Run** behavior tells CM to **skip all remaining Checks in the current Run and start processing the next Run in order.**
+
+NOTE: `nextRun` is the **default behavior** for the `postTrigger` state
+
+Example
+
+```yaml
+runs:
+  - name: MyFirstRun
+    checks:
+      - name: MyCheck
+        # ...
+        postTrigger: nextRun # if Check is triggered then CM will SKIP mySecondCheck and instead start processing MySecondRun
+      - name: MySecondCheck
+        # ...
+        
+  - name: MySecondRun
+    checks:
+      - name: FooCheck
+        # ...
+```
+
+### Stop
+
+The **Stop** behavior tells CM to **stop processing the Activity entirely.** This means all remaining Checks and Runs will not be processed.
+
+Example
+
+```yaml
+runs:
+  - name: MyFirstRun
+    checks:
+      - name: MyCheck
+        # ...
+        postTrigger: stop # if Check is triggered CM will NOT process MySecondCheck OR MySecondRun. The activity is "done" being processed at this point
+      - name: MySecondCheck
+        # ...
+        
+  - name: MySecondRun
+    checks:
+      - name: FooCheck
+        # ...
+```
+
+### Goto
+
+The **Goto** behavior is an **advanced** behavior that allows you to specify that CM should "jump to" a specific place in your configuration, regardless of order/location, and continue processing the Activity from there. It can be used to do things like:
+
+* create a loop/iteration to have CM re-process the Activity on an earlier executed part of your configuration because a later part modified the Activity (flaired, etc...)
+* use a Check as a simplified *switch statement*
+
+**Goto should be use with care.** If you do not fully understand how this mechanism works you should avoid using it as **most** behaviors can be accomplished using the other behaviors. 
+
+As an additional protection **goto depth is limited to 1 by default** which means if a `goto` would be executed more than once during an Activity's lifecycle CM will automatically stop processing that Activity. The `maxGotoDepth` can be raised by the [**Bot Operator**](/docs/gettingStartedOperator.md) per subreddit.
+
+#### Goto Syntax
+
+Location to "jump to" can be specified as:
+
+* **Run** -- `goto:myRunName`
+* **Check inside a different Run** -- `goto:myRunName.aCheckInsideTheRun`
+* **Check inside the current Run** -- `goto:.myCheck`
+
+Example
+
+```yaml
+runs:
+  - name: MyFirstRun
+    checks:
+      - name: FirstCheck
+        # ...
+      - name: MyCheck
+        # ...
+        postTrigger: 'goto:MyThirdRun' # jump to the run MyThirdRun
+        postFail: 'goto:MySecondRun.BuzzCheck' # jump to the Check BuzzCheck inside the Run MySecondRun
+        
+  - name: MySecondRun
+    checks:
+      - name: FooCheck
+        # ...
+      - name: BuzzCheck
+        # ...
+        
+  - name: MyThirdRun
+    checks:
+      - name: BarCheck
+        # ...
+```
+
+# Default Behaviors
+
+It is **not required** to define post-Check behavior. CM uses sane defaults to mimic the behavior of automoderator as well as what is "intuitive" when reading a configuration -- that logic flows from top-to-bottom in the order it was defined. For each Check like this:
+
+```yaml
+- name: MyCheck
+  kind: comment
+  rules: 
+   # ...
+  actions:
+   # ...
+```
+
+`postTrigger` and `postFail` have default behaviors (mentioned in the sections above) that make the Check end up working like this:
+
+```yaml
+- name: MyCheck
+  kind: comment
+  rules: 
+   # ...
+  actions:
+   # ...
+  postTrigger: nextRun # check is triggered and actions were performed, skip remaining checks and go to the next Run
+  postFail: next # check is not triggered and no actions performed, continue to the next check in this Run
+```
+
+**So if you are fine with all Checks running in order until one triggered there is no need to define post-Check behaviors at all.**
+
+## Defining Default Behaviors
+
+Defining `postTrigger` and/or `postFail` on a **Run** will set the default behavior for any **Checks** in the Run that **do not have an explicit behavior set.**
+
+```yaml
+runs:
+  - name: MyFirstRun
+    postTrigger: stop # all Checks without postTrigger defined will have 'stop' as their behavior
+    checks:
+      - name: FooCheck # postTrigger is 'stop' since it is not defined
+        # ...
+      - name: BarCheck
+        # ...
+        postTrigger: next # overrides default behavior
+```
+
+# Examples
+
+One **Run** with **default behavior** (no post-Check behavior explicitly defined)
+
+```mermaid
+flowchart TB
+    subgraph spam ["(Run) Spam"]
+        b1["(Check) self-promotion"] -- "postFail: next" --> b2
+        b2["(Check) repeat spam"] -- "postFail: next" --> b3
+        b3["(Check) Good user"]
+    end
+    b1 -- "postTrigger: nextRun" --> finish
+    b2 -- "postTrigger: nextRun" --> finish
+    b3 -- "postFail: next" --> finish
+    b3 -- "postTrigger: nextRun" --> finish
+    finish[Processing Finished]
+```
+
+Two **Runs** with **default behavior** (no post-Check behavior explicitly defined)
+
+```mermaid
+flowchart TB
+    subgraph flair ["(Run) Flairing"]
+        a1["(Check) Flair Submission based on history"]-- "postFail: next" -->a2
+        a2["(Check) Flair Submission based on user profile"] -- "postFail: next" --> a3
+        a3["(Check) Flair Submission based on self text"]
+    end
+    a1 -- "postTrigger: nextRun" --> b1
+    a2 -- "postTrigger: nextRun" --> b1
+    a3 -- "postFail: next" --> b1
+    a3 -- "postTrigger: nextRun" --> b1
+    subgraph spam ["(Run) Spam"]
+        b1["(Check) self-promotion"] -- "postFail: next" -->b2
+        b2["(Check) repeat spam"] -- "postFail: next" -->b3
+        b3["(Check) Good user"]
+    end
+    b1 -- "postTrigger: nextRun" --> finish
+    b2 -- "postTrigger: nextRun" --> finish
+    b3 -- "postFail: next" --> finish
+    b3 -- "postTrigger: nextRun" --> finish
+    finish[Processing Finished]
+```

docs/examples/advancedConcepts/flowControl.yaml

@@ -0,0 +1,96 @@
+runs:
+  - name: flairAndCategory
+
+    # Runs inherit the same filters as checks/rules/actions
+    # If these filters fail the Run is skipped and CM processes the next run in order
+    #    authorIs:
+    #    itemIs:
+
+    # Set the default behavior for check trigger/fail
+    #    postTrigger:
+    #    postFail:
+
+    # Defaults can also be set for check authorIs/itemIs
+    # same as at operator/subreddit level - any defined here will override "higher" defaults
+    #    filterCriteriaDefaults:
+
+    checks:
+      - name: goodUserFlair
+        description: flair user if they have decent history in sub
+        kind: submission
+        authorIs:
+          exclude:
+            - flairText: 'Good User'
+        rules:
+          - kind: recentActivity
+            thresholds:
+              - threshold: '> 5'
+                karma: '> 10'
+                subreddits:
+                  - mySubreddit
+        actions:
+          - kind: userflair
+            text: 'Good User'
+        # post-behavior after a check has run. Either the check is TRIGGERED or FAIL
+        # there are 4 possible behaviors for each post-behavior type:
+        #
+        # 'next' => Continue to next check in order
+        # 'nextRun' => Exit the current Run (skip all remaining Checks) and go to the next Run in order
+        # 'stop' => Exit the current Run and finish activity processing immediately (skip all remaining Runs)
+        # 'goto:run[.check]' => Specify a run[.check] to jump to. This can be anywhere in your config. CM will continue to process in order from the specified point.
+        #
+        # GOTO syntax --
+        # 'goto:normalFilters' => go to run "normalFilters"
+        # 'goto:normalFilters.myCheck' => go to run "normalFilters" and start at check "myCheck"
+        # 'goto:.goodUserFlair' => go to check 'goodUserFlair' IN THE SAME RUN currently processing
+        #
+
+        # this means if the check triggers then continue to 'good submission flair'
+        postTrigger: next # default is 'nextRun'
+      #        postFail: # default is 'next'
+
+      - name: good submission flair
+        description: flair submission if from good user
+        kind: submission
+        authorIs:
+          include:
+            - flairText: 'Good User'
+        actions:
+          - kind: flair
+            text: 'Trusted Source'
+          - kind: approve
+        # this means if the check is triggered then stop processing the activity entirely
+        postTrigger: stop
+
+  - name: Determine Suspect
+    checks:
+      - name: is suspect
+        kind: submission
+        rules:
+          - kind: recentActivity
+            thresholds:
+              - subreddits:
+                  - over_18: true
+        actions:
+        # do some actions
+
+        # if check is triggered then go to run 'suspectFilters'
+        postTrigger: 'goto:suspectFilters'
+        # if check is not triggered then go to run 'normalFilters'
+        postFail: 'goto:normalFilters'
+
+  - name: suspectFilters
+    postTrigger: stop
+    authorIs:
+      exclude:
+        - flairText: 'Good User'
+    checks:
+    # some checks for users that are suspicious
+
+
+  - name: normalFilters
+    authorIs:
+      exclude:
+        - flairText: 'Good User'
+    checks:
+    # some checks for general activities

docs/examples/advancedConcepts/ruleNameReuse.json5

@@ -1,75 +1,79 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Auto Remove SP Karma",
-      "description": "Remove submission because author has self-promo >10% and posted in karma subs recently",
-      "kind": "submission",
-      "rules": [
-        // named rules can be referenced at any point in the configuration (where they occur does not matter)
-        // and can be used in any Check
-        // Note: rules do not transfer between subreddit configurations
-        "freekarmasub",
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          "criteria": [
+          "name": "Auto Remove SP Karma",
+          "description": "Remove submission because author has self-promo >10% and posted in karma subs recently",
+          "kind": "submission",
+          "rules": [
+            // named rules can be referenced at any point in the configuration (where they occur does not matter)
+            // and can be used in any Check
+            // Note: rules do not transfer between subreddit configurations
+            "freekarmasub",
             {
-              "threshold": "> 10%",
-              "window": "90 days"
+              "name": "attr10all",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
+            }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
             },
             {
-              "threshold": "> 10%",
-              "window": 100
+              "kind": "comment",
+              "content": "Your submission was removed because you are over reddit's threshold for self-promotion and recently posted this content in a karma sub"
             }
-          ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "remove"
+          ]
         },
         {
-          "kind": "comment",
-          "content": "Your submission was removed because you are over reddit's threshold for self-promotion and recently posted this content in a karma sub"
-        }
-      ]
-    },
-    {
-      "name": "Free Karma On Submission Alert",
-      "description": "Check if author has posted this submission in 'freekarma' subreddits",
-      "kind": "submission",
-      "rules": [
-        {
-          // rules can be re-used throughout a configuration by referencing them by name
-          //
-          // The rule name itself can only contain spaces, hyphens and underscores
-          // The value used to reference it will have all of these removed, and lower-cased
-          //
-          // so to reference this rule use the value 'freekarmasub'
-          "name": "Free_Karma-SUB",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "useSubmissionAsReference":true,
-          "thresholds": [
+          "name": "Free Karma On Submission Alert",
+          "description": "Check if author has posted this submission in 'freekarma' subreddits",
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "upvote"
-              ]
+              // rules can be re-used throughout a configuration by referencing them by name
+              //
+              // The rule name itself can only contain spaces, hyphens and underscores
+              // The value used to reference it will have all of these removed, and lower-cased
+              //
+              // so to reference this rule use the value 'freekarmasub'
+              "name": "Free_Karma-SUB",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "useSubmissionAsReference":true,
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "upvote"
+                  ]
+                }
+              ],
+              "window": "7 days"
             }
           ],
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
-        }
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
+            }
+          ]
+        },
       ]
-    },
+    }
   ]
 }

docs/examples/advancedConcepts/ruleNameReuse.yaml

@@ -0,0 +1,53 @@
+runs:
+  - checks:
+      - name: Auto Remove SP Karma
+        description: >-
+          Remove submission because author has self-promo >10% and posted in karma
+          subs recently
+        kind: submission
+        rules:
+          # named rules can be referenced at any point in the configuration (where they occur does not matter)
+          # and can be used in any Check
+          # Note: rules do not transfer between subreddit configurations
+          - freekarmasub
+          - name: attr10all
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+        actions:
+          - kind: remove
+          - kind: comment
+            content: >-
+              Your submission was removed because you are over reddit's threshold
+              for self-promotion and recently posted this content in a karma sub
+      - name: Free Karma On Submission Alert
+        description: Check if author has posted this submission in 'freekarma' subreddits
+        kind: submission
+        rules:
+          # rules can be re-used throughout a configuration by referencing them by name
+          #
+          # The rule name itself can only contain spaces, hyphens and underscores
+          # The value used to reference it will have all of these removed, and lower-cased
+          #
+          # so to reference this rule use the value 'freekarmasub'
+          - name: Free_Karma-SUB
+            kind: recentActivity
+            lookAt: submissions
+            useSubmissionAsReference: true
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - upvote
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Submission posted {{rules.freekarmasub.totalCount}} times in karma
+              {{rules.freekarmasub.subCount}} subs over
+              {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}

docs/examples/advancedConcepts/ruleSets.json5

@@ -1,84 +1,88 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo All or low comment",
-      "description": "SP >10% of all activities or >10% of submissions with low comment engagement",
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          // this attribution rule is looking at all activities
-          //
-          // we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
-          "name": "attr10all",
-          "kind": "attribution",
-          "criteria": [
-            {
-              "threshold": "> 10%",
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "window": 100
-            }
-          ],
-        },
-        {
-          // this is a **Rule Set**
-          //
-          // it is made up of "nested" rules with a pass condition (AND/OR)
-          // if the nested rules pass the condition then the Rule Set triggers the Check
-          //
-          // AND = all nested rules must be triggered to make the Rule Set trigger
-          // AND = any of the nested Rules will be the Rule Set trigger
-          "condition": "AND",
-          // in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
-          // and combine it with a History rule looking for low comment engagement
-          // to make a "higher" requirement Rule Set our of two low requirement Rules
+          "name": "Self Promo All or low comment",
+          "description": "SP >10% of all activities or >10% of submissions with low comment engagement",
+          "kind": "submission",
           "rules": [
             {
-              "name": "attr20sub",
+              // this attribution rule is looking at all activities
+              //
+              // we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
+              "name": "attr10all",
               "kind": "attribution",
               "criteria": [
                 {
                   "threshold": "> 10%",
-                  "thresholdOn": "submissions",
                   "window": "90 days"
                 },
                 {
                   "threshold": "> 10%",
-                  "thresholdOn": "submissions",
                   "window": 100
                 }
               ],
-              "lookAt": "media"
             },
             {
-              "name": "lowOrOpComm",
-              "kind": "history",
-              "criteriaJoin": "OR",
-              "criteria": [
+              // this is a **Rule Set**
+              //
+              // it is made up of "nested" rules with a pass condition (AND/OR)
+              // if the nested rules pass the condition then the Rule Set triggers the Check
+              //
+              // AND = all nested rules must be triggered to make the Rule Set trigger
+              // AND = any of the nested Rules will be the Rule Set trigger
+              "condition": "AND",
+              // in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
+              // and combine it with a History rule looking for low comment engagement
+              // to make a "higher" requirement Rule Set our of two low requirement Rules
+              "rules": [
                 {
-                  "window": "90 days",
-                  "comment": "< 50%"
+                  "name": "attr20sub",
+                  "kind": "attribution",
+                  "criteria": [
+                    {
+                      "threshold": "> 10%",
+                      "thresholdOn": "submissions",
+                      "window": "90 days"
+                    },
+                    {
+                      "threshold": "> 10%",
+                      "thresholdOn": "submissions",
+                      "window": 100
+                    }
+                  ],
+                  "lookAt": "media"
                 },
                 {
-                  "window": "90 days",
-                  "comment": "> 40% OP"
+                  "name": "lowOrOpComm",
+                  "kind": "history",
+                  "criteriaJoin": "OR",
+                  "criteria": [
+                    {
+                      "window": "90 days",
+                      "comment": "< 50%"
+                    },
+                    {
+                      "window": "90 days",
+                      "comment": "> 40% OP"
+                    }
+                  ]
                 }
               ]
             }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            },
+            {
+              "kind": "comment",
+              "content": "Your submission was removed because you are over reddit's threshold for self-promotion or exhibit low comment engagement"
+            }
           ]
-        }
-      ],
-      "actions": [
-        {
-          "kind": "remove"
         },
-        {
-          "kind": "comment",
-          "content": "Your submission was removed because you are over reddit's threshold for self-promotion or exhibit low comment engagement"
-        }
       ]
-    },
-  ],
+    }
+  ]
 }

docs/examples/advancedConcepts/ruleSets.yaml

@@ -0,0 +1,54 @@
+runs:
+  - checks:
+      - name: Self Promo All or low comment
+        description: >-
+          SP >10% of all activities or >10% of submissions with low comment
+          engagement
+        kind: submission
+        rules:
+          # this attribution rule is looking at all activities
+          #
+          # we want want this one rule to trigger the check because >10% of all activity (submission AND comments) is a good requirement
+          - name: attr10all
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+            # this is a RULE SET
+            #
+            # it is made up of "nested" rules with a pass condition (AND/OR)
+            # if the nested rules pass the condition then the Rule Set triggers the Check
+            #
+            # AND = all nested rules must be triggered to make the Rule Set trigger
+            # AND = any of the nested Rules will be the Rule Set trigger
+          - condition: AND
+            # in this check we use an Attribution >10% on ONLY submissions, which is a lower requirement then the above attribution rule
+            # and combine it with a History rule looking for low comment engagement
+            # to make a "higher" requirement Rule Set our of two low requirement Rules
+            rules:
+              - name: attr20sub
+                kind: attribution
+                criteria:
+                  - threshold: '> 10%'
+                    thresholdOn: submissions
+                    window: 90 days
+                  - threshold: '> 10%'
+                    thresholdOn: submissions
+                    window: 100
+                lookAt: media
+              - name: lowOrOpComm
+                kind: history
+                criteriaJoin: OR
+                criteria:
+                  - window: 90 days
+                    comment: < 50%
+                  - window: 90 days
+                    comment: '> 40% OP'
+        actions:
+          - kind: remove
+          - kind: comment
+            content: >-
+              Your submission was removed because you are over reddit's threshold
+              for self-promotion or exhibit low comment engagement

docs/examples/attribution/README.md

@@ -10,5 +10,5 @@ Consult the [schema](https://json-schema.app/view/%23/%23%2Fdefinitions%2FCheckJ
 
 ### Examples
 
-* [Self Promotion as percentage of all Activities](/docs/examples/attribution/redditSelfPromoAll.json5) - Check if Author is submitting much more than they comment.
-* [Self Promotion as percentage of Submissions](/docs/examplesm/attribution/redditSelfPromoSubmissionsOnly.json5) - Check if any of Author's aggregated submission origins are >10% of their submissions
+* Self Promotion as percentage of all Activities [YAML](/docs/examples/attribution/redditSelfPromoAll.yaml) | [JSON](/docs/examples/attribution/redditSelfPromoAll.json5) - Check if Author is submitting much more than they comment.
+* Self Promotion as percentage of Submissions [YAML](/docs/examples/attribution/redditSelfPromoSubmissionsOnly.yaml) | [JSON](/docs/examplesm/attribution/redditSelfPromoSubmissionsOnly.json5) - Check if any of Author's aggregated submission origins are >10% of their submissions

docs/examples/attribution/redditSelfPromoAll.json5

@@ -1,37 +1,41 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Activities",
-      "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          // criteria defaults to OR -- so either of these criteria will trigger the rule
-          "criteria": [
+          "name": "Self Promo Activities",
+          "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // threshold can be a percent or an absolute number
-              "threshold": "> 10%",
-              // The default is "all" -- calculate percentage of entire history (submissions & comments)
-              // "thresholdOn": "all",
+              "name": "attr10all",
+              "kind": "attribution",
+              // criteria defaults to OR -- so either of these criteria will trigger the rule
+              "criteria": [
+                {
+                  // threshold can be a percent or an absolute number
+                  "threshold": "> 10%",
+                  // The default is "all" -- calculate percentage of entire history (submissions & comments)
+                  // "thresholdOn": "all",
 
-              // look at last 90 days of Author's activities (comments and submissions)
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              // look at Author's last 100 activities (comments and submissions)
-              "window": 100
+                  // look at last 90 days of Author's activities (comments and submissions)
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  // look at Author's last 100 activities (comments and submissions)
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.attr10all.largestPercent}}% of {{rules.attr10all.activityTotal}} items over {{rules.attr10all.window}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr10all.largestPercent}}% of {{rules.attr10all.activityTotal}} items over {{rules.attr10all.window}}"
+            }
+          ]
         }
       ]
     }

docs/examples/attribution/redditSelfPromoAll.yaml

@@ -0,0 +1,28 @@
+runs:
+  - checks:
+      - name: Self Promo Activities
+        description: >-
+          Check if any of Author's aggregated submission origins are >10% of entire
+          history
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: attr10all
+            kind: attribution
+            # criteria defaults to OR -- so either of these criteria will trigger the rule
+            criteria:
+              - threshold: '> 10%' # threshold can be a percent or an absolute number
+                # The default is "all" -- calculate percentage of entire history (submissions & comments)
+                #thresholdOn: all
+                #
+                # look at last 90 days of Author's activities (comments and submissions)
+                window: 90 days
+              - threshold: '> 10%'
+                # look at Author's last 100 activities (comments and submissions)
+                window: 100
+        actions:
+          - kind: report
+            content: >-
+              {{rules.attr10all.largestPercent}}% of
+              {{rules.attr10all.activityTotal}} items over
+              {{rules.attr10all.window}}

docs/examples/attribution/redditSelfPromoSubmissionOnly.yaml

@@ -0,0 +1,25 @@
+runs:
+  - checks:
+      - name: Self Promo Submissions
+        description: >-
+          Check if any of Author's aggregated submission origins are >10% of their
+          submissions
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: attr10sub
+            kind: attribution
+            # criteria defaults to OR -- so either of these criteria will trigger the rule
+            criteria:
+              - threshold: '> 10%' # threshold can be a percent or an absolute number
+                thresholdOn: submissions # calculate percentage of submissions, rather than entire history (submissions & comments)
+                window: 90 days # look at last 90 days of Author's activities (comments and submissions)
+              - threshold: '> 10%'
+                thresholdOn: submissions
+                window: 100 # look at Author's last 100 activities (comments and submissions)
+        actions:
+          - kind: report
+            content: >-
+              {{rules.attr10sub.largestPercent}}% of
+              {{rules.attr10sub.activityTotal}} items over
+              {{rules.attr10sub.window}}

docs/examples/attribution/redditSelfPromoSubmissionsOnly.json5

@@ -1,38 +1,42 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Submissions",
-      "description": "Check if any of Author's aggregated submission origins are >10% of their submissions",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10sub",
-          "kind": "attribution",
-          // criteria defaults to OR -- so either of these criteria will trigger the rule
-          "criteria": [
+          "name": "Self Promo Submissions",
+          "description": "Check if any of Author's aggregated submission origins are >10% of their submissions",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // threshold can be a percent or an absolute number
-              "threshold": "> 10%",
-              // calculate percentage of submissions, rather than entire history (submissions & comments)
-              "thresholdOn": "submissions",
+              "name": "attr10sub",
+              "kind": "attribution",
+              // criteria defaults to OR -- so either of these criteria will trigger the rule
+              "criteria": [
+                {
+                  // threshold can be a percent or an absolute number
+                  "threshold": "> 10%",
+                  // calculate percentage of submissions, rather than entire history (submissions & comments)
+                  "thresholdOn": "submissions",
 
-              // look at last 90 days of Author's activities (comments and submissions)
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "thresholdOn": "submissions",
-              // look at Author's last 100 activities (comments and submissions)
-              "window": 100
+                  // look at last 90 days of Author's activities (comments and submissions)
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "thresholdOn": "submissions",
+                  // look at Author's last 100 activities (comments and submissions)
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.attr10sub.largestPercent}}% of {{rules.attr10sub.activityTotal}} items over {{rules.attr10sub.window}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr10sub.largestPercent}}% of {{rules.attr10sub.activityTotal}} items over {{rules.attr10sub.window}}"
+            }
+          ]
         }
       ]
     }

docs/examples/author/README.md

@@ -18,10 +18,10 @@ Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorRule
 ### Examples
 
 * Basic examples
-    * [Flair new user Submission](/docs/examples/author/flairNewUserSubmission.json5) - If the Author does not have the `vet` flair then flair the Submission with `New User`
-    * [Flair vetted user Submission](/docs/examples/author/flairNewUserSubmission.json5) - If the Author does have the `vet` flair then flair the Submission with `Vetted`
+    * Flair new user Submission [YAML](/docs/examples/author/flairNewUserSubmission.yaml) | [JSON](/docs/examples/author/flairNewUserSubmission.json5) - If the Author does not have the `vet` flair then flair the Submission with `New User`
+    * Flair vetted user Submission [YAML](/docs/examples/author/flairNewUserSubmission.yaml) | [JSON](/docs/examples/author/flairNewUserSubmission.json5) - If the Author does have the `vet` flair then flair the Submission with `Vetted`
 * Used with other Rules
-    * [Ignore vetted user](/docs/examples/author/flairNewUserSubmission.json5) - Short-circuit the Check if the Author has the `vet` flair
+    * Ignore vetted user [YAML](/docs/examples/author/flairNewUserSubmission.yaml) | [JSON](/docs/examples/author/flairNewUserSubmission.json5) - Short-circuit the Check if the Author has the `vet` flair
     
 ## Filter
 
@@ -35,4 +35,4 @@ All **Rules** and **Checks** have an optional `authorIs` property that takes an
 
 ### Examples
 
-* [Skip recent activity check based on author](/docs/examples/author/authorFilter.json5) - Skip a Recent Activity check for a set of subreddits if the Author of the Submission has any set of flairs.
+* Skip recent activity check based on author [YAML](/docs/examples/author/authorFilter.yaml) | [JSON](/docs/examples/author/authorFilter.json5) - Skip a Recent Activity check for a set of subreddits if the Author of the Submission has any set of flairs.

docs/examples/author/authorFilter.json5

@@ -1,67 +1,71 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Karma/Meme Sub Activity",
-      "description": "Report on karma sub activity or meme sub activity if user isn't a memelord",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "thresholds": [
+          "name": "Karma/Meme Sub Activity",
+          "description": "Report on karma sub activity or meme sub activity if user isn't a memelord",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-              ]
-            }
-          ],
-          "window": "7 days"
-        },
-        {
-          "name": "noobmemer",
-          "kind": "recentActivity",
-          // authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
-          // if *all* Rules for a Check are skipped due to authors filter then the Check will fail
-          "authorIs": {
-            // each property (include/exclude) can contain multiple AuthorCriteria
-            // if any AuthorCriteria passes its test the Rule is skipped
-            //
-            // for an AuthorCriteria to pass all properties present on it must pass
-            //
-            // if "include" is present it will always run and exclude will be skipped
-            // "include:" []
-            "exclude": [
-              // for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
-              {
-                "flairText": ["Supreme Memer"],
-                "names": ["user1","user2"]
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                  ]
+                }
+              ],
+              "window": "7 days"
+            },
+            {
+              "name": "noobmemer",
+              "kind": "recentActivity",
+              // authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
+              // if *all* Rules for a Check are skipped due to authors filter then the Check will fail
+              "authorIs": {
+                // each property (include/exclude) can contain multiple AuthorCriteria
+                // if any AuthorCriteria passes its test the Rule is skipped
+                //
+                // for an AuthorCriteria to pass all properties present on it must pass
+                //
+                // if "include" is present it will always run and exclude will be skipped
+                // "include:" []
+                "exclude": [
+                  // for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
+                  {
+                    "flairText": ["Supreme Memer"],
+                    "names": ["user1","user2"]
+                  },
+                  {
+                    // for this to pass the Author of the Submission must not have the flair "Decent Memer"
+                    "flairText": ["Decent Memer"]
+                  }
+                ]
               },
-              {
-                // for this to pass the Author of the Submission must not have the flair "Decent Memer"
-                "flairText": ["Decent Memer"]
-              }
-            ]
-          },
-          "lookAt": "submissions",
-          "thresholds": [
-            {
-              "threshold": ">= 1",
-              "subreddits": [
-                "dankmemes",
-              ]
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "dankmemes",
+                  ]
+                }
+              ],
+              "window": "7 days"
             }
           ],
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has posted in free karma sub, or in /r/dankmemes and does not have meme flair in this subreddit"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has posted in free karma sub, or in /r/dankmemes and does not have meme flair in this subreddit"
+            }
+          ]
         }
       ]
     }

docs/examples/author/authorFilter.yaml

@@ -0,0 +1,49 @@
+runs:
+  - checks:
+      - name: Karma/Meme Sub Activity
+        description: Report on karma sub activity or meme sub activity if user isn't a memelord
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+            window: 7 days
+          - name: noobmemer
+            kind: recentActivity
+            # authors filter will be checked before a rule is run. If anything passes then the Rule is skipped -- it is not failed or triggered.
+            # if *all* Rules for a Check are skipped due to authors filter then the Check will fail
+            authorIs:
+              # each property (include/exclude) can contain multiple AuthorCriteria
+              # if any AuthorCriteria passes its test the Rule is skipped
+              #
+              # for an AuthorCriteria to pass all properties present on it must pass
+              #
+              # if include is present it will always run and exclude will be skipped
+              #-include:
+              exclude:
+                # for this to pass the Author of the Submission must not have the flair "Supreme Memer" and have the name "user1" or "user2"
+                - flairText:
+                    - Supreme Memer
+                  names:
+                    - user1
+                    - user2
+                  # for this to pass the Author of the Submission must not have the flair "Decent Memer"
+                - flairText:
+                    - Decent Memer
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - dankmemes
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Author has posted in free karma sub, or in /r/dankmemes and does not
+              have meme flair in this subreddit

docs/examples/author/flairNewUserSubmission.json5

@@ -1,28 +1,32 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Flair New User Sub",
-      "description": "Flair submission as sketchy if user does not have vet flair",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "newflair",
-          "kind": "author",
-          // rule will trigger if Author does not have "vet" flair text
-          "exclude": [
+          "name": "Flair New User Sub",
+          "description": "Flair submission as sketchy if user does not have vet flair",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "flairText": ["vet"]
+              "name": "newflair",
+              "kind": "author",
+              // rule will trigger if Author does not have "vet" flair text
+              "exclude": [
+                {
+                  "flairText": ["vet"]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "flair",
+              "text": "New User",
+              "css": "orange"
             }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "flair",
-          "text": "New User",
-          "css": "orange"
-        }
       ]
     }
   ]

docs/examples/author/flairNewUserSubmission.yaml

@@ -0,0 +1,17 @@
+runs:
+  - checks:
+      - name: Flair New User Sub
+        description: Flair submission as sketchy if user does not have vet flair
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: newflair
+            kind: author
+            # rule will trigger if Author does not have "vet" flair text
+            exclude:
+              - flairText:
+                  - vet
+        actions:
+          - kind: flair
+            text: New User
+            css: orange

docs/examples/author/flairVettedUserSubmission.json5

@@ -1,28 +1,32 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Flair Vetted User Submission",
-      "description": "Flair submission as Approved if user has vet flair",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "newflair",
-          "kind": "author",
-          // rule will trigger if Author has "vet" flair text
-          "include": [
+          "name": "Flair Vetted User Submission",
+          "description": "Flair submission as Approved if user has vet flair",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "flairText": ["vet"]
+              "name": "newflair",
+              "kind": "author",
+              // rule will trigger if Author has "vet" flair text
+              "include": [
+                {
+                  "flairText": ["vet"]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "flair",
+              "text": "Vetted",
+              "css": "green"
             }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "flair",
-          "text": "Vetted",
-          "css": "green"
-        }
       ]
     }
   ]

docs/examples/author/flairVettedUserSubmission.yaml

@@ -0,0 +1,17 @@
+runs:
+  - checks:
+      - name: Flair Vetted User Submission
+        description: Flair submission as Approved if user has vet flair
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: newflair
+            kind: author
+            # rule will trigger if Author has "vet" flair text
+            include:
+              - flairText:
+                  - vet
+        actions:
+          - kind: flair
+            text: Vetted
+            css: green

docs/examples/author/ignoreVettedUser.json5

@@ -1,73 +1,77 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "non-vetted karma/meme activity",
-      "description": "Report if Author has SP and has recent karma/meme sub activity and isn't vetted",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          // The Author Rule is best used in conjunction with other Rules --
-          // instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
-          // you can write one Author Rule and make it fail on the required criteria
-          // so that the check fails and Actions don't run
-          "name": "nonvet",
-          "kind": "author",
-          "exclude": [
+          "name": "non-vetted karma/meme activity",
+          "description": "Report if Author has SP and has recent karma/meme sub activity and isn't vetted",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "flairText": ["vet"]
-            }
-          ]
-        },
-        {
-          "name": "attr10",
-          "kind": "attribution",
-          "criteria": [
-            {
-              "threshold": "> 10%",
-              "window": "90 days"
+              // The Author Rule is best used in conjunction with other Rules --
+              // instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
+              // you can write one Author Rule and make it fail on the required criteria
+              // so that the check fails and Actions don't run
+              "name": "nonvet",
+              "kind": "author",
+              "exclude": [
+                {
+                  "flairText": ["vet"]
+                }
+              ]
             },
             {
-              "threshold": "> 10%",
-              "window": 100
-            }
-          ],
-        },
-        {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "thresholds": [
+              "name": "attr10",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
+            },
             {
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-              ]
-            }
-          ],
-          "window": "7 days"
-        },
-        {
-          "name": "memes",
-          "kind": "recentActivity",
-          "lookAt": "submissions",
-          "thresholds": [
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                  ]
+                }
+              ],
+              "window": "7 days"
+            },
             {
-              "threshold": ">= 3",
-              "subreddits": [
-                "dankmemes",
-              ]
+              "name": "memes",
+              "kind": "recentActivity",
+              "lookAt": "submissions",
+              "thresholds": [
+                {
+                  "threshold": ">= 3",
+                  "subreddits": [
+                    "dankmemes",
+                  ]
+                }
+              ],
+              "window": "7 days"
             }
           ],
-          "window": "7 days"
-        }
-      ],
-      // will NOT run if the Author for this Submission has the flair "vet"
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has posted in free karma or meme subs recently"
+          // will NOT run if the Author for this Submission has the flair "vet"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has posted in free karma or meme subs recently"
+            }
+          ]
         }
       ]
     }

docs/examples/author/ignoreVettedUser.yaml

@@ -0,0 +1,46 @@
+runs:
+  - checks:
+      - name: non-vetted karma/meme activity
+        description: >-
+          Report if Author has SP and has recent karma/meme sub activity and isn't
+          vetted
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          # The Author Rule is best used in conjunction with other Rules --
+          # instead of having to write an AuthorFilter for every Rule where you want to skip it based on Author criteria
+          # you can write one Author Rule and make it fail on the required criteria
+          # so that the check fails and Actions don't run
+          - name: nonvet
+            kind: author
+            exclude:
+              - flairText:
+                  - vet
+          - name: attr10
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+          - name: freekarma
+            kind: recentActivity
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+            window: 7 days
+          - name: memes
+            kind: recentActivity
+            lookAt: submissions
+            thresholds:
+              - threshold: '>= 3'
+                subreddits:
+                  - dankmemes
+            window: 7 days
+        # will NOT run if the Author for this Submission has the flair "vet"
+        actions:
+          - kind: report
+            content: Author has posted in free karma or meme subs recently

docs/examples/history/README.md

@@ -9,5 +9,5 @@ Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FHistoryJSO
 
 ### Examples
 
-* [Low Comment Engagement](/docs/examples/history/lowEngagement.json5) - Check if Author is submitting much more than they comment.
-* [OP Comment Engagement](/docs/examples/history/opOnlyEngagement.json5) - Check if Author is mostly engaging only in their own content
+* Low Comment Engagement [YAML](/docs/examples/history/lowEngagement.yaml) | [JSON](/docs/examples/history/lowEngagement.json5) - Check if Author is submitting much more than they comment.
+* OP Comment Engagement [YAML](/docs/examples/history/opOnlyEngagement.yaml) | [JSON](/docs/examples/history/opOnlyEngagement.json5) - Check if Author is mostly engaging only in their own content

docs/examples/history/lowEngagement.json5

@@ -1,29 +1,33 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Low Comment Engagement",
-      "description": "Check if Author is submitting much more than they comment",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "lowComm",
-          "kind": "history",
-          "criteria": [
+          "name": "Low Comment Engagement",
+          "description": "Check if Author is submitting much more than they comment",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // look at last 90 days of Author's activities
-              "window": "90 days",
-              // trigger if less than 30% of their activities in this time period are comments
-              "comment": "< 30%"
-            },
+              "name": "lowComm",
+              "kind": "history",
+              "criteria": [
+                {
+                  // look at last 90 days of Author's activities
+                  "window": "90 days",
+                  // trigger if less than 30% of their activities in this time period are comments
+                  "comment": "< 30%"
+                },
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Low engagement: comments were {{rules.lowcomm.commentPercent}} of {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}"
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Low engagement: comments were {{rules.lowcomm.commentPercent}} of {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}"
-        }
       ]
     }
   ]

docs/examples/history/lowEngagement.yaml

@@ -0,0 +1,22 @@
+runs:
+  - checks:
+      - name: Low Comment Engagement
+        description: Check if Author is submitting much more than they comment
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: lowComm
+            kind: history
+            criteria:
+              - comment: '< 30%'
+                window:
+                  # get author's last 90 days of activities or 100 activities, whichever is less
+                  duration: 90 days
+                  count: 100
+                # trigger if less than 30% of their activities in this time period are comments
+
+        actions:
+          - kind: report
+            content: >-
+              Low engagement: comments were {{rules.lowcomm.commentPercent}} of
+              {{rules.lowcomm.activityTotal}} over {{rules.lowcomm.window}}

docs/examples/history/opOnlyEngagement.json5

@@ -1,29 +1,33 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Engaging Own Content Only",
-      "description": "Check if Author is mostly engaging in their own content only",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "opOnly",
-          "kind": "history",
-          "criteria": [
+          "name": "Engaging Own Content Only",
+          "description": "Check if Author is mostly engaging in their own content only",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // look at last 90 days of Author's activities
-              "window": "90 days",
-              // trigger if more than 60% of their activities in this time period are comments as OP
-              "comment": "> 60% OP"
-            },
+              "name": "opOnly",
+              "kind": "history",
+              "criteria": [
+                {
+                  // look at last 90 days of Author's activities
+                  "window": "90 days",
+                  // trigger if more than 60% of their activities in this time period are comments as OP
+                  "comment": "> 60% OP"
+                },
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Selfish OP: {{rules.oponly.opPercent}} of {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}} are as OP"
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Selfish OP: {{rules.oponly.opPercent}} of {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}} are as OP"
-        }
       ]
     }
   ]

docs/examples/history/opOnlyEngagement.yaml

@@ -0,0 +1,23 @@
+runs:
+  - checks:
+      - name: Engaging Own Content Only
+        description: Check if Author is mostly engaging in their own content only
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: opOnly
+            kind: history
+            criteria:
+              # trigger if more than 60% of their activities in this time period are comments as OP
+              - comment: '> 60% OP'
+                window:
+                  # get author's last 90 days of activities or 100 activities, whichever is less
+                  duration: 90 days
+                  count: 100
+
+        actions:
+          - kind: report
+            content: >-
+              Selfish OP: {{rules.oponly.opPercent}} of
+              {{rules.oponly.commentTotal}} comments over {{rules.oponly.window}}
+              are as OP

docs/examples/onlyfansFlair/README.md

@@ -0,0 +1,9 @@
+# Flair users and submissions
+
+Flair users and submissions based on certain keywords from submitter's profile.
+
+Consult [User Flair schema](https://json-schema.app/view/%23%2Fdefinitions%2FUserFlairActionJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) and [Submission Flair schema](https://json-schema.app/view/%23%2Fdefinitions%2FFlairActionJson?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+
+### Examples
+
+* OnlyFans submissions [YAML](/docs/examples/onlyFansFlair/onlyFansFlair.yaml) | [JSON](/docs/examples/onlyfansFlair/onlyfansFlair.json5) - Check whether submitter has typical OF keywords in their profile and flair both author + submission accordingly.

docs/examples/onlyfansFlair/onlyfansFlair.json5

@@ -0,0 +1,72 @@
+{
+  "runs": [
+    {
+      "checks": [
+        {
+          "name": "Flair OF submitters",
+          "description": "Flair submission as OF if user does not have Verified flair and has certain keywords in their profile",
+          "kind": "submission",
+          "authorIs": {
+            "exclude": [
+              {
+                "flairCssClass": ["verified"]
+              }
+            ]
+          },
+          "rules": [
+            {
+              "name": "OnlyFans strings in description",
+              "kind": "author",
+              "include": [
+                {
+                  "description": [
+                    "/(cashapp|allmylinks|linktr|onlyfans\\.com)/i",
+                    "/(see|check|my|view) (out|of|onlyfans|kik|skype|insta|ig|profile|links)/i",
+                    "my links",
+                    "$"
+                  ]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "name": "Set OnlyFans user flair",
+              "kind": "userflair",
+              "flair_template_id": "put-your-onlyfans-user-flair-id-here"
+            },
+            {
+              "name":"Set OF Creator SUBMISSION flair",
+              "kind": "flair",
+              "flair_template_id": "put-your-onlyfans-post-flair-id-here"
+            }
+          ]
+        },
+
+        {
+          "name": "Flair posts of OF submitters",
+          "description": "Flair submission as OnlyFans if submitter has OnlyFans userflair (override post flair set by submitter)",
+          "kind": "submission",
+          "rules": [
+            {
+              "name": "Include OF submitters",
+              "kind": "author",
+              "include": [
+                {
+                  "flairCssClass": ["onlyfans"]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "name":"Set OF Creator SUBMISSION flair",
+              "kind": "flair",
+              "flair_template_id": "put-your-onlyfans-post-flair-id-here"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

docs/examples/onlyfansFlair/onlyfansFlair.yaml

@@ -0,0 +1,39 @@
+runs:
+  - checks:
+      - name: Flair OF submitters
+        description: Flair submission as OF if user does not have Verified flair and has
+          certain keywords in their profile
+        kind: submission
+        authorIs:
+          exclude:
+            - flairCssClass:
+                - verified
+        rules:
+          - name: OnlyFans strings in description
+            kind: author
+            include:
+              - description:
+                  - '/(cashapp|allmylinks|linktr|onlyfans\.com)/i'
+                  - '/(see|check|my|view) (out|of|onlyfans|kik|skype|insta|ig|profile|links)/i'
+                  - my links
+                  - "$"
+        actions:
+          - name: Set OnlyFans user flair
+            kind: userflair
+            flair_template_id: put-your-onlyfans-user-flair-id-here
+          - name: Set OF Creator SUBMISSION flair
+            kind: flair
+            flair_template_id: put-your-onlyfans-post-flair-id-here
+      - name: Flair posts of OF submitters
+        description: Flair submission as OnlyFans if submitter has OnlyFans userflair (override post flair set by submitter)
+        kind: submission
+        rules:
+          - name: Include OF submitters
+            kind: author
+            include:
+              - flairCssClass:
+                  - onlyfans
+        actions:
+          - name: Set OF Creator SUBMISSION flair
+            kind: flair
+            flair_template_id: put-your-onlyfans-post-flair-id-here

docs/examples/recentActivity/README.md

@@ -6,5 +6,5 @@ Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FRecentActi
 
 ### Examples
 
-* [Free Karma Subreddits](/docs/examples/recentActivity/freeKarma.json5) - Check if the Author has recently posted in any "free karma" subreddits
-* [Submission in Free Karma Subreddits](/docs/examples/recentActivity/freeKarmaOnSubmission.json5) - Check if the Author has posted the Submission this check is running on in any "free karma" subreddits recently
+* Free Karma Subreddits [YAML](/docs/examples/recentActivity/freeKarma.yaml) | [JSON](/docs/examples/recentActivity/freeKarma.json5) - Check if the Author has recently posted in any "free karma" subreddits
+* Submission in Free Karma Subreddits [YAML](/docs/examples/recentActivity/freeKarmaOnSubmission.yaml) | [JSON](/docs/examples/recentActivity/freeKarmaOnSubmission.json5) - Check if the Author has posted the Submission this check is running on in any "free karma" subreddits recently

docs/examples/recentActivity/freeKarma.json5

@@ -1,38 +1,42 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Free Karma Alert",
-      "description": "Check if author has posted in 'freekarma' subreddits",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "useSubmissionAsReference": false,
-          // when `lookAt` is not present this rule will look for submissions and comments
-          // lookAt: "submissions"
-          // lookAt: "comments"
-          "thresholds": [
+          "name": "Free Karma Alert",
+          "description": "Check if author has posted in 'freekarma' subreddits",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "upvote"
-              ]
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "useSubmissionAsReference": false,
+              // when `lookAt` is not present this rule will look for submissions and comments
+              // lookAt: "submissions"
+              // lookAt: "comments"
+              "thresholds": [
+                {
+                  // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "upvote"
+                  ]
+                }
+              ],
+              // will look at all of the Author's activities in the last 7 days
+              "window": "7 days"
             }
           ],
-          // will look at all of the Author's activities in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.freekarma.totalCount}} activities in karma {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}: {{rules.freekarma.subSummary}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.freekarma.totalCount}} activities in karma {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}: {{rules.freekarma.subSummary}}"
+            }
+          ]
         }
       ]
     }

docs/examples/recentActivity/freeKarma.yaml

@@ -0,0 +1,28 @@
+runs:
+  - checks:
+      - name: Free Karma Alert
+        description: Check if author has posted in 'freekarma' subreddits
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            # // when lookAt is not present this rule will look for submissions and comments
+            #lookAt: comments
+            useSubmissionAsReference: false
+            thresholds:
+              # if the number of activities (sub/comment) found CUMULATIVELY in the subreddits listed is
+              # equal to or greater than 1 then the rule is triggered
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - upvote
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              {{rules.freekarma.totalCount}} activities in karma
+              {{rules.freekarma.subCount}} subs over {{rules.freekarma.window}}:
+              {{rules.freekarma.subSummary}}

docs/examples/recentActivity/freeKarmaOnSubmission.json5

@@ -1,39 +1,43 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Free Karma On Submission Alert",
-      "description": "Check if author has posted this submission in 'freekarma' subreddits",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "freekarmasub",
-          "kind": "recentActivity",
-          // rule will only look at Author's submissions in these subreddits
-          "lookAt": "submissions",
-          // rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
-          // In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
-          "useSubmissionAsReference":true,
-          "thresholds": [
+          "name": "Free Karma On Submission Alert",
+          "description": "Check if author has posted this submission in 'freekarma' subreddits",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
-              "threshold": ">= 1",
-              "subreddits": [
-                "DeFreeKarma",
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "upvote"
-              ]
+              "name": "freekarmasub",
+              "kind": "recentActivity",
+              // rule will only look at Author's submissions in these subreddits
+              "lookAt": "submissions",
+              // rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
+              // In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
+              "useSubmissionAsReference":true,
+              "thresholds": [
+                {
+                  // for all subreddits, if the number of activities (sub/comment) is equal to or greater than 1 then the rule is triggered
+                  "threshold": ">= 1",
+                  "subreddits": [
+                    "DeFreeKarma",
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "upvote"
+                  ]
+                }
+              ],
+              // look at all of the Author's submissions in the last 7 days
+              "window": "7 days"
             }
           ],
-          // look at all of the Author's submissions in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Submission posted {{rules.freekarmasub.totalCount}} times in karma {{rules.freekarmasub.subCount}} subs over {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}"
+            }
+          ]
         }
       ]
     }

docs/examples/recentActivity/freeKarmaOnSubmission.yaml

@@ -0,0 +1,27 @@
+runs:
+  - checks:
+      - name: Free Karma On Submission Alert
+        description: Check if author has posted this submission in 'freekarma' subreddits
+        kind: submission
+        rules:
+          - name: freekarmasub
+            kind: recentActivity
+            # rule will only look at Author's submissions in these subreddits
+            lookAt: submissions
+            # rule will only look at Author's submissions in these subreddits that have the same content (link) as the submission this event was made on
+            # In simpler terms -- rule will only check to see if the same link the author just posted is also posted in these subreddits
+            useSubmissionAsReference: true
+            thresholds:
+              - threshold: '>= 1'
+                subreddits:
+                  - DeFreeKarma
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - upvote
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Submission posted {{rules.freekarmasub.totalCount}} times in karma
+              {{rules.freekarmasub.subCount}} subs over
+              {{rules.freekarmasub.window}}: {{rules.freekarmasub.subSummary}}

docs/examples/regex/README.md

@@ -0,0 +1,22 @@
+The **Regex** rule matches on text content from a comment or submission in the same way automod uses regex. The rule, however, provides additional functionality automod does not:
+
+* Can set the **number** of matches that trigger the rule (`matchThreshold`)
+
+Which can then be used in conjunction with a [`window`](https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md) to match against activities from the history of the Author of the Activity being checked (including the Activity being checked):
+
+* Can set the **number of Activities** that meet the `matchThreshold` to trigger the rule (`activityMatchThreshold`)
+* Can set the **number of total matches** across all Activities to trigger the rule (`totalMatchThreshold`)
+* Can set the **type of Activities** to check (`lookAt`)
+* When an Activity is a Submission can **specify which parts of the Submission to match against** IE title, body, and/or url (`testOn`)
+
+### Examples
+
+* Trigger if regex matches against the current activity - [YAML](/docs/examples/regex/matchAnyCurrentActivity.yaml) | [JSON](/docs/examples/regex/matchAnyCurrentActivity.json5)
+* Trigger if regex matches 5 times against the current activity - [YAML](/docs/examples/regex/matchThresholdCurrentActivity.yaml) | [JSON](/docs/examples/regex/matchThresholdCurrentActivity.json5)
+* Trigger if regex matches against any part of a Submission - [YAML](/docs/examples/regex/matchSubmissionParts.yaml) | [JSON](/docs/examples/regex/matchSubmissionParts.json5)
+* Trigger if regex matches any of Author's last 10 activities - [YAML](/docs/examples/regex/matchHistoryActivity.yaml) | [JSON](/docs/examples/regex/matchHistoryActivity.json5)
+* Trigger if regex matches at least 3 of Author's last 10 activities - [YAML](/docs/examples/regex/matchActivityThresholdHistory.json5) | [JSON](/docs/examples/regex/matchActivityThresholdHistory.json5)
+* Trigger if there are 5 regex matches in the Author's last 10 activities - [YAML](/docs/examples/regex/matchTotalHistoryActivity.yaml) | [JSON](/docs/examples/regex/matchTotalHistoryActivity.json5) 
+* Trigger if there are 5 regex matches in the Author's last 10 comments - [YAML](/docs/examples/regex/matchSubsetHistoryActivity.yaml) | [JSON](/docs/examples/regex/matchSubsetHistoryActivity.json5)
+* Remove comments that are spamming discord links - [YAML](/docs/examples/regex/removeDiscordSpam.yaml) | [JSON](/docs/examples/regex/removeDiscordSpam.json5)
+  * Differs from just using automod because this config can allow one-off/organic links from users who DO NOT spam discord links but will still remove the comment if the user is spamming them

docs/examples/regex/matchActivityThresholdHistory.json5

@@ -0,0 +1,20 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    // triggers if more than 3 activities in the last 10 match the regex
+    {
+      "regex": "/fuck|shit|damn/",
+      // this differs from "totalMatchThreshold"
+      //
+      // activityMatchThreshold => # of activities from window must match regex
+      // totalMatchThreshold => # of matches across all activities from window must match regex
+      "activityMatchThreshold": "> 3",
+      // if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+      // learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+      "window": 10,
+    },
+  ]
+}

docs/examples/regex/matchActivityThresholdHistory.yaml

@@ -0,0 +1,13 @@
+name: swear
+kind: regex
+criteria:
+    # triggers if more than 3 activities in the last 10 match the regex
+  - regex: '/fuck|shit|damn/'
+    # this differs from "totalMatchThreshold"
+    #
+    # activityMatchThreshold => # of activities from window must match regex
+    # totalMatchThreshold => # of matches across all activities from window must match regex
+    activityMatchThreshold: '> 3'
+    # if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+    # learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+    window: 10

docs/examples/regex/matchAnyCurrentActivity.json5

@@ -0,0 +1,14 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    // triggers if current activity has more than 0 matches
+    {
+      "regex": "/fuck|shit|damn/",
+      // if "matchThreshold" is not specified it defaults to this -- default behavior is to trigger if there are any matches
+      // "matchThreshold": "> 0"
+    },
+  ]
+}

docs/examples/regex/matchAnyCurrentActivity.yaml

@@ -0,0 +1,6 @@
+name: swear
+kind: regex
+criteria:
+  - regex: '/fuck|shit|damn/'
+    # if "matchThreshold" is not specified it defaults to this -- default behavior is to trigger if there are any matches
+    #matchThreshold: "> 0"

docs/examples/regex/matchHistoryActivity.json5

@@ -0,0 +1,15 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    // triggers if any activity in the last 10 (including current activity) match the regex
+    {
+      "regex": "/fuck|shit|damn/",
+      // if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+      // learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+      "window": 10,
+    },
+  ]
+}

docs/examples/regex/matchHistoryActivity.yaml

@@ -0,0 +1,8 @@
+name: swear
+kind: regex
+criteria:
+    # triggers if any activity in the last 10 (including current activity) match the regex
+  - regex: '/fuck|shit|damn/'
+    # if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+    # learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+    window: 10

docs/examples/regex/matchSubmissionParts.json5

@@ -0,0 +1,19 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    {
+      // triggers if the current activity has more than 0 matches
+      // if the activity is a submission then matches against title, body, and url
+      // if "testOn" is not provided then `title, body` are the defaults
+      "regex": "/fuck|shit|damn/",
+      "testOn": [
+        "title",
+        "body",
+        "url"
+      ]
+    },
+  ]
+}

docs/examples/regex/matchSubmissionParts.yaml

@@ -0,0 +1,11 @@
+name: swear
+kind: regex
+criteria:
+  - regex: '/fuck|shit|damn/'
+    # triggers if the current activity has more than 0 matches
+    # if the activity is a submission then matches against title, body, and url
+    # if "testOn" is not provided then `title, body` are the defaults
+    testOn:
+      - title
+      - body
+      - url

docs/examples/regex/matchSubsetHistoryActivity.json5

@@ -0,0 +1,23 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    // triggers if there are more than 5 regex matches in the last 10 activities (comments only)
+    {
+      "regex": "/fuck|shit|damn/",
+      // this differs from "activityMatchThreshold"
+      //
+      // activityMatchThreshold => # of activities from window must match regex
+      // totalMatchThreshold => # of matches across all activities from window must match regex
+      "totalMatchThreshold": "> 5",
+      // if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+      // learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+      "window": 10,
+      // determines which activities from window to consider
+      //defaults to "all" (submissions and comments)
+      "lookAt": "comments",
+    },
+  ]
+}

docs/examples/regex/matchSubsetHistoryActivity.yaml

@@ -0,0 +1,16 @@
+name: swear
+kind: regex
+criteria:
+    # triggers if there are more than 5 regex matches in the last 10 activities (comments only)
+  - regex: '/fuck|shit|damn/'
+    # this differs from "activityMatchThreshold"
+    #
+    # activityMatchThreshold => # of activities from window must match regex
+    # totalMatchThreshold => # of matches across all activities from window must match regex
+    totalMatchThreshold: '> 5'
+    # if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+    # learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+    window: 10
+    # determines which activities from window to consider
+    # defaults to "all" (submissions and comments)
+    lookAt: comments

docs/examples/regex/matchThresholdCurrentActivity.json5

@@ -0,0 +1,13 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    {
+      "regex": "/fuck|shit|damn/",
+      // triggers if current activity has greater than 5 matches
+      "matchThreshold": "> 5"
+    },
+  ]
+}

docs/examples/regex/matchThresholdCurrentActivity.yaml

@@ -0,0 +1,6 @@
+name: swear
+kind: regex
+criteria:
+  - regex: '/fuck|shit|damn/'
+    # triggers if current activity has greater than 5 matches
+    matchThreshold: '> 5'

docs/examples/regex/matchTotalHistoryActivity.json5

@@ -0,0 +1,21 @@
+// goes inside
+// "rules": []
+{
+  "name": "swear",
+  "kind": "regex",
+  "criteria": [
+    // triggers if there are more than 5 regex matches in the last 10 activities (comments or submission)
+    {
+      // triggers if there are more than 5 *total matches* across the last 10 activities
+      "regex": "/fuck|shit|damn/",
+      // this differs from "activityMatchThreshold"
+      //
+      // activityMatchThreshold => # of activities from window must match regex
+      // totalMatchThreshold => # of matches across all activities from window must match regex
+      "totalMatchThreshold": "> 5",
+      // if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+      // learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+      "window": 10,
+    },
+  ]
+}

docs/examples/regex/matchTotalHistoryActivity.yaml

@@ -0,0 +1,13 @@
+name: swear
+kind: regex
+criteria:
+    # triggers if there are more than 5 regex matches in the last 10 activities (comments or submission)
+  - regex: '/fuck|shit|damn/'
+    # this differs from "activityMatchThreshold"
+    #
+    # activityMatchThreshold => # of activities from window must match regex
+    # totalMatchThreshold => # of matches across all activities from window must match regex
+    totalMatchThreshold: '> 5'
+    # if `window` is specified it tells the rule to check the current activity as well as the activities returned from `window`
+    # learn more about `window` here https://github.com/FoxxMD/context-mod/blob/master/docs/activitiesWindow.md
+    window: 10

docs/examples/regex/removeDiscordSpam.json5

@@ -0,0 +1,77 @@
+{
+  "runs": [
+    {
+      "checks": [
+        {
+          "name": "remove discord spam",
+          "notifyOnTrigger": true,
+          "description": "remove comments from users who are spamming discord links",
+          "kind": "comment",
+          "authorIs": {
+            "exclude": [
+              {
+                "isMod": true
+              }
+            ]
+          },
+          "itemIs": [
+            {
+              "removed": false,
+              "approved": false,
+            }
+          ],
+          "condition": "OR",
+          "rules": [
+            {
+              // set to false if you want to allow comments with a discord link ONLY IF
+              // the author doesn't have a history of spamming discord links
+              // -- basically allows one-off/organic discord links
+              "enable": true,
+              "name": "linkOnlySpam",
+              "kind": "regex",
+              "criteria": [
+                {
+                  "name": "only link",
+                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+)$/i",
+                }
+              ]
+            },
+            {
+              "condition": "AND",
+              "rules": [
+                {
+                  "name": "linkAnywhereSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains link anywhere",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                    }
+                  ]
+                },
+                {
+                  "name": "linkAnywhereHistoricalSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains links anywhere historically",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                      "totalMatchThreshold": ">= 3",
+                      "lookAt": "comments",
+                      "window": 10
+                    }
+                  ]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+}

docs/examples/regex/removeDiscordSpam.yaml

@@ -0,0 +1,37 @@
+runs:
+  - checks:
+      - name: remove discord spam
+        notifyOnTrigger: true
+        description: remove comments from users who are spamming discord links
+        kind: comment
+        authorIs:
+          exclude:
+            - isMod: true
+        itemIs:
+          - removed: false
+            approved: false
+        condition: OR
+        rules:
+          - enable: true
+            name: linkOnlySpam
+            kind: regex
+            criteria:
+              - name: only link
+                regex: '/^.*(discord\.gg\/[\w\d]+)$/i'
+          - condition: AND
+            rules:
+              - name: linkAnywhereSpam
+                kind: regex
+                criteria:
+                  - name: contains link anywhere
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+              - name: linkAnywhereHistoricalSpam
+                kind: regex
+                criteria:
+                  - name: contains links anywhere historically
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+                    totalMatchThreshold: '>= 3'
+                    lookAt: comments
+                    window: 10
+        actions:
+          - kind: remove

docs/examples/repeatActivity/README.md

@@ -45,5 +45,5 @@ With only `gapAllowance: 2` this rule **would trigger** because the the 1 and 2
 
 ## Examples
 
-* [Crosspost Spamming](/docs/examples/repeatActivity/crosspostSpamming.json5) - Check if an Author is spamming their Submissions across multiple subreddits
-* [Burst-posting](/docs/examples/repeatActivity/burstPosting.json5) - Check if Author is crossposting their Submissions in short bursts
+* Crosspost Spamming [JSON](/docs/examples/repeatActivity/crosspostSpamming.json5) | [YAML](/docs/examples/repeatActivity/crosspostSpamming.yaml) - Check if an Author is spamming their Submissions across multiple subreddits
+* Burst-posting [JSON](/docs/examples/repeatActivity/burstPosting.json5) | [YAML](/docs/examples/repeatActivity/burstPosting.yaml) - Check if Author is crossposting their Submissions in short bursts

docs/examples/repeatActivity/burstPosting.json5

@@ -1,30 +1,34 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Burstpost Spam",
-      "description": "Check if Author is crossposting in short bursts",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "burstpost",
-          "kind": "repeatActivity",
-          // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
-          "useSubmissionAsReference": true,
-          // the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
-          "gapAllowance": 3,
-          // if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
-          "threshold": ">= 6",
-          // look at all of the Author's submissions in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has burst-posted this link {{rules.burstpost.largestRepeat}} times over {{rules.burstpost.window}}"
+          "name": "Burstpost Spam",
+          "description": "Check if Author is crossposting in short bursts",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
+            {
+              "name": "burstpost",
+              "kind": "repeatActivity",
+              // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+              "useSubmissionAsReference": true,
+              // the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
+              "gapAllowance": 3,
+              // if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
+              "threshold": ">= 6",
+              // look at all of the Author's submissions in the last 7 days
+              "window": "7 days"
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has burst-posted this link {{rules.burstpost.largestRepeat}} times over {{rules.burstpost.window}}"
+            }
+          ]
         }
       ]
     }
-  ]
+  ],
 }

docs/examples/repeatActivity/burstPosting.yaml

@@ -0,0 +1,24 @@
+runs:
+  - checks:
+      - name: Burstpost Spam
+        description: Check if Author is crossposting in short bursts
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: burstpost
+            kind: repeatActivity
+            # will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+            useSubmissionAsReference: true
+            # the number of non-repeat activities (submissions or comments) to ignore between repeat submissions
+            gapAllowance: 3
+            # if the Author has posted this Submission 6 times, ignoring 3 non-repeat activities between each repeat, then this rule will trigger
+            threshold: '>= 6'
+            # look at all of the Author's submissions in the last 7 days or 100 submissions
+            window:
+              duration: 7 days
+              count: 100
+        actions:
+          - kind: report
+            content: >-
+              Author has burst-posted this link {{rules.burstpost.largestRepeat}}
+              times over {{rules.burstpost.window}}

docs/examples/repeatActivity/crosspostSpamming.json5

@@ -1,26 +1,30 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Crosspost Spam",
-      "description": "Check if Author is spamming Submissions across subreddits",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "xpostspam",
-          "kind": "repeatActivity",
-          // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
-          "useSubmissionAsReference": true,
-          // if the Author has posted this Submission 5 times consecutively then this rule will trigger
-          "threshold": ">= 5",
-          // look at all of the Author's submissions in the last 7 days
-          "window": "7 days"
-        }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "Author has posted this link {{rules.xpostspam.largestRepeat}} times over {{rules.xpostspam.window}}"
+          "name": "Crosspost Spam",
+          "description": "Check if Author is spamming Submissions across subreddits",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
+            {
+              "name": "xpostspam",
+              "kind": "repeatActivity",
+              // will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+              "useSubmissionAsReference": true,
+              // if the Author has posted this Submission 5 times consecutively then this rule will trigger
+              "threshold": ">= 5",
+              // look at all of the Author's submissions in the last 7 days
+              "window": "7 days"
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "Author has posted this link {{rules.xpostspam.largestRepeat}} times over {{rules.xpostspam.window}}"
+            }
+          ]
         }
       ]
     }

docs/examples/repeatActivity/crosspostSpamming.yaml

@@ -0,0 +1,20 @@
+runs:
+  - checks:
+      - name: Crosspost Spam
+        description: Check if Author is spamming Submissions across subreddits
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: xpostspam
+            kind: repeatActivity
+            # will only look at Submissions in Author's history that contain the same content (link) as the Submission this check was initiated by
+            useSubmissionAsReference: true
+            # if the Author has posted this Submission 5 times consecutively then this rule will trigger
+            threshold: '>= 5'
+            # look at all of the Author's submissions in the last 7 days
+            window: 7 days
+        actions:
+          - kind: report
+            content: >-
+              Author has posted this link {{rules.xpostspam.largestRepeat}} times
+              over {{rules.xpostspam.window}}

docs/examples/repost/README.md

@@ -0,0 +1,927 @@
+The **Repost** rule is used to find reposts for both **Submissions** and **Comments**, depending on what type of **Check** it is used on.
+
+Note: This rule is for searching **all of Reddit** for reposts, as opposed to just the Author of the Activity being checked. If you only want to check for reposts by the Author of the Activity being checked you should use the [Repeat Activity](/docs/examples/repeatActivity) rule.
+
+# TLDR
+
+Out of the box CM generates a repost rule with sensible default behavior without any configuration. You do not need to configure any of below options (facets, modifiers, criteria) yourself in order to have a working repost rule. Default behavior is as follows...
+
+* When looking for Submission reposts CM will find any Submissions with 
+  * a very similar title 
+  * or independent of title...
+     * any crossposts/duplicates
+     * any submissions with the exact URL
+* When looking for Comment reposts CM will do the above AND THEN 
+  * compare the top 50 most-upvoted comments from the top 10 most-upvoted Submissions against the comment being checked
+  * compare any items found from external source (Youtube comments, etc...) against the comment being checked
+
+# Configuration
+
+## Search Facets
+
+ContextMod has several ways to search for reposts -- all of which look at different elements of a Submission in order to find repost candidates. You can define any/all of these **Search Facets** you want to use to search Reddit inside the configuration for the Repost Rule in the `searchOn` property.
+
+### Usage
+
+Facets are specified in the `searchOn` array property within the rule's configuration.
+
+**String**
+
+Specify one or more types of facets as a string to use their default configurations
+
+<details>
+
+YAML
+```yaml
+kind: repost
+criteria:
+  - searchOn:
+      - title
+      - url
+      - crossposts
+```
+
+JSON
+```json5
+{
+  "kind": "repost",
+  "criteria": [
+    {
+      // ...
+      "searchOn": ["title", "url", "crossposts"],
+      // ....
+    }
+  ]
+}
+
+```
+
+</details>
+
+**Object**
+
+**string** and object configurations can be mixed
+
+<details>
+
+```yaml
+kind: repost
+criteria:
+  - searchOn:
+      - title
+      - kind: url
+        matchScore: 90
+      - external
+```
+
+```json5
+{
+  "kind": "repost",
+  "criteria": [
+    {
+      // ...
+      "searchOn": [
+        "title",
+        {
+          "kind": "url",
+          // could also specify multiple types to use the same config for all
+          //"kind": ["url", "duplicates"]
+          "matchScore": 90,
+          //...
+        },
+        "external"
+      ],
+      // ....
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Facet Types
+
+* **title** -- search reddit for Submissions with a similar title
+* **url** -- search reddit for Submissions with the same URL
+* **duplicates** -- get all Submissions **reddit has identified** as duplicates that are **NOT** crossposts
+  * these are found under *View discussions in other communities* (new reddit) or *other discussions* (old reddit) on the Submission
+* **crossposts** -- get all Submissions where the current Submission is the source of an **official** crosspost
+  * this differs from duplicates in that crossposts use reddit's built-in crosspost functionality, respect subreddit crosspost rules, and link back to the original Submission
+* **external** -- get items from the Submission's link source that may be reposted (currently implemented for **Comment Checks** only)
+  * When the Submission link is for...
+    * **Youtube** -- get top comments on video by replies/like count
+      * **NOTE:** An **API Key** for the [Youtube Data API](https://developers.google.com/youtube/v3) must be provided for this facet to work. This can be provided by the operator alongside [bot credentials](/docs/operatorConfiguration.md) or in the top-level `credentials` property for a [subreddit configuration.](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json)
+
+### Facet Modifiers
+
+For all **Facets**, except for **external**, there are options that be configured to determine if the found Submissions is a "valid" repost IE filtering. These options can be configured **per facet**.
+
+* **matchScore** -- The percentage, as a whole number, of a repost title that must match the title being checked in order to consider both a match
+* **minWordCount** -- The minimum number of words a title must have
+* **caseSensitive** -- If the match comparison should be case-sensitive (defaults to `false`)
+
+Additionally, the current Activity's title and/or each repost's title can be transformed before matching:
+
+* **transformations** -- An array of SearchAndReplace objects used to transform the repost's title
+* **transformationsActivity** -- An array of SearchAndReplace objects used to transform the current Activity's title
+
+#### Modifier Defaults
+
+To make facets easier to use without configuration sensible defaults are applied to each when no other configuration is defined...
+
+* **title**
+  * `matchScore: 85` -- The candidate repost's title must be at least 85% similar to the current Activity's title
+  * `minWordCount: 2` --  The candidate repost's title must have at least 2 words
+
+For `url`,`duplicates`, and `crossposts` the only default is `matchScore: 0` because the assumption is you want to treat any actual dups/x-posts or exact URLs as reposts, regardless of their title.
+
+## Additional Criteria Properties
+
+A **criteria** object may also specify some additional tests to run against the reposts found from searching.
+
+### For Submissions and Comments
+
+#### Occurrences
+
+Define a set of criteria to test against the **number of reposts**, **time reposts were created**, or both.
+
+##### Count
+
+<details>
+
+```yaml
+kind: repost
+criteria:
+  - searchOn:
+      - title
+      - url
+      - crossposts
+    occurrences:
+      criteria:
+        - count:
+            condition: AND
+            test:
+              - '> 3'
+              - <= 5
+```
+
+```json5
+{
+  "kind": "repost",
+  "criteria": [
+    {
+      // ...
+      "searchOn": ["title", "url", "crossposts"],
+      "occurrences": {
+        "criteria": [
+          {
+            // passes if BOTH tests are true
+            "count": {
+              "condition": "AND", // default is AND
+              "test": [
+                "> 3", // TRUE if there are GREATER THAN 3 reposts found
+                "<= 5" // TRUE if there are LESS THAN OR EQUAL TO 5 reposts found
+              ]
+            }
+          }
+        ],
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+##### Time
+
+Define a test or array of tests to run against **when reposts were created**
+
+<details>
+
+```yaml
+kind: repost
+criteria:
+  - searchOn:
+      - title
+      - url
+      - crossposts
+    occurrences:
+      criteria:
+        - time:
+            condition: AND
+            test:
+              - testOn: all
+                condition: '> 3 months'
+```
+
+```json5
+{
+  "kind": "repost",
+  "criteria": [
+    {
+      // ...
+      "searchOn": [
+        "title",
+        "url",
+        "crossposts"
+      ],
+      "occurrences": {
+        "criteria": [
+          {
+            time: {
+              // how to test array of comparisons. AND => all must pass, OR => any must pass
+              "condition": "AND",
+              "test": [
+                {
+                  // which of the found reposts to test the time comparison on
+                  //
+                  // "all"    => ALL reposts must pass time comparison
+                  // "any"    => ANY repost must pass time comparison
+                  // "newest" => The newest (closest in time to now) repost must pass time comparison
+                  // "oldest" => The oldest (furthest in time from now) repost must pass time comparison
+                  //
+                  "testOn": "all",
+                  // Tested items must be OLDER THAN 3 months
+                  "condition": "> 3 months"
+                }
+              ]
+            }
+          }
+        ]
+      },
+    }
+  ]
+}
+```
+
+</details>
+
+
+### For Comments
+
+When the rule is run in a **Comment Check** you may specify text comparisons (like those found in Search Facets) to run on the contents of the repost comments *against* the contents of the comment being checked.
+
+* **matchScore** -- The percentage, as a whole number, of a repost comment that must match the comment being checked in order to consider both a match (defaults to 85% IE `85`)
+* **minWordCount** -- The minimum number of words a comment must have
+* **caseSensitive** -- If the match comparison should be case-sensitive (defaults to `false`)
+
+# Examples
+
+Examples of a *full* CM configuration, including the Repost Rule, in various scenarios. In each scenario the parts of the configuration that affect the rule are indicated.
+
+## Submissions
+
+When the Repost Rule is run on a **Submission Check** IE the activity being checked is a Submission.
+
+### Default Behavior (No configuration)
+
+This is the same behavior described in the [TLDR](#TLDR) section above -- find any submissions with:
+
+* a very similar title (85% or more the same)
+* or ignoring title...
+  * any crossposts/duplicates
+  * any submissions with the exact URL
+
+<details>
+
+```yaml
+polling:
+  - unmoderated
+checks:
+  - name: subRepost
+    description: Check if submission has been reposted
+    kind: submission
+    condition: AND
+    rules:
+      - kind: repost
+    actions:
+      - kind: report
+        content: This submission was reposted
+```
+
+```json5
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      "name": "subRepost",
+      "description": "Check if submission has been reposted",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "submission",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost"
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This submission was reposted"
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Search by Title Only
+
+Find any submissions with:
+
+* a very similar title (85% or more the same)
+
+<details>
+
+```yaml
+polling:
+  - unmoderated
+checks:
+  - name: subRepost
+    description: Check if submission has been reposted
+    kind: submission
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - title
+    actions:
+      - kind: report
+        content: This submission was reposted
+```
+
+```json5
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      "name": "subRepost",
+      "description": "Check if submission has been reposted",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "submission",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              // specify only title to search on
+              "searchOn": [
+                "title" // uses default configuration since only string is specified
+              ]
+            }
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This submission was reposted"
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Search by Title only and specify similarity percentage
+
+* a very similar title (95% or more the same)
+
+<details>
+
+```yaml
+polling:
+  - unmoderated
+checks:
+  - name: subRepost
+    description: Check if submission has been reposted
+    kind: submission
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - kind: title
+                matchScore: '95'
+    actions:
+      - kind: report
+        content: This submission was reposted
+```
+
+```json5
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      "name": "subRepost",
+      "description": "Check if submission has been reposted",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "submission",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              // specify only title to search on
+              "searchOn": [
+                {
+                  "kind": "title",
+                  // titles must be 95% or more similar
+                  "matchScore": "95"
+                }
+              ]
+            }
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This submission was reposted"
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Search by Title, specify similarity percentage, AND any duplicates
+
+<details>
+
+```yaml
+polling:
+  - unmoderated
+checks:
+  - name: subRepost
+    description: Check if submission has been reposted
+    kind: submission
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - duplicates
+              - kind: title
+                matchScore: '95'
+    actions:
+      - kind: report
+        content: This submission was reposted
+```
+
+```json5
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      "name": "subRepost",
+      "description": "Check if submission has been reposted",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "submission",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              "searchOn": [
+                // look for duplicates (NON crossposts) using default configuration
+                "duplicates",
+                // search by title
+                {
+                  "kind": "title",
+                  // titles must be 95% or more similar
+                  "matchScore": "95"
+                }
+              ]
+            }
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This submission was reposted"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
+### Approve Submission if not reposted in the last month, by title
+
+<details>
+
+```yaml
+polling:
+  - unmoderated
+checks:
+  - name: subRepost
+    description: Check there are no reposts with same title in the last month
+    kind: submission
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - title
+            occurrences:
+              condition: OR
+              criteria:
+                - count:
+                    test:
+                      - < 1
+                - time:
+                    test:
+                      - testOn: newest
+                        condition: '> 1 month'
+    actions:
+      - kind: approve
+```
+
+```json5
+{
+  "polling": [
+    "unmoderated"
+  ],
+  "checks": [
+    {
+      "name": "subRepost",
+      "description": "Check there are no reposts with same title in the last month",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "submission",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              "searchOn": [
+                "title"
+              ],
+              "occurrences": {
+                // if EITHER criteria is TRUE then it "passes"
+                "condition": "OR",
+                "criteria": [
+                  // first criteria:
+                  // TRUE if there are LESS THAN 1 reposts (no reposts found)
+                  {
+                    "count": {
+                      "test": ["< 1"]
+                    }
+                  },
+                  // second criteria:
+                  // TRUE if the newest repost is older than one month
+                  {
+                    "time": {
+                      "test": [
+                        {
+                          "testOn": "newest",
+                          "condition": "> 1 month"
+                        }
+                      ]
+                    }
+                  }
+                ]
+              },
+            }
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          // approve this post since we know it is not a repost of anything within the last month
+          "kind": "approve",
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+
+## Comments
+
+### Default Behavior (No configuration)
+
+This is the same behavior described in the [TLDR](#TLDR) section above -- find any submissions with:
+
+* a very similar title (85% or more the same)
+* or ignoring title...
+  * any crossposts/duplicates
+  * any submissions with the exact URL
+* If comment being checked is on a Submission for Youtube then get top 50 comments on youtube video as well...
+
+AND THEN
+
+* sort submissions by votes
+* take top 20 (upvoted) comments from top 10 (upvoted) submissions
+* sort comments by votes, take top 50 + top 50 external items
+
+FINALLY
+
+* filter all gathered comments by default `matchScore: 85` to find very similar matches
+* rules is triggered if any are found
+
+<details>
+
+```yaml
+polling:
+  - newComm
+checks:
+  - name: commRepost
+    description: Check if comment has been reposted
+    kind: common
+    condition: AND
+    rules:
+      - kind: repost
+    actions:
+      - kind: report
+        content: This comment was reposted
+```
+
+```json5
+{
+  "polling": [
+    "newComm"
+  ],
+  "checks": [
+    {
+      "name": "commRepost",
+      "description": "Check if comment has been reposted",
+      // kind specifies this check is for COMMENTS
+      "kind": "common",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost"
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This comment was reposted"
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Search by external (youtube) comments only
+
+<details>
+
+```yaml
+polling:
+  - newComm
+checks:
+  - name: commRepost
+    description: Check if comment has been reposted from youtube
+    kind: comment
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - external
+    actions:
+      - kind: report
+        content: This comment was reposted from youtube
+```
+
+```json5
+{
+  "polling": [
+    "newComm"
+  ],
+  "checks": [
+    {
+      "name": "commRepost",
+      "description": "Check if comment has been reposted from youtube",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "comment",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              // specify only external (youtube) to search on
+              "searchOn": [
+                "external"
+              ]
+            }
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This comment was reposted from youtube"
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Search by external (youtube) comments only, with higher comment match percentage
+
+<details>
+
+```yaml
+polling:
+  - newComm
+checks:
+  - name: commRepost
+    description: Check if comment has been reposted from youtube
+    kind: comment
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - external
+            matchScore: 95
+    actions:
+      - kind: report
+        content: This comment was reposted from youtube
+```
+
+```json5
+{
+  "polling": [
+    "newComm"
+  ],
+  "checks": [
+    {
+      "name": "commRepost",
+      "description": "Check if comment has been reposted from youtube",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "comment",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              // specify only external (youtube) to search on
+              "searchOn": [
+                "external"
+              ],
+              "matchScore": 95 // matchScore for comments is on criteria instead of searchOn config...
+            },
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This comment was reposted from youtube"
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+</details>
+
+### Search by external (youtube) comments and submission URL, with higher comment match percentage
+
+<details>
+
+```yaml
+polling:
+  - newComm
+checks:
+  - name: commRepost
+    description: Check if comment has been reposted
+    kind: comment
+    condition: AND
+    rules:
+      - kind: repost
+        criteria:
+          - searchOn:
+              - external
+              - url
+            matchScore: 95
+    actions:
+      - kind: report
+        content: >-
+          This comment was reposted from youtube or from submission with the
+          same URL
+```
+
+```json5
+{
+  "polling": [
+    "newComm"
+  ],
+  "checks": [
+    {
+      "name": "commRepost",
+      "description": "Check if comment has been reposted",
+      // kind specifies this check is for SUBMISSIONS
+      "kind": "comment",
+      "condition": "AND",
+      "rules": [
+        // repost rule configuration is below
+        //
+        {
+          "kind": "repost",
+          "criteria": [
+            {
+              // specify only external (youtube) to search on
+              "searchOn": [
+                "external",
+                // can specify any/all submission search facets to acquire comments from
+                "url"
+              ],
+              "matchScore": 95 // matchScore for comments is on criteria instead of searchOn config...
+            },
+          ]
+        },
+        // 
+        // repost rule configuration is above
+      ],
+      "actions": [
+        {
+          "kind": "report",
+          "content": "This comment was reposted from youtube or from submission with the same URL"
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>

docs/examples/subredditReady/README.md

@@ -11,21 +11,31 @@ All actions for these configurations are non-destructive in that:
 
 **You will have to remove the `report` action and `dryRun` settings yourself.** This is to ensure that you understand the behavior the bot will be performing. If you are unsure of this you should leave them in place until you are certain the behavior the bot is performing is acceptable.
 
+**YAML** is the same format as **automoderator**
+
 ## Submission-based Behavior
 
-### [Remove submissions from users who have used 'freekarma' subs to bypass karma checks](/docs/examples/subredditReady/freekarma.json5)
+### Remove submissions from users who have used 'freekarma' subs to bypass karma checks
+
+[YAML](/docs/examples/subredditReady/freekarma.yaml) | [JSON](/docs/examples/subredditReady/freekarma.json5)
 
 If the user has any activity (comment/submission) in known freekarma subreddits in the past (50 activities or 6 months) then remove the submission.
 
-### [Remove submissions from users who have crossposted the same submission 4 or more times](/docs/examples/subredditReady/crosspostSpam.json5)
+### Remove submissions from users who have crossposted the same submission 4 or more times
+
+[YAML](/docs/examples/subredditReady/crosspostSpam.yaml) | [JSON](/docs/examples/subredditReady/crosspostSpam.yaml)
 
 If the user has crossposted the same submission in the past (50 activities or 6 months) 4 or more times in a row then remove the submission.
 
-### [Remove submissions from users who have crossposted or used 'freekarma' subs](/docs/examples/subredditReady/freeKarmaOrCrosspostSpam.json5)
+### Remove submissions from users who have crossposted or used 'freekarma' subs
+
+[YAML](/docs/examples/subredditReady/freeKarmaOrCrosspostSpam.yaml) | [JSON](/docs/examples/subredditReady/freeKarmaOrCrosspostSpam.json5)
 
 Will remove submission if either of the above two behaviors is detected
 
-### [Remove link submissions where the user's history is comprised of 10% or more of the same link](/docs/examples/subredditReady/selfPromo.json5)
+### Remove link submissions where the user's history is comprised of 10% or more of the same link
+
+[YAML](/docs/examples/subredditReady/selfPromo.yaml) | [JSON](/docs/examples/subredditReady/selfPromo.json5)
 
 If the link origin (youtube author, twitter author, etc. or regular domain for non-media links)
 
@@ -36,6 +46,33 @@ then remove the submission
 
 ## Comment-based behavior
 
-### [Remove comment if the user has posted the same comment 4 or more times in a row](/docs/examples/subredditReady/commentSpam.json5)
+### Remove comment if the user has posted the same comment 4 or more times in a row
+
+[YAML](/docs/examples/subredditReady/commentSpam.yaml) | [JSON](/docs/examples/subredditReady/commentSpam.json5)
 
 If the user made the same comment (with some fuzzy matching) 4 or more times in a row in the past (50 activities or 6 months) then remove the comment.
+
+### Remove comment if it is discord invite link spam
+
+[YAML](/docs/examples/subredditReady/discordSpam.yaml) | [JSON](/docs/examples/subredditReady/discordSpam.json5)
+
+This rule goes a step further than automod can by being more discretionary about how it handles this type of spam. 
+
+* Remove the comment and **ban a user** if:
+  * Comment being checked contains **only** a discord link (no other text) AND
+  * Discord links appear **anywhere** in three or more of the last 10 comments the Author has made
+
+otherwise...
+
+* Remove the comment if:
+  * Comment being checked contains **only** a discord link (no other text) OR
+    * Comment contains a discord link **anywhere** AND
+    * Discord links appear **anywhere** in three or more of the last 10 comments the Author has made
+
+Using these checks ContextMod can more easily distinguish between these use cases for a user commenting with a discord link:
+
+* actual spammers who only spam a discord link
+* users who may comment with a link but have context for it either in the current comment or in their history
+* users who many comment with a link but it's a one-off event (no other links historically)
+
+Additionally, you could modify both/either of these checks to not remove one-off discord link comments but still remove if the user has a historical trend for spamming links

docs/examples/subredditReady/commentSpam.json5

@@ -1,42 +1,46 @@
 {
   "polling": ["newComm"],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who spam the same comment many times
-      //
-      // Remove a COMMENT if the user has crossposted it at least 4 times in recent history
-      //
-      "name": "low xp comment spam",
-      "description": "X-posted comment >=4x",
-      "kind": "comment",
-      "condition": "AND",
-      "rules": [
+      "checks": [
         {
-          "name": "xPostLow",
-          "kind": "repeatActivity",
-          "gapAllowance": 2,
-          "threshold": ">= 4",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          }
-        },
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=> Posted same comment {{rules.xpostlow.largestRepeat}}x times"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
+          //
+          // Stop users who spam the same comment many times
+          //
+          // Remove a COMMENT if the user has crossposted it at least 4 times in recent history
+          //
+          "name": "low xp comment spam",
+          "description": "X-posted comment >=4x",
+          "kind": "comment",
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "xPostLow",
+              "kind": "repeatActivity",
+              "gapAllowance": 2,
+              "threshold": ">= 4",
+              "window": {
+                "count": 50,
+                "duration": "6 months"
+              }
+            },
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=> Posted same comment {{rules.xpostlow.largestRepeat}}x times"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            }
+          ]
         }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/commentSpam.yaml

@@ -0,0 +1,26 @@
+polling:
+  - newComm
+runs:
+  - checks:
+      # Stop users who spam the same comment many times
+      - name: low xp comment spam
+        description: X-posted comment >=4x
+        kind: comment
+        condition: AND
+        rules:
+          - name: xPostLow
+            kind: repeatActivity
+            # number of "non-repeat" comments allowed between "repeat comments"
+            gapAllowance: 2
+            # greater or more than 4 repeat comments triggers this rule
+            threshold: '>= 4'
+            # retrieve either last 50 comments or 6 months' of history, whichever is less
+            window:
+              count: 50
+              duration: 6 months
+        actions:
+          - kind: report
+            enable: true
+            content: 'Remove => Posted same comment {{rules.xpostlow.largestRepeat}}x times'
+          - kind: remove
+            enable: true

docs/examples/subredditReady/crosspostSpam.json5

@@ -1,77 +1,81 @@
 {
   "polling": ["unmoderated"],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who post low-effort, crossposted spam
-      //
-      // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
-      // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-      //
-      "name": "low xp spam and engagement",
-      "description": "X-posted 4x and low comment engagement",
-      "kind": "submission",
-      "itemIs": [
+      "checks": [
         {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "xPostLow",
-          "kind": "repeatActivity",
-          "gapAllowance": 2,
-          "threshold": ">= 4",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          }
-        },
-        {
-          "name": "lowOrOpComm",
-          "kind": "history",
-          "criteriaJoin": "OR",
-          "criteria": [
+          //
+          // Stop users who post low-effort, crossposted spam
+          //
+          // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+          // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+          //
+          "name": "low xp spam and engagement",
+          "description": "X-posted 4x and low comment engagement",
+          "kind": "submission",
+          "itemIs": [
             {
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "xPostLow",
+              "kind": "repeatActivity",
+              "gapAllowance": 2,
+              "threshold": ">= 4",
               "window": {
-                "count": 100,
+                "count": 50,
                 "duration": "6 months"
-              },
-              "comment": "< 50%"
+              }
             },
             {
-              "window": {
-                "count": 100,
-                "duration": "6 months"
-              },
-              "comment": "> 40% OP"
+              "name": "lowOrOpComm",
+              "kind": "history",
+              "criteriaJoin": "OR",
+              "criteria": [
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "< 50%"
+                },
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "> 40% OP"
+                }
+              ]
+            }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
+              "distinguish": true,
+              "dryRun": true
             }
           ]
         }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-       {
-          "kind": "comment",
-          "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
-          "distinguish": true,
-          "dryRun": true
-        }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/crosspostSpam.yaml

@@ -0,0 +1,49 @@
+polling:
+  - unmoderated
+runs:
+  - checks:
+      #   stop users who post low-effort, crossposted spam submissions
+      #
+      #   Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+      #   less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      - name: low xp spam and engagement
+        description: X-posted 4x and low comment engagement
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: xPostLow
+            kind: repeatActivity
+            gapAllowance: 2
+            threshold: '>= 4'
+            window:
+              count: 50
+              duration: 6 months
+          - name: lowOrOpComm
+            kind: history
+            criteriaJoin: OR
+            criteria:
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: < 50%
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: '> 40% OP'
+        actions:
+          - kind: report
+            enable: true
+            content: >-
+              Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
+              {{rules.loworopcomm.thresholdSummary}}
+          - kind: remove
+            enable: true
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed because you cross-posted it
+              {{rules.xpostlow.largestRepeat}} times and you have very low
+              engagement outside of making submissions
+            distinguish: true

docs/examples/subredditReady/discordSpam.json5

@@ -0,0 +1,79 @@
+{
+  "polling": ["newComm"],
+  "runs": [
+    {
+      "checks": [
+        {
+          "name": "ban discord only spammer",
+          "description": "ban a user who spams only a discord link many times historically",
+          "kind": "comment",
+          "condition": "AND",
+          "rules": [
+            "linkOnlySpam",
+            "linkAnywhereHistoricalSpam",
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            },
+            {
+              "kind": "ban",
+              "content": "spamming discord links"
+            }
+          ]
+        },
+        {
+          "name": "remove discord spam",
+          "description": "remove comments from users who only link to discord or mention discord link many times historically",
+          "kind": "comment",
+          "condition": "OR",
+          "rules": [
+            {
+              "name": "linkOnlySpam",
+              "kind": "regex",
+              "criteria": [
+                {
+                  "name": "only link",
+                  "regex": "/^.*(discord\\.gg\\/[\\w\\d]+)$/i",
+                }
+              ]
+            },
+            {
+              "condition": "AND",
+              "rules": [
+                {
+                  "name": "linkAnywhereSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains link anywhere",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                    }
+                  ]
+                },
+                {
+                  "name": "linkAnywhereHistoricalSpam",
+                  "kind": "regex",
+                  "criteria": [
+                    {
+                      "name": "contains links anywhere historically",
+                      "regex": "/^.*(discord\\.gg\\/[\\w\\d]+).*$/i",
+                      "totalMatchThreshold": ">= 3",
+                      "lookAt": "comments",
+                      "window": 10
+                    }
+                  ]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            {
+              "kind": "remove"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+}

docs/examples/subredditReady/discordSpam.yaml

@@ -0,0 +1,47 @@
+polling:
+    - newComm
+runs:
+  - checks:
+      - name: ban discord only spammer
+        description: ban a user who spams only a discord link many times historically
+        kind: comment
+        condition: AND
+        rules:
+          - linkOnlySpam
+          - linkAnywhereHistoricalSpam
+        actions:
+          - kind: remove
+          - kind: ban
+            content: spamming discord links
+      - name: remove discord spam
+        description: >-
+          remove comments from users who only link to discord or mention discord
+          link many times historically
+        kind: comment
+        condition: OR
+        rules:
+          - name: linkOnlySpam
+            kind: regex
+            criteria:
+              - name: only link
+                # single quotes are required to escape special characters
+                regex: '/^.*(discord\.gg\/[\w\d]+)$/i'
+          - condition: AND
+            rules:
+              - name: linkAnywhereSpam
+                kind: regex
+                criteria:
+                  - name: contains link anywhere
+                    # single quotes are required to escape special characters
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+              - name: linkAnywhereHistoricalSpam
+                kind: regex
+                criteria:
+                  - name: contains links anywhere historically
+                    # single quotes are required to escape special characters
+                    regex: '/^.*(discord\.gg\/[\w\d]+).*$/i'
+                    totalMatchThreshold: '>= 3'
+                    lookAt: comments
+                    window: 10
+        actions:
+          - kind: remove

docs/examples/subredditReady/freeKarmaOrCrosspostSpam.json5

@@ -2,135 +2,139 @@
   "polling": [
     "unmoderated"
   ],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who post low-effort, crossposted spam
-      //
-      // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
-      // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-      //
-      "name": "remove on low xp spam and engagement",
-      "description": "X-posted 4x and low comment engagement",
-      "kind": "submission",
-      "itemIs": [
+      "checks": [
         {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "xPostLow",
-          "kind": "repeatActivity",
-          "gapAllowance": 2,
-          "threshold": ">= 4",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          }
-        },
-        {
-          "name": "lowOrOpComm",
-          "kind": "history",
-          "criteriaJoin": "OR",
-          "criteria": [
+          //
+          // Stop users who post low-effort, crossposted spam
+          //
+          // Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+          // less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+          //
+          "name": "remove on low xp spam and engagement",
+          "description": "X-posted 4x and low comment engagement",
+          "kind": "submission",
+          "itemIs": [
             {
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "xPostLow",
+              "kind": "repeatActivity",
+              "gapAllowance": 2,
+              "threshold": ">= 4",
               "window": {
-                "count": 100,
+                "count": 50,
                 "duration": "6 months"
-              },
-              "comment": "< 50%"
+              }
             },
             {
-              "window": {
-                "count": 100,
-                "duration": "6 months"
-              },
-              "comment": "> 40% OP"
-            }
-          ]
-        }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
-          "distinguish": true,
-          "dryRun": true
-        }
-      ]
-    },
-    {
-      //
-      // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
-      //
-      "name": "freekarma removal",
-      "description": "Remove submission if user has used freekarma sub recently",
-      "kind": "submission",
-      "itemIs": [
-        {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          },
-          "useSubmissionAsReference": false,
-          "thresholds": [
-            {
-              "subreddits": [
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "KarmaStore",
-                "promote",
-                "shamelessplug",
-                "upvote"
+              "name": "lowOrOpComm",
+              "kind": "history",
+              "criteriaJoin": "OR",
+              "criteria": [
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "< 50%"
+                },
+                {
+                  "window": {
+                    "count": 100,
+                    "duration": "6 months"
+                  },
+                  "comment": "> 40% OP"
+                }
               ]
             }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=>{{rules.xpostlow.largestRepeat}} X-P => {{rules.loworopcomm.thresholdSummary}}"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you cross-posted it {{rules.xpostlow.largestRepeat}} times and you have very low engagement outside of making submissions",
+              "distinguish": true,
+              "dryRun": true
+            }
           ]
-        }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
         },
-        //
-        //
         {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
-          "distinguish": true,
-          "dryRun": true
+          //
+          // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+          //
+          "name": "freekarma removal",
+          "description": "Remove submission if user has used freekarma sub recently",
+          "kind": "submission",
+          "itemIs": [
+            {
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "window": {
+                "count": 50,
+                "duration": "6 months"
+              },
+              "useSubmissionAsReference": false,
+              "thresholds": [
+                {
+                  "subreddits": [
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "KarmaStore",
+                    "promote",
+                    "shamelessplug",
+                    "upvote"
+                  ]
+                }
+              ]
+            }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
+              "distinguish": true,
+              "dryRun": true
+            }
+          ]
         }
       ]
     }

docs/examples/subredditReady/freeKarmaOrCrosspostSpam.yaml

@@ -0,0 +1,85 @@
+polling:
+  - unmoderated
+runs:
+  - checks:
+      #   stop users who post low-effort, crossposted spam submissions
+      #
+      #   Remove a SUBMISSION if the user has crossposted it at least 4 times in recent history AND
+      #   less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      - name: remove on low xp spam and engagement
+        description: X-posted 4x and low comment engagement
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: xPostLow
+            kind: repeatActivity
+            gapAllowance: 2
+            threshold: '>= 4'
+            window:
+              count: 50
+              duration: 6 months
+          - name: lowOrOpComm
+            kind: history
+            criteriaJoin: OR
+            criteria:
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: < 50%
+              - window:
+                  count: 100
+                  duration: 6 months
+                comment: '> 40% OP'
+        actions:
+          - kind: report
+            enable: true
+            content: >-
+              Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
+              {{rules.loworopcomm.thresholdSummary}}
+          - kind: remove
+            enable: false
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed because you cross-posted it
+              {{rules.xpostlow.largestRepeat}} times and you have very low
+              engagement outside of making submissions
+            distinguish: true
+            dryRun: true
+        # Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+      - name: freekarma removal
+        description: Remove submission if user has used freekarma sub recently
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            window:
+              count: 50
+              duration: 6 months
+            useSubmissionAsReference: false
+            thresholds:
+              - subreddits:
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - KarmaStore
+                  - promote
+                  - shamelessplug
+                  - upvote
+        actions:
+          - kind: report
+            enable: true
+            content: 'Remove=> {{rules.newtube.totalCount}} activities in freekarma subs'
+          - kind: remove
+            enable: false
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed because you have recent activity in
+              'freekarma' subs
+            distinguish: true
+            dryRun: true

docs/examples/subredditReady/freekarma.json5

@@ -2,63 +2,67 @@
   "polling": [
     "unmoderated"
   ],
-  "checks": [
+  "runs": [
     {
-      //
-      // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
-      //
-      "name": "freekarma removal",
-      "description": "Remove submission if user has used freekarma sub recently",
-      "kind": "submission",
-      "itemIs": [
+      "checks": [
         {
-          "removed": false
-        }
-      ],
-      "condition": "AND",
-      "rules": [
-        {
-          "name": "freekarma",
-          "kind": "recentActivity",
-          "window": {
-            "count": 50,
-            "duration": "6 months"
-          },
-          "useSubmissionAsReference": false,
-          "thresholds": [
+          //
+          // Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+          //
+          "name": "freekarma removal",
+          "description": "Remove submission if user has used freekarma sub recently",
+          "kind": "submission",
+          "itemIs": [
             {
-              "subreddits": [
-                "FreeKarma4U",
-                "FreeKarma4You",
-                "KarmaStore",
-                "upvote"
+              "removed": false
+            }
+          ],
+          "condition": "AND",
+          "rules": [
+            {
+              "name": "freekarma",
+              "kind": "recentActivity",
+              "window": {
+                "count": 50,
+                "duration": "6 months"
+              },
+              "useSubmissionAsReference": false,
+              "thresholds": [
+                {
+                  "subreddits": [
+                    "FreeKarma4U",
+                    "FreeKarma4You",
+                    "KarmaStore",
+                    "upvote"
+                  ]
+                }
               ]
             }
+          ],
+          "actions": [
+            // remove this after confirming behavior is acceptable
+            {
+              "kind": "report",
+              "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true,
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
+              "distinguish": true,
+              "dryRun": true,
+            }
           ]
         }
-      ],
-      "actions": [
-        // remove this after confirming behavior is acceptable
-        {
-          "kind": "report",
-          "content": "Remove=> {{rules.newtube.totalCount}} activities in freekarma subs"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true,
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed because you have recent activity in 'freekarma' subs",
-          "distinguish": true,
-          "dryRun": true,
-        }
       ]
     }
-  ]
+  ],
 }

docs/examples/subredditReady/freekarma.yaml

@@ -0,0 +1,36 @@
+polling:
+  - unmoderated
+runs:
+  - checks:
+      # Remove submissions from users who have recent activity in freekarma subs within the last 50 activities or 6 months (whichever is less)
+      - name: freekarma removal
+        description: Remove submission if user has used freekarma sub recently
+        kind: submission
+        itemIs:
+          - removed: false
+        condition: AND
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            window:
+              count: 50
+              duration: 6 months
+            useSubmissionAsReference: false
+            thresholds:
+              - subreddits:
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - KarmaStore
+                  - upvote
+        actions:
+          - kind: report
+            enable: true
+            content: 'Remove=> {{rules.newtube.totalCount}} activities in freekarma subs'
+          - kind: remove
+            enable: true
+          - kind: comment
+            enable: false
+            content: >-
+              Your submission has been removed because you have recent activity in
+              'freekarma' subs
+            distinguish: true

docs/examples/subredditReady/selfPromo.json5

@@ -2,48 +2,30 @@
   "polling": [
     "unmoderated"
   ],
-  "checks": [
+  "runs": [
     {
-      //
-      // Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
-      // https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
-      //
-      // Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
-      //
-      // if link comprises 10% of submission history (100 activities or 6 months)
-      // AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
-      //
-      "name": "Self-promo all AND low engagement",
-      "description": "Self-promo is >10% for all or just sub and low comment engagement",
-      "kind": "submission",
-      "condition": "OR",
-      "rules": [
+      "checks": [
         {
-          "name": "attr",
-          "kind": "attribution",
-          "criteria": [
-            {
-              "threshold": ">= 10%",
-              "window": {
-                "count": 100,
-                "duration": "6 months"
-              },
-              "domains": [
-                "AGG:SELF"
-              ]
-            }
-          ],
-        },
-        {
-          "condition": "AND",
+          //
+          // Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
+          // https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
+          //
+          // Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
+          //
+          // if link comprises 10% of submission history (100 activities or 6 months)
+          // AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+          //
+          "name": "Self-promo all AND low engagement",
+          "description": "Self-promo is >10% for all or just sub and low comment engagement",
+          "kind": "submission",
+          "condition": "OR",
           "rules": [
             {
-              "name": "attrsub",
+              "name": "attr",
               "kind": "attribution",
               "criteria": [
                 {
                   "threshold": ">= 10%",
-                  "thresholdOn": "submissions",
                   "window": {
                     "count": 100,
                     "duration": "6 months"
@@ -52,52 +34,74 @@
                     "AGG:SELF"
                   ]
                 }
-              ]
+              ],
             },
             {
-              "name": "lowOrOpComm",
-              "kind": "history",
-              "criteriaJoin": "OR",
-              "criteria": [
+              "condition": "AND",
+              "rules": [
                 {
-                  "window": {
-                    "count": 100,
-                    "duration": "6 months"
-                  },
-                  "comment": "< 50%"
+                  "name": "attrsub",
+                  "kind": "attribution",
+                  "criteria": [
+                    {
+                      "threshold": ">= 10%",
+                      "thresholdOn": "submissions",
+                      "window": {
+                        "count": 100,
+                        "duration": "6 months"
+                      },
+                      "domains": [
+                        "AGG:SELF"
+                      ]
+                    }
+                  ]
                 },
                 {
-                  "window": {
-                    "count": 100,
-                    "duration": "6 months"
-                  },
-                  "comment": "> 40% OP"
+                  "name": "lowOrOpComm",
+                  "kind": "history",
+                  "criteriaJoin": "OR",
+                  "criteria": [
+                    {
+                      "window": {
+                        "count": 100,
+                        "duration": "6 months"
+                      },
+                      "comment": "< 50%"
+                    },
+                    {
+                      "window": {
+                        "count": 100,
+                        "duration": "6 months"
+                      },
+                      "comment": "> 40% OP"
+                    }
+                  ]
                 }
               ]
             }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}} => {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}"
+            },
+            //
+            //
+            {
+              "kind": "remove",
+              // remove the line below after confirming behavior is acceptable
+              "dryRun": true
+            },
+            // optionally remove "dryRun" from below if you want to leave a comment on removal
+            // PROTIP: the comment is bland, you should make it better
+            {
+              "kind": "comment",
+              "content": "Your submission has been removed it comprises 10% or more of your recent history ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This is against [reddit's self promotional guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)",
+              "distinguish": true,
+              "dryRun": true
+            }
           ]
         }
-      ],
-      "actions": [
-        {
-          "kind": "report",
-          "content": "{{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}} => {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}"
-        },
-        //
-        //
-        {
-          "kind": "remove",
-          // remove the line below after confirming behavior is acceptable
-          "dryRun": true
-        },
-        // optionally remove "dryRun" from below if you want to leave a comment on removal
-        // PROTIP: the comment is bland, you should make it better
-        {
-          "kind": "comment",
-          "content": "Your submission has been removed it comprises 10% or more of your recent history ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This is against [reddit's self promotional guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)",
-          "distinguish": true,
-          "dryRun": true
-        }
       ]
     }
   ]

docs/examples/subredditReady/selfPromo.yaml

@@ -0,0 +1,72 @@
+polling:
+  - unmoderated
+runs:
+  - checks:
+      #
+      # Stop users who make link submissions with a self-promotional agenda (with reddit's suggested 10% rule)
+      # https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit
+      #
+      # Remove a SUBMISSION if the link comprises more than or equal to 10% of users history (100 activities or 6 months) OR
+      #
+      # if link comprises 10% of submission history (100 activities or 6 months)
+      # AND less than 50% of their activity is comments OR more than 40% of those comments are as OP (in the own submissions)
+      #
+      - name: Self-promo all AND low engagement
+        description: Self-promo is >10% for all or just sub and low comment engagement
+        kind: submission
+        condition: OR
+        rules:
+          - name: attr
+            kind: attribution
+            criteria:
+              - threshold: '>= 10%'
+                window:
+                  count: 100
+                  duration: 6 months
+                domains:
+                  - 'AGG:SELF'
+          - condition: AND
+            rules:
+              - name: attrsub
+                kind: attribution
+                criteria:
+                  - threshold: '>= 10%'
+                    thresholdOn: submissions
+                    window:
+                      count: 100
+                      duration: 6 months
+                    domains:
+                      - 'AGG:SELF'
+              - name: lowOrOpComm
+                kind: history
+                criteriaJoin: OR
+                criteria:
+                  - window:
+                      count: 100
+                      duration: 6 months
+                    comment: < 50%
+                  - window:
+                      count: 100
+                      duration: 6 months
+                    comment: '> 40% OP'
+        actions:
+          - kind: report
+            enable: true
+            content: >-
+              {{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}} of
+              {{rules.attr.activityTotal}}{{rules.attrsub.activityTotal}} items
+              ({{rules.attr.window}}{{rules.attrsub.window}}){{#rules.loworopcomm.thresholdSummary}}
+              =>
+              {{rules.loworopcomm.thresholdSummary}}{{/rules.loworopcomm.thresholdSummary}}
+          - kind: remove
+            enable: false
+          - kind: comment
+            enable: true
+            content: >-
+              Your submission has been removed it comprises 10% or more of your
+              recent history
+              ({{rules.attr.largestPercent}}{{rules.attrsub.largestPercent}}). This
+              is against [reddit's self promotional
+              guidelines.](https://www.reddit.com/wiki/selfpromotion#wiki_guidelines_for_self-promotion_on_reddit)
+            distinguish: true
+            dryRun: true

docs/examples/userNotes/README.md

@@ -14,7 +14,7 @@ Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FUserNoteCr
 
 ### Examples
 
-* [Do not tag user with Good User note](/docs/examples/userNotes/usernoteFilter.json5)
+* Do not tag user with Good User note [JSON](/docs/examples/userNotes/usernoteFilter.json5) | [YAML](/docs/examples/userNotes/usernoteFilter.yaml)
 
 ## Action
 
@@ -23,4 +23,4 @@ A User Note can also be added to the Author of a Submission or Comment with the
 
 ### Examples
 
-* [Add note on user doing self promotion](/docs/examples/userNotes/usernoteSP.json5)
+* Add note on user doing self promotion [JSON](/docs/examples/userNotes/usernoteSP.json5) | [YAML](/docs/examples/userNotes/usernoteSP.yaml)

docs/examples/userNotes/usernoteFilter.json5

@@ -1,43 +1,47 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Activities",
-      "description": "Tag SP only if user does not have good contributor user note",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          "author": {
-            "exclude": [
-              {
-                // the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-                // rule will not run if current usernote on Author is of type 'gooduser'
-                "type": "gooduser"
-              }
-            ]
-          },
-          "criteria": [
+          "name": "Self Promo Activities",
+          "description": "Tag SP only if user does not have good contributor user note",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": "> 10%",
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "window": 100
+              "name": "attr10all",
+              "kind": "attribution",
+              "author": {
+                "exclude": [
+                  {
+                    // the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+                    // rule will not run if current usernote on Author is of type 'gooduser'
+                    "type": "gooduser"
+                  }
+                ]
+              },
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "usernote",
-          // the key of usernote type
-          // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-          "type": "spamwarn",
-          // content is mustache templated as usual
-          "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+          "actions": [
+            {
+              "kind": "usernote",
+              // the key of usernote type
+              // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+              "type": "spamwarn",
+              // content is mustache templated as usual
+              "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+            }
+          ]
         }
       ]
     }

docs/examples/userNotes/usernoteFilter.yaml

@@ -0,0 +1,28 @@
+runs:
+  - checks:
+      - name: Self Promo Activities
+        description: Tag SP only if user does not have good contributor user note
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        kind: submission
+        rules:
+          - name: attr10all
+            kind: attribution
+            author:
+              exclude:
+                # the key of the usernote type to look for https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+                # rule will not run if current usernote on Author is of type 'gooduser'
+                - type: gooduser
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+        actions:
+          - kind: usernote
+            # the key of usernote type
+            # https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+            type: spamwarn
+            # content is mustache templated
+            content: >-
+              Self Promotion: {{rules.attr10all.titlesDelim}}
+              {{rules.attr10sub.largestPercent}}%

docs/examples/userNotes/usernoteSP.json5

@@ -1,34 +1,38 @@
 {
-  "checks": [
+  "runs": [
     {
-      "name": "Self Promo Activities",
-      "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
-      // check will run on a new submission in your subreddit and look at the Author of that submission
-      "kind": "submission",
-      "rules": [
+      "checks": [
         {
-          "name": "attr10all",
-          "kind": "attribution",
-          "criteria": [
+          "name": "Self Promo Activities",
+          "description": "Check if any of Author's aggregated submission origins are >10% of entire history",
+          // check will run on a new submission in your subreddit and look at the Author of that submission
+          "kind": "submission",
+          "rules": [
             {
-              "threshold": "> 10%",
-              "window": "90 days"
-            },
-            {
-              "threshold": "> 10%",
-              "window": 100
+              "name": "attr10all",
+              "kind": "attribution",
+              "criteria": [
+                {
+                  "threshold": "> 10%",
+                  "window": "90 days"
+                },
+                {
+                  "threshold": "> 10%",
+                  "window": 100
+                }
+              ],
             }
           ],
-        }
-      ],
-      "actions": [
-        {
-          "kind": "usernote",
-          // the key of usernote type
-          // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
-          "type": "spamwarn",
-          // content is mustache templated as usual
-          "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+          "actions": [
+            {
+              "kind": "usernote",
+              // the key of usernote type
+              // https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+              "type": "spamwarn",
+              // content is mustache templated as usual
+              "content": "Self Promotion: {{rules.attr10all.titlesDelim}} {{rules.attr10sub.largestPercent}}%"
+            }
+          ]
         }
       ]
     }

docs/examples/userNotes/usernoteSP.yaml

@@ -0,0 +1,24 @@
+runs:
+  - checks:
+      - name: Self Promo Activities
+        # check will run on a new submission in your subreddit and look at the Author of that submission
+        description: >-
+          Check if any of Author's aggregated submission origins are >10% of entire
+          history
+        kind: submission
+        rules:
+          - name: attr10all
+            kind: attribution
+            criteria:
+              - threshold: '> 10%'
+                window: 90 days
+              - threshold: '> 10%'
+                window: 100
+        actions:
+          - kind: usernote
+            # the key of usernote type
+            # https://github.com/toolbox-team/reddit-moderator-toolbox/wiki/Subreddit-Wikis%3A-usernotes#working-with-note-types
+            type: spamwarn
+            content: >-
+              Self Promotion: {{rules.attr10all.titlesDelim}}
+              {{rules.attr10sub.largestPercent}}%

docs/gettingStartedMod.md

@@ -4,7 +4,9 @@ This getting started guide is for **reddit moderators** -- that is, someone who
 # Table of Contents
 
 * [Prior Knowledge](#prior-knowledge)
-* [Mod the Bot](#mod-the-bot)
+* [Choose A Bot](#choose-a-bot)
+  * [Use The Operator's Bot](#use-the-operators-bot)
+  * [Bring Your Own Bot (BYOB)](#bring-your-own-bot-byob)
 * [Creating Configuration](#configuring-the-bot)
 * [Monitor the Bot](#monitor-the-bot)
 
@@ -12,32 +14,87 @@ This getting started guide is for **reddit moderators** -- that is, someone who
 
 Before continuing with this guide you should first make sure you understand how a ContextMod works. Please review this documentation:
 
-* [How It Works](/docs#how-it-works)
-* [Core Concepts](/docs#concepts)
+* [How It Works](/docs/README.md#how-it-works)
+* [Core Concepts](/docs/README.md#concepts)
 
-# Mod The Bot
+# Choose A Bot
 
-First ensure that you are in communication with the **operator** for this bot. The bot **will not automatically accept a moderator invitation,** it must be manually done by the bot operator. This is an intentional barrier to ensure moderators and the operator are familiar with their respective needs and have some form of trust.
+First determine what bot (reddit account) you want to run ContextMod with. (You may have already discussed this with your operator)
+
+## Use the Operator's Bot
+
+If the Operator has communicated that **you should add a bot they control as a moderator** to your subreddit this is the option you will use.
+
+**Pros:**
+
+* Do not have to create and keep track of another reddit account
+* Easiest option in terms of setup for both moderators and operator
+
+**Cons:**
+
+* Shared api quota among other moderated subreddits (not great for high-volume subreddits)
+
+___
+
+Ensure that you are in communication with the **operator** of this bot. The bot **will only accept a moderator invitation if your subreddit has been whitelisted by the operator.** This is an intentional barrier to ensure moderators and the operator are familiar with their respective needs and have some form of trust.
 
 Now invite the bot to moderate your subreddit. The bot should have at least these permissions:
 
 * Manage Users
 * Manage Posts and Comments
 * Manage Flair
+* Manage Wiki Pages
+  * Required to read the moderator-only visible wiki page used to configure the bot
+  * Required to read/write to [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes)
 
-Additionally, the bot must have the **Manage Wiki Pages** permission if you plan to use [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes). If you are not planning on using this feature and do not want the bot to have this permission then you **must** ensure the bot has visibility to the configuration wiki page (detailed below).
+## Bring Your Own Bot (BYOB)
+
+If the operator has communicated that **they want to use a bot you control** this is the option you will use.
+
+**Pros:**
+
+* **Dedicated API quota**
+  * This is basically a requirement if your subreddit has high-volume activity and you plan on running checks on comments
+* More security guarantees since you control the account 
+  * **Note:** authenticating an account does NOT give the operator access to view or change the email/password for the account
+* Established history in your subreddit
+
+**Cons:**
+
+* You must have access to the credentials for the reddit account (bot)
+
+___
+
+The **operator** will send you an **invite link** that you will use to authenticate your bot with the operator's application. Example link: `https://operatorsUrl.com/auth/invite?invite=4kf9n3o03ncd4nd`
+
+Review the information shown on the invite link webpage and then follow the directions shown to authorize your bot for the operator.
+
+**Note:** There is information display **after** authentication that you will need to communicate to your operator -- **Refresh** and **Access** token values. Make sure you save these somewhere as the invite link is **one-use only.**
 
 # Configuring the Bot
 
+The bot's behavior is defined using a configuration, like automoderator, that is stored in the **wiki** of each subreddit it moderates.
+
+The default location for this page is at `https://old.reddit.com/r/YOURSUBERDDIT/wiki/botconfig/contextbot`
+
 ## Setup wiki page
 
+The bot automatically tries to create its configuration wiki page. You can find the result of this in the log for your subreddit in the web interface.
+
+If this fails for some reason you can create the wiki page through the web interface by navigating to your subreddit's tab, opening the [built-in editor (click **View**)](/docs/images/configBox.png), and following the directions in **Create configuration for...** link found there.
+
+If neither of the above approaches work, or you do not wish to use the web interface, expand the section below for directions on how to manually setup the wiki page:
+
+<details>
+
 * Visit the wiki page of the subreddit you want the bot to moderate
   * The default location the bot checks for a configuration is at `https://old.reddit.com/r/YOURSUBERDDIT/wiki/botconfig/contextbot`
   * If the page does not exist create it
 * Ensure the wiki page visibility is restricted
   * On the wiki page click **settings** (**Page settings** in new reddit)
   * Check the box for **Only mods may edit and view** and then **save**
-    * Alternatively, if you did not give the bot the **Manage Wiki Pages** permission then add it to the **allow users to edit page** setting
+
+</details>
 
 ## Procure a configuration
 
@@ -51,25 +108,46 @@ Visit the [Examples](https://github.com/FoxxMD/context-mod/tree/master/docs/exam
 
 After you have found a configuration to use as a starting point:
 
-* In a new tab open the github page for the configuration you want ([example](/docs/examples/repeatActivity/crosspostSpamming.json5))
-* Click the **Raw** button, then select all and copy all of the text to your clipboard.
+* Copy the URL for the configuration file EX `https://github.com/FoxxMD/context-mod/blob/master/docs/examples/subredditReady/freekarma.json5` and either:
+  * (Easiest) **Load** it into your [subreddit's built-in editor](#using-the-built-in-editor) and **Save**
+  * or on the file's page, click the **Raw** button, select all and copy to your clipboard, and [manually save to your wiki page](#manually-saving)
 
 ### Build Your Own Config
 
-Additionally, you can use [this schema editor](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) to build your configuration. The editor features a ton of handy features:
+CM comes equipped with a [configuration explorer](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) to help you see all available options, with descriptions and examples, that can be used in your configuration.
 
-* fully annotated configuration data/structure
-* generated examples in json/yaml
-* built-in editor that automatically validates your config
+To create or edit a configuration you should use **CM's buit-in editor** which features:
+* syntax validation and formatting
+* full configuration validation with error highlighting, hints, and fixes
+* hover over properties to see documentation and examples
 
-PROTIP: Find an example config to use as a starting point and then build on it using the editor.
+To use the editor either:
+* [use your subreddit's built-in editor](#using-the-built-in-editor)
+* or use the public editor at https://cm.foxxmd.dev/config
+
+PROTIP: Find an [example config](#using-an-example-config) to use as a starting point and then build on it using the editor.
 
 ## Saving Your Configuration
 
-* Open the wiki page you created in the [previous step](#setup-wiki-page) and click **edit**
+### Using the built-in Editor
+
+In the web interface each subreddit's tab has access to the built-in editor. Use this built-in editor to automatically create, load, or save the configuration for that subreddit's wiki.
+
+* Visit the tab for the subreddit you want to edit the configuration of
+* Open the [built-in editor by click **View**](/docs/images/configBox.png)
+* Edit your configuration
+* Follow the directions on the **Save to r/..** link found at the top of the editor to automatically save your configuration
+
+### Manually Saving
+
+<details>
+
+* Open the wiki page you created in the [wiki setup step](#setup-wiki-page) and click **edit**
   * Copy-paste your configuration into the wiki text box
   * Save the edited wiki page
 
+</details>
+
 ___
 
 The bot automatically checks for new configurations on your wiki page every 5 minutes. If your operator has the web interface accessible you may login there and force the config to update on your subreddit.

docs/gettingStartedOperator.md

@@ -22,13 +22,14 @@ PROTIP: Using a container management tool like [Portainer.io CE](https://www.por
 
 ### [Dockerhub](https://hub.docker.com/r/foxxmd/context-mod)
 
-```
-foxxmd/context-mod:latest
-```
+An example of starting the container using the [minimum configuration](/docs/operatorConfiguration.md#minimum-config) with a [configuration file](/docs/operatorConfiguration.md#defining-configuration-via-file):
+
+* Bind the folder where the config is located on your host machine into the container `-v /host/path/folder:/config`
+* Tell CM where to find the config using an env `-e "OPERATOR_CONFIG=/config/myConfig.yaml"`
+* Expose the web interface using the container port `8085`
 
-Adding **environmental variables** to your `docker run` command will pass them through to the app EX:
 ```
-docker run -d -e "CLIENT_ID=myId" ... foxxmd/context-mod
+docker run -d -e "OPERATOR_CONFIG=/config/myConfig.yaml" -v /host/path/folder:/config -p 8085:8085 foxxmd/context-mod
 ```
 
 ### Locally
@@ -47,12 +48,30 @@ npm install
 tsc -p .
 ```
 
+An example of running CM using the [minimum configuration](/docs/operatorConfiguration.md#minimum-config) with a [configuration file](/docs/operatorConfiguration.md#defining-configuration-via-file):
+
+```bash
+node src/index.js run
+```
+
 ### [Heroku Quick Deploy](https://heroku.com/about)
 [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?template=https://github.com/FoxxMD/context-mod)
 
+This template provides a **web** and **worker** dyno for heroku.
+
+* **Web** -- Will run the bot **and** the web interface for ContextMod.
+* **Worker** -- Will run **just** the bot.
+
+Be aware that Heroku's [free dyno plan](https://devcenter.heroku.com/articles/free-dyno-hours#dyno-sleeping) enacts some limits:
+
+* A **Web** dyno will go to sleep (pause) after 30 minutes without web activity -- so your bot will ALSO go to sleep at this time
+* The **Worker** dyno **will not** go to sleep but you will NOT be able to access the web interface. You can, however, still see how Cm is running by reading the logs for the dyno.
+
+If you want to use a free dyno it is recommended you perform first-time setup (bot authentication and configuration, testing, etc...) with the **Web** dyno, then SWITCH to a **Worker** dyno so it can run 24/7.
+
 # Bot Authentication
 
-Next you need to create your bot and authenticate it with Reddit. Follow the [bot authentication guide](/docs/botAuthentication.md) to complete this step.
+Next you need to create a bot and authenticate it with Reddit. Follow the [bot authentication guide](/docs/botAuthentication.md) to complete this step.
 
 # Instance Configuration
 

docs/imageComparison.md

@@ -0,0 +1,237 @@
+# Overview
+
+ContextMod supports comparing image content, for the purpose of detecting duplicates, with two different but complimentary systems. Image comparison behavior is available for the following rules:
+
+* [Recent Activity](/docs/examples/recentActivity)
+* Repeat Activity (In-progress)
+
+To enable comparisons reference the example below (at the top-level of your rule) and configure as needed:
+
+JSON
+```json5
+{
+  "name": "ruleWithImageDetection",
+  "kind": "recentActivity",
+  // Add block below...
+  // 
+  "imageDetection": {
+    // enables image comparison
+    "enable": true,
+    // The difference, in percentage, between the reference submission and the submissions being checked
+    // must be less than this number to consider the images "the same"
+    "threshold": 5,
+    // optional
+    // set the behavior for determining if image comparison should occur on a URL:
+    //
+    // "extension" => try image detection if URL ends in a known image extension (jpeg, gif, png, bmp, etc.)
+    // "unknown"   => try image detection if URL ends in known image extension OR there is no extension OR the extension is unknown (not video, html, doc, etc...)
+    // "all"       => ALWAYS try image detection, regardless of URL extension
+    //
+    // if fetchBehavior is not defined then "extension" is the default
+    "fetchBehavior": "extension",
+  },
+  //
+  // And above ^^^
+  //...
+}
+```
+YAML
+```yaml
+name: ruleWithImageDetection
+kind: recentActivity
+  enable: true
+  threshold: 5
+  fetchBehavior: extension
+
+```
+
+**Perceptual Hashing** (`hash`) and **Pixel Comparisons** (`pixel`) may be used at the same time. Refer to the documentation below to see how they interact.
+
+**Note:** Regardless of `fetchBehavior`, if the response from the URL does not indicate it is an image then image detection will not occur. IE Response `Content-Type` must contain `image`
+
+## Prerequisites
+
+Both image comparison systems require [Sharp](https://sharp.pixelplumbing.com/) as a dependency. Most modern operating systems running Node.js >= 12.13.0 do not require installing additional dependencies in order to use Sharp. 
+
+If you are using the docker image for ContextMod (`foxxmd/context-mod`) Sharp is built-in.
+
+If you are installing ContextMod using npm then **Sharp should be installed automatically as an optional dependency.** 
+
+**If you do not want to install it automatically** install ContextMod with the following command:
+
+```
+npm install --no-optional
+```
+
+If you are using ContextMod as part of a larger project you may want to require Sharp in your own package:
+
+```
+npm install sharp@0.29.1 --save
+```
+
+# Comparison Systems
+
+## Perceptual Hashing
+
+[Perceptual Hashing](https://en.wikipedia.org/wiki/Perceptual_hashing) creates a text fingerprint of an image by:
+
+* Dividing up the image into a grid
+* Using an algorithm to derive a value from the pixels in each grid
+* Adding up all the values to create a unique string (the "fingerprint")
+
+An example of how a perceptual hash can work [can be found here.](https://www.hackerfactor.com/blog/?/archives/432-Looks-Like-It.html)
+
+ContextMod uses [blockhash-js](https://github.com/commonsmachinery/blockhash-js) which is a javascript implementation of the algorithm described in the paper [Block Mean Value Based Image Perceptual Hashing by Bian Yang, Fan Gu and Xiamu Niu.](https://ieeexplore.ieee.org/document/4041692)
+
+
+**Advantages**
+
+* Low memory requirements and not CPU intensive
+* Does not require any image transformations
+* Hash results can be stored to make future comparisons even faster and skip downloading images (cached by url)
+* Resolution-independent
+
+**Disadvantages**
+
+* Hash is weak when image differences are based only on color
+* Hash is weak when image contains lots of text
+* Higher accuracy requires larger calculation (more bits required)
+
+**When should I use it?**
+
+* General duplicate detection
+* Comparing many images
+* Comparing the same images often
+
+### How To Use
+
+If `imageDetection.enable` is `true` then hashing is enabled by default and no further configuration is required.
+
+To further configure hashing refer to this code block:
+
+```json5
+{
+  "name": "ruleWithImageDetectionAndConfiguredHashing",
+  "kind": "recentActivity",
+  "imageDetection": {
+    "enable": true,
+    // Add block below...
+    //
+    "hash": {
+      // enable or disable hash comparisons (enabled by default)
+      "enable": true,
+      // determines accuracy of hash and granularity of hash comparison (comparison to other hashes)
+      // the higher the bits the more accurate the comparison
+      //
+      // NOTE: Hashes of different sizes (bits) cannot be compared. If you are caching hashes make sure all rules where results may be shared use the same bit count to ensure hashes can be compared. Otherwise hashes will be recomputed.
+      "bits": 32,
+      // default is 32 if not defined
+      //
+      // number of seconds to cache an image hash
+      "ttl": 60,
+      // default is 60 if not defined
+      //
+      // "High Confidence" Threshold
+      // If the difference in comparison is equal to or less than this number the images are considered the same and pixel comparison WILL NOT occur
+      //
+      // Defaults to the parent-level `threshold` value if not present
+      //
+      // Use null if you want pixel comparison to ALWAYS occur (softThreshold must be present)
+      "hardThreshold": 5,
+      //
+      // "Low Confidence" Threshold -- only used if `pixel` is enabled
+      // If the difference in comparison is:
+      //
+      // 1) equal to or less than this value and
+      // 2) the value is greater than `hardThreshold`
+      //
+      // the images will be compared using the `pixel` method
+      "softThreshold": 0,
+    },
+    //
+    // And above ^^^
+    //"pixel": {...}
+  }
+  //...
+}
+```
+YAML
+```yaml
+name: ruleWithImageDetectionAndConfiguredHashing
+kind: recentActivity
+imageDetection:
+  enable: true
+  hash:
+    enable: true
+    bits: 32
+    ttl: 60
+    hardThreshold: 5
+    softThreshold: 0
+```
+
+## Pixel Comparison
+
+This approach is as straight forward as it sounds. Both images are compared, pixel by pixel, to determine the difference between the two. ContextMod uses [pixelmatch](https://github.com/mapbox/pixelmatch) to do the comparison.
+
+**Advantages**
+
+* Extremely accurate, high-confidence on difference percentage
+* Strong when comparing text-based images or color-only differences
+
+**Disadvantages**
+
+* High memory requirements (10-30MB per comparison) and CPU intensive
+* Weak against similar images with different aspect ratios
+* Requires image transformations (resize, crop) before comparison
+* Can only store image-to-image results (no single image fingerprints)
+
+**When should I use it?**
+
+* Require very high accuracy in comparison results
+* Comparing mostly text-based images or subtle color/detail differences
+* As a secondary, high-confidence confirmation of comparison result after hashing
+
+### How To Use
+
+By default pixel comparisons **are not enabled.** They must be explicitly enabled in configuration.
+
+Pixel comparisons will be performed in either of these scenarios:
+
+* pixel is enabled, hashing is enabled and `hash.softThreshold` is defined
+  * When a comparison occurs that is less different than `softThreshold` but more different then `hardThreshold` (or `"hardThreshold": null`), then pixel comparison will occur as a high-confidence check
+  * Example
+    * hash comparison => 7% difference
+    * `"softThreshold": 10`
+    * `"hardThreshold": 4`
+* `hash.enable` is `false` and `pixel.enable` is true
+  * hashing is skipped entirely and only pixel comparisons are performed 
+
+To configure pixel comparisons refer to this code block:
+
+```json5
+{
+  "name": "ruleWithImageDetectionAndPixelEnabled",
+  "kind": "recentActivity",
+  "imageDetection": {
+    //"hash": {...}
+    "pixel": {
+      // enable or disable pixel comparisons (disabled by default)
+      "enable": true,
+      // if the comparison difference percentage is equal to or less than this value the images are considered the same
+      //
+      // if not defined the value from imageDetection.threshold will be used
+      "threshold": 5
+    }
+  },
+  //...
+}
+```
+YAML
+```yaml
+name: ruleWithImageDetectionAndPixelEnabled
+kind: recentActivity
+imageDetection:
+  pixel:
+    enable: true
+    threshold: 5
+```