feat: Support multiple expressions for regex property

* Specify docker-compose minimum version
* Change commands to use new syntax

.dockerignore

@@ -1,6 +1,29 @@
-node_modules
-Dockerfile
-.dockerignore
-.gitignore
 .git
-src/logs
+logs
+.github
+_site
+.bundle
+vendor
+docs/.jekyll-cache
+node_modules
+coverage
+.nyc_output
+.idea
+*.bak
+*.sqlite
+*.sqlite*
+*.json
+*.json5
+*.yaml
+*.yml
+*.env
+
+# exceptions
+!heroku.yml
+!app.json
+!.nycrc.json
+!.mocharc.json
+!tsconfig.json
+!package*.json
+!docker/config/**
+!_config.yml

.github/FUNDING.yml

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

.github/push-hook-sample.json

@@ -0,0 +1,3 @@
+{
+  "ref": "refs/heads/edge"
+}

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0' # Not needed with a .ruby-version file
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v1
+      - run: bundle exec jekyll build --baseurl ${{ steps.pages.outputs.base_path }} # defaults output to '/_site'
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1 # This will automatically upload an artifact from the '/_site' directory
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/publishImage.yml

@@ -0,0 +1,74 @@
+name: Publish Docker image to registries
+
+# Builds image and tags based on the type of push event:
+# * branch push -> tag is branch name IE context-mod:edge
+# * release (tag) -> tag is release name IE context-mod:0.13.0
+#
+# Then pushes tagged images to multiple registries
+#
+# Based on
+# https://github.com/docker/build-push-action/blob/master/docs/advanced/push-multi-registries.md
+# https://github.com/docker/metadata-action
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'edge'
+    tags:
+      - '*.*.*'
+    # don't trigger if just updating docs
+    paths-ignore:
+      - '**.md'
+
+jobs:
+  push_to_registry:
+    name: Build and Push Docker image to registries
+    runs-on: ubuntu-latest
+    # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v2
+      
+      - name: Log in to Docker Hub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v3
+        with:
+          images: |
+            foxxmd/context-mod
+            ghcr.io/foxxmd/context-mod
+          # generate Docker tags based on the following events/attributes
+          tags: |
+            type=raw,value=latest,enable=${{ endsWith(github.ref, 'master') }}
+            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
+            type=semver,pattern={{version}}
+          flavor: |
+            latest=false
+      
+      - name: Build and push Docker image
+        if: ${{ !env.ACT }}
+        uses: docker/build-push-action@v3
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+

.gitignore

@@ -336,6 +336,7 @@ web_modules/
 # dotenv environment variables file
 .env
 .env.test
+*.env
 
 # parcel-bundler cache (https://parceljs.org/)
 .cache
@@ -380,5 +381,30 @@ dist
 .yarn/install-state.gz
 .pnp.*
 
+# Copied from https://github.com/github/gitignore/blob/main/Jekyll.gitignore
+# Ignore metadata generated by Jekyll
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Ignore folders generated by Bundler
+.bundle/
+vendor/
+
 **/src/**/*.js
+**/tests/**/*.js
+**/tests/**/*.map
+!src/Web/assets/**
 **/src/**/*.map
+/**/*.sqlite
+/**/*.bak
+*.yaml
+*.json5
+
+!src/Schema/*.json
+!.github/push-hook-sample.json
+!docs/**/*.json5
+!docs/**/*.yaml
+!docs/**/*.json
+!docker/config/**

.idea/redditcontextbot.iml

@@ -2,10 +2,16 @@
 <module type="WEB_MODULE" version="4">
   <component name="NewModuleRootManager">
     <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/tests" isTestSource="true" />
       <excludeFolder url="file://$MODULE_DIR$/temp" />
       <excludeFolder url="file://$MODULE_DIR$/.tmp" />
       <excludeFolder url="file://$MODULE_DIR$/tmp" />
       <excludeFolder url="file://$MODULE_DIR$/src/logs" />
+      <excludeFolder url="file://$MODULE_DIR$/coverage" />
+      <excludeFolder url="file://$MODULE_DIR$/.nyc_output" />
+      <excludeFolder url="file://$MODULE_DIR$/_site" />
+      <excludeFolder url="file://$MODULE_DIR$/docs/.jekyll-cache" />
+      <excludeFolder url="file://$MODULE_DIR$/vendor" />
     </content>
     <content url="file://$MODULE_DIR$/node_modules" />
     <orderEntry type="inheritedJdk" />

.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "require": ["./register.js", "source-map-support/register"],
+  "reporter": "dot"
+}

.nvmrc

@@ -0,0 +1 @@
+16.14.2

.nycrc.json

@@ -0,0 +1,24 @@
+{
+  "extends": "@istanbuljs/nyc-config-typescript",
+  "exclude": [
+    "node_modules/",
+    "**/src/Schema/**",
+    "**/src/Web/assets/**",
+    "**/tests/**",
+    "register.js",
+    "**/src/**/*.d.ts"
+  ],
+  "include": [
+    "**/src/**/*.ts",
+    "**/src/**/*.js",
+    "**/src/**/*.js.map"
+  ],
+  "extension": [
+    ".ts"
+  ],
+  "reporter": [
+    "text-summary",
+    "html"
+  ],
+  "report-dir": "./coverage"
+}

Dockerfile

@@ -1,27 +1,148 @@
-FROM node:16-alpine3.12
+FROM lsiobase/alpine:3.15 as base
 
 ENV TZ=Etc/GMT
 
-RUN apk update
+# borrowed from node/alpine:3.15
+# https://github.com/nodejs/docker-node/blob/main/16/alpine3.15/Dockerfile
+#
+# Start of node docker stuff
+#
+ENV NODE_VERSION 16.14.2
+
+RUN apk add --no-cache \
+        libstdc++ \
+    && apk add --no-cache --virtual .build-deps \
+        curl \
+    && ARCH= && alpineArch="$(apk --print-arch)" \
+      && case "${alpineArch##*-}" in \
+        x86_64) \
+          ARCH='x64' \
+          CHECKSUM="a6dc255e1ef1f20372306eec932b4a3648575c6d3024bcd685b8efc93dc95569" \
+          ;; \
+        *) ;; \
+      esac \
+  && if [ -n "${CHECKSUM}" ]; then \
+    set -eu; \
+    curl -fsSLO --compressed "https://unofficial-builds.nodejs.org/download/release/v$NODE_VERSION/node-v$NODE_VERSION-linux-$ARCH-musl.tar.xz"; \
+    echo "$CHECKSUM  node-v$NODE_VERSION-linux-$ARCH-musl.tar.xz" | sha256sum -c - \
+      && tar -xJf "node-v$NODE_VERSION-linux-$ARCH-musl.tar.xz" -C /usr/local --strip-components=1 --no-same-owner \
+      && ln -s /usr/local/bin/node /usr/local/bin/nodejs; \
+  else \
+    echo "Building from source" \
+    # backup build
+    && apk add --no-cache --virtual .build-deps-full \
+        binutils-gold \
+        g++ \
+        gcc \
+        gnupg \
+        libgcc \
+        linux-headers \
+        make \
+        python3 \
+    # gpg keys listed at https://github.com/nodejs/node#release-keys
+    && for key in \
+      4ED778F539E3634C779C87C6D7062848A1AB005C \
+      141F07595B7B3FFE74309A937405533BE57C7D57 \
+      94AE36675C464D64BAFA68DD7434390BDBE9B9C5 \
+      74F12602B6F1C4E913FAA37AD3A89613643B6201 \
+      71DCFD284A79C3B38668286BC97EC7A07EDE3FC1 \
+      8FCCA13FEF1D0C2E91008E09770F7A9A5AE15600 \
+      C4F0DFFF4E8C1A8236409D08E73BC641CC11F4C8 \
+      C82FA3AE1CBEDC6BE46B9360C43CEC45C17AB93C \
+      DD8F2338BAE7501E3DD5AC78C273792F7D83545D \
+      A48C2BEE680E841632CD4E44F07496B3EB3C1762 \
+      108F52B48DB57BB0CC439B2997B01419BD92F80A \
+      B9E2F5981AA6E0CD28160D9FF13993A75599653C \
+    ; do \
+      gpg --batch --keyserver hkps://keys.openpgp.org --recv-keys "$key" || \
+      gpg --batch --keyserver keyserver.ubuntu.com --recv-keys "$key" ; \
+    done \
+    && curl -fsSLO --compressed "https://nodejs.org/dist/v$NODE_VERSION/node-v$NODE_VERSION.tar.xz" \
+    && curl -fsSLO --compressed "https://nodejs.org/dist/v$NODE_VERSION/SHASUMS256.txt.asc" \
+    && gpg --batch --decrypt --output SHASUMS256.txt SHASUMS256.txt.asc \
+    && grep " node-v$NODE_VERSION.tar.xz\$" SHASUMS256.txt | sha256sum -c - \
+    && tar -xf "node-v$NODE_VERSION.tar.xz" \
+    && cd "node-v$NODE_VERSION" \
+    && ./configure \
+    && make -j$(getconf _NPROCESSORS_ONLN) V= \
+    && make install \
+    && apk del .build-deps-full \
+    && cd .. \
+    && rm -Rf "node-v$NODE_VERSION" \
+    && rm "node-v$NODE_VERSION.tar.xz" SHASUMS256.txt.asc SHASUMS256.txt; \
+  fi \
+  && rm -f "node-v$NODE_VERSION-linux-$ARCH-musl.tar.xz" \
+  && apk del .build-deps \
+  # smoke tests
+  && node --version \
+  && npm --version
+#
+# end of docker node stuff
+#
+
+# 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
+ARG data_dir=/config
+VOLUME $data_dir
+ENV DATA_DIR=$data_dir
 
-COPY package*.json ./
-COPY tsconfig.json .
+COPY docker/root/ /
+
+WORKDIR /app
+
+FROM base as build
+
+# copy NPM dependencies and install
+COPY --chown=abc:abc package*.json ./
+COPY --chown=abc:abc tsconfig.json .
 
 RUN npm install
 
-ADD . /usr/app
+# copy bundle/jekyll dependencies and docs folder
+COPY --chown=abc:abc Gemfile Gemfile.lock _config.yml ./
+COPY --chown=abc:abc docs ./docs/
 
-RUN npm run build
+# sassc (a jekll dependency) is very slow to compile bc there are no alpine binaries
+# https://github.com/sass/sassc-ruby/issues/189#issuecomment-629758948
+# so for now sync used jekyll version with prebuilt binary available in alpine repo
+RUN apk add --no-cache --virtual .build-deps \
+    ruby-jekyll \
+    && bundle install \
+    && jekyll build -b /docs \
+    && apk del .build-deps \
+    && rm -rf docs
+
+COPY --chown=abc:abc . /app
+
+RUN npm run build && rm -rf node_modules
+
+FROM base as app
+
+COPY --from=build --chown=abc:abc /app /app
+
+RUN npm install --production \
+    && npm cache clean --force \
+    && chown abc:abc node_modules \
+    && rm -rf node_modules/ts-node \
+    && rm -rf node_modules/typescript
 
 ENV NPM_CONFIG_LOGLEVEL debug
 
-ARG log_dir=/home/node/logs
-RUN mkdir -p $log_dir
-VOLUME $log_dir
-ENV LOG_DIR=$log_dir
+# can set database to use more performant better-sqlite3 since we control everything
+ENV DB_DRIVER=better-sqlite3
+
+# NODE_ARGS are expanded after `node` command in the entrypoint IE "node {NODE_ARGS} src/index.js run"
+# by default enforce better memory mangement by limiting max long-lived GC space to 512MB
+ENV NODE_ARGS="--max_old_space_size=512"
+
+ARG webPort=8085
+ENV PORT=$webPort
+EXPOSE $PORT
+
+# convenience variable for more helpful error messages
+ENV IS_DOCKER=true
 
-CMD [ "node", "src/index.js", "run" ]

Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+# sassc (a jekll dependency) is very slow to compile bc there are no alpine binaries
+# https://github.com/sass/sassc-ruby/issues/189#issuecomment-629758948
+# so for now sync used jekyll version with prebuilt binary available in alpine repo
+gem "jekyll", "4.2.2" # installed by `gem jekyll`
+# gem "webrick"        # required when using Ruby >= 3 and Jekyll <= 4.2.2
+
+gem "just-the-docs", "0.4.0.rc3" # currently the latest pre-release
+# gem "just-the-docs"            # the latest release - currently 0.3.3
+
+gem "jekyll-readme-index"
+gem 'jekyll-default-layout'
+gem 'jekyll-titles-from-headings'
+gem 'jekyll-relative-links'
+
+group :jekyll_plugins do
+  gem 'jekyll-optional-front-matter'
+end

Gemfile.lock

@@ -0,0 +1,90 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.1)
+      public_suffix (>= 2.0.2, < 6.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.10)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.15.5)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.8.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-default-layout (0.1.5)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-optional-front-matter (0.3.2)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-readme-index (0.3.0)
+      jekyll (>= 3.0, < 5.0)
+    jekyll-relative-links (0.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sass-converter (2.2.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-titles-from-headings (0.5.3)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.4.0.rc3)
+      jekyll (>= 3.8.5)
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.7.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (5.0.0)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.30.0)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.8.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  jekyll (= 4.2.2)
+  jekyll-default-layout
+  jekyll-optional-front-matter
+  jekyll-readme-index
+  jekyll-relative-links
+  jekyll-titles-from-headings
+  just-the-docs (= 0.4.0.rc3)
+
+BUNDLED WITH
+   2.3.25

README.md

@@ -1,46 +1,69 @@
-# reddit-context-bot
+---
+title: Home
+nav_order: 1
+---
+# 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)
 
-[![Latest Release](https://img.shields.io/github/v/release/foxxmd/reddit-context-bot)](https://github.com/FoxxMD/reddit-context-bot/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/reddit-context-bot)](https://hub.docker.com/r/foxxmd/reddit-context-bot)
+<img src="/docs/logo.png" align="right"
+alt="ContextMod logo" width="180" height="176">
 
-**Context Bot** 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/).
+[**Context Mod**](https://contextmod.dev/) (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/).
 
 It is designed to help fill in the gaps for [automoderator](https://www.reddit.com/wiki/automoderator/full-documentation) in regard to more complex behavior with a focus on **user-history based moderation.**
 
-An example of the above that Context Bot can do now:
+An example of the above that Context Bot can do:
 
 > * On a new submission, check if the user has also posted the same link in **N** number of other subreddits within a timeframe/# of posts
 > * On a new submission or comment, check if the user has had any activity (sub/comment) in **N** set of subreddits within a timeframe/# of posts
 >
 >In either instance Context Bot can then perform any action a moderator can (comment, report, remove, lock, etc...) against that user, comment, or submission.
 
-Some feature highlights:
-* Simple rule-action behavior can be combined to create any level of complexity in behavior
-* One instance can handle managing many subreddits (as many as it has moderator permissions in!)
-* Per-subreddit configuration is handled by JSON stored in the subreddit wiki
-* Any text-based actions (comment, submission, message, usernotes, etc...) can be configured via a wiki page or raw text in JSON
-* All text-based actions support [mustache](https://mustache.github.io) templating
-* 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.
-* Checks/Rules support skipping behavior based on:
-  * author criteria (name, css flair/text, 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 so you write rules/actions once and reference them anywhere
-* User-configurable 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
+Feature Highlights for **Moderators:**
+
+* Complete bot **autonomy**. YAML config is [stored in your subreddit's wiki](/docs/moderators/gettingStarted.md#setup-wiki-page) (like automoderator)
+* Simple rule-action behavior can be combined to create **complex behavior detection**
+* Support Activity filtering based on:
+  * [Author criteria](docs/subreddit-configuration/in-depth/filters/README.md#author-filter) (name, css flair/text, age, karma, moderator status, [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes), and more!)
+  * [Activity state](docs/subreddit-configuration/in-depth/filters/README.md#item-filter) (removed, locked, distinguished, etc...)
+  * State of Subreddit Activity is in [Subreddit](docs/subreddit-configuration/in-depth/filters/README.md#subreddit-filter) (nsfw, name, profile, etc...)
+* Rules and Actions support [named references](docs/subreddit-configuration/README.md#named-rules) -- **write once, reference anywhere**
+* Powerful [logic control](docs/subreddit-configuration/advancedConcepts/flowControl.md) (if, then, goto)
+* [Delay/re-process activities](docs/subreddit-configuration/README.md#dispatch) using arbitrary rules
+* [**Image Comparisons**](docs/subreddit-configuration/imageComparison.md) via fingerprinting and/or pixel differences
+* [**Repost detection**](docs/subreddit-configuration/in-depth/repost) with support for external services (youtube, etc...)
+* Event notification via Discord
+* [**Web interface**](#web-ui-and-screenshots) for monitoring, administration, and oauth bot authentication
+* [**Placeholders**](docs/subreddit-configuration/actionTemplating.md) (like automoderator) can be configured via a wiki page or raw text and supports [mustache](https://mustache.github.io) templating
+* [**Partial Configurations**](docs/subreddit-configuration/README.md#partial-configurations) -- offload parts of your configuration to shared locations to consolidate logic between multiple subreddits
+* [Guest Access](docs/moderators/README.md#guest-access) enables collaboration and easier setup by allowing temporary access
+* [Toxic content prediction](docs/subreddit-configuration/README.md#moderatehatespeechcom-predictions) using [moderatehatespeech.com](https://moderatehatespeech.com) machine learning model
+
+Feature highlights for **Developers and Hosting (Operators):**
+
+* [Server/client architecture](/docs/operator/serverClientArchitecture.md)
+  * 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
+* Global/subreddit-level [**caching**](/docs/operator/caching.md) of Reddit APIs responses and CM results
+* [Database Persistence](/docs/operator/database.md) using SQLite, MySql, or Postgres
+  * Audit trails for bot activity
+  * Historical statistics
+* [Docker container](/docs/operator/installation.md#docker-recommended) and [docker-compose](/docs/operator/installation.md#docker-compose) support
+* Easy, UI-based [OAuth authentication](/docs/operator/addingBot.md) for adding Bots and moderator dashboard
+* Integration with [InfluxDB](https://www.influxdata.com) for detailed [time-series metrics](/docs/operator/database.md#influx) and a pre-built [Grafana](https://grafana.com) [dashboard](/docs/operator/database.md#grafana)
 
 # Table of Contents
 
 * [How It Works](#how-it-works)
-* [Installation](#installation)
-* [Configuration](#configuration)
-  * [Examples](#examples)
-* [Usage](#usage)
+* [Getting Started](#getting-started)
+* [Configuration And Documentation](#configuration-and-documentation)
+* [Web UI and Screenshots](#web-ui-and-screenshots)
 
 ### How It Works
 
-Context Bot's configuration is made up of an array of **Checks**. Each **Check** consists of :
+Each subreddit using the RCB bot configures its behavior via their own wiki page. 
+
+When a monitored **Activity** (new comment/submission, new modqueue item, etc.) is detected the bot runs through a list of [**Checks**](docs/subreddit-configuration/README.md#checks) to determine what to do with the **Activity** from that Event. Each **Check** consists of :
 
 #### Kind
 
@@ -48,193 +71,98 @@ Is this check for a submission or comment?
 
 #### Rules
 
-A list of **Rule** objects to run against the activity. If **any** Rule object is triggered by the activity then the Check runs its **Actions**
+A list of [**Rules**](docs/subreddit-configuration/README.md#rules) to run against the **Activity**. Triggered Rules can cause the whole Check to trigger and run its **Actions**
 
 #### Actions
 
-A list of **Action** objects that describe what the bot should do with the activity or author of the activity. The bot will run **all** Actions in this list.
+A list of [**Actions**](docs/subreddit-configuration/README.md#actions) that describe what the bot should do with the **Activity** or **Author** of the activity (comment, remove, approve, etc.). The bot will run **all** Actions in this list.
 
 ___
 
 The **Checks** for a subreddit are split up into **Submission Checks** and **Comment Checks** based on their **kind**. Each list of checks is run independently based on when events happen (submission or comment).
 
-When an event occurs all Checks of that type are run in the order they were listed in the configuration. When one check is triggered (an action is performed) the remaining checks will not be run.
+When an Event occurs all Checks of that type are run in the order they were listed in the configuration. When one check is triggered (an Action is performed) the remaining checks will not be run.
 
-## Installation
+___
 
+[Learn more about the RCB lifecycle and core concepts in the docs.](/docs/README.md#how-it-works)
 
-### Locally
+## Getting Started
 
-Clone this repository somewhere and then install from the working directory
+#### Operators
 
-```bash
-git clone https://github.com/FoxxMD/reddit-context-bot.git .
-cd reddit-context-bot
-npm install
-```
+This guide is for users who want to **run their own bot on a ContextMod instance.**
 
-### [Docker](https://hub.docker.com/r/foxxmd/reddit-context-bot)
+See the [Operator's Getting Started Guide](/docs/operator/gettingStarted.md)
 
-```
-foxxmd/reddit-context-bot:latest
-```
+#### Moderators
 
-Adding [**environmental variables**](#usage) to your `docker run` command will pass them through to the app EX:
-```
-docker run -e "CLIENT_ID=myId" ... foxxmd/reddit-context-bot
-```
+This guide is for **reddit moderators** who want to configure an existing CM bot to run on their subreddit.
 
-### [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/reddit-context-bot)
+See the [Moderator's Getting Started Guide](/docs/moderators/gettingStarted.md)
 
+## Configuration and Documentation
 
-## Configuration
+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.
 
-Context Bot's configuration can be written in JSON, [JSON5](https://json5.org/) or YAML. It's [schema](/src/Schema/App.json) conforms to [JSON Schema Draft 7](https://json-schema.org/).
+* For **operators** (running the bot instance) see the [Operator Configuration](/docs/operator/configuration.md) guide
+* For **moderators** consult the [Subreddit Configuration Docs](/docs/subreddit-configuration/README.md)
 
-I suggest using [Atlassian JSON Schema Viewer](https://json-schema.app/start) ([direct link](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Freddit-context-bot%2Fmaster%2Fsrc%2FSchema%2FApp.json)) so you can view all documentation while also interactively writing and validating your config! From there you can drill down into any object, see its requirements, view an example JSON document, and live-edit your configuration on the right-hand side.
+[**Check the full docs for in-depth explanations of all concepts and examples**](/docs)
 
-### Examples
+## Web UI and Screenshots
 
-Read through the [Examples](/examples) section for a thorough introduction to all the **Rules**, in-depth concepts, and sample configuration files.
+### Dashboard
 
-### Action Templating
+CM comes equipped with a dashboard designed for use by both moderators and bot operators.
 
-Actions that can submit text (Report, Comment) will have their `content` values run through a [Mustache Template](https://mustache.github.io/). This means you can insert data generated by Rules into your text before the Action is performed.
+* 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
+  * View statistics on bot usage (# of events, checks run, actions performed) and cache usage
+  * View various parts of your subreddit's configuration and manually update configuration
+  * View **real-time logs** of what the bot is doing on your subreddit
+  * **Run bot on any permalink**
 
-See here for a [cheatsheet](https://gist.github.com/FoxxMD/d365707cf99fdb526a504b8b833a5b78) and [here](https://www.tsmean.com/articles/mustache/the-ultimate-mustache-tutorial/) for a more thorough tutorial.
+![Subreddit View](docs/images/subredditStatus.jpg)
 
-All Actions with `content` have access to this data:
+### Bot Setup/Authentication
 
-```json5
-{
-    item: {
-        kind: 'string', // the type of item (comment/submission)
-        author: 'string', // name of the item author (reddit user)
-        permalink: 'string', // a url to the item
-        url: 'string', // if the item is a Submission then its URL (external for link type submission, reddit link for self-posts)
-        title: 'string', // if the item is a Submission, then the title of the Submission,
-        botLink: 'string' // a link to the bot's FAQ
-    },
-    rules: {
-        // contains all rules that were run and are accessible using the name, lowercased, with all spaces/dashes/underscores removed
-    }
-}
+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/operator/addingBot.md#cm-oauth-helper-recommended)
 
-```
+Operator view/invite link generation:
 
-The properties of `rules` are accessible using the name, lower-cased, with all spaces/dashes/underscores. If no name is given `kind` is used as `name` Example:
+![Oauth View](docs/images/oauth.jpg)
 
-```
-"rules": [
-  {
-    "name": "My Custom-Recent Activity Rule", // mycustomrecentactivityrule
-    "kind": "recentActivity"
-  },
-  {
-    // name = repeatsubmission
-    "kind": "repeatActivity",
-  }
-]
-```
+Moderator view/invite and authorization:
 
-**To see what data is available for individual Rules [consult the schema](#configuration) for each Rule.**
+![Invite View](docs/images/oauth-invite.jpg)
 
-#### Quick Templating Tutorial
+A similar helper and invitation experience is available for adding **subreddits to an existing bot.**
 
-<details>
+![Subreddit Invite View](docs/images/subredditInvite.jpg)
 
-As a quick example for how you will most likely be using templating -- wrapping a variable in curly brackets, `{{variable}}`, will cause the variable value to be rendered instead of the brackets:
-```
-myVariable = 50;
-myOtherVariable = "a text fragment"
-template = "This is my template, the variable is {{myVariable}}, my other variable is {{myOtherVariable}}, and that's it!";
+### Configuration Editor
 
-console.log(Mustache.render(template, {myVariable});
-// will render...
-"This is my template, the variable is 50, my other variable is a text fragment, and that's it!";
-```
+A built-in editor using [monaco-editor](https://microsoft.github.io/monaco-editor/) makes editing configurations easy:
 
-**Note: When accessing an object or its properties you must use dot notation**
-```
-const item = {
-aProperty: 'something',
-anotherObject: {
-bProperty: 'something else'
-}
-}
-const content = "My content will render the property {{item.aProperty}} like this, and another nested property {{item.anotherObject.bProperty}} like this."
-```
-</details>
+* 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
 
-## Usage
+![Configuration View](docs/images/editor.jpg)
 
-```
-Usage: index [options] [command]
+### [Grafana Dashboard](/docs/operator/database.md#grafana)
 
-Options:
-  -c, --clientId <id>                          Client ID for your Reddit application (default: process.env.CLIENT_ID)
-  -e, --clientSecret <secret>                  Client Secret for your Reddit application (default: process.env.CLIENT_SECRET)
-  -a, --accessToken <token>                    Access token retrieved from authenticating an account with your Reddit Application (default: process.env.ACCESS_TOKEN)
-  -r, --refreshToken <token>                   Refresh token retrieved from authenticating an account with your Reddit Application (default: process.env.REFRESH_TOKEN)
-  -s, --subreddits <list...>                   List of subreddits to run on. Bot will run on all subs it has access to if not defined (default: process.env.SUBREDDITS (comma-seperated))
-  -d, --logDir <dir>                           Absolute path to directory to store rotated logs in (default: process.env.LOG_DIR || process.cwd()/logs)
-  -l, --logLevel <level>                       Log level (default: process.env.LOG_LEVEL || info)
-  -w, --wikiConfig <path>                      Relative url to contextbot wiki page EX https://reddit.com/r/subreddit/wiki/<path> (default: process.env.WIKI_CONFIG || 'botconfig/contextbot')
-  --snooDebug                                  Set Snoowrap to debug (default: process.env.SNOO_DEBUG || false)
-  --authorTTL <ms>                             Set the TTL (ms) for the Author Activities shared cache (default: process.env.AUTHOR_TTL || 10000)
-  --heartbeat <s>                              Interval, in seconds, between heartbeat logs. Set to 0 to disable (default: process.env.HEARTBEAT || 300)
-  --apiLimitWarning <remaining>                When API limit remaining (600/10min) is lower than this value log statements for limit will be raised to WARN level (default: process.env.API_REMAINING || 250)
-  --dryRun                                     Set dryRun=true for all checks/actions on all subreddits (overrides any existing) (default: process.env.DRYRUN)
-  --disableCache                               Disable caching for all subreddits (default: process.env.DISABLE_CACHE || false)
-  -h, --help                                   display help for command
+* Overall stats (active bots/subreddits, api calls, per second/hour/minute activity ingest)
+* Over time graphs for events, per subreddit, and for individual rules/check/actions
 
-Commands:
-  run                                          Runs bot normally
-  check [options] <activityIdentifier> [type]  Run check(s) on a specific activity
-  unmoderated [options] <subreddits...>        Run checks on all unmoderated activity in the modqueue
-  help [command]                               display help for command
-
-```
-
-### Logging
-
-### Reddit App??
-
-To use this bot you must do two things:
-* Create a reddit application
-* Authenticate that application to act as a user (login to the application with an account)
-
-#### Create Application
-
-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.
-* Choose **script**
-* For redirect uri use https://not-an-aardvark.github.io/reddit-oauth-helper/
-* Write down your **Client ID** and **Client Secret** somewhere
-
-#### Authenticate an Account
-
-Visit https://not-an-aardvark.github.io/reddit-oauth-helper/
-* Input your **Client ID** and **Client Secret** in the text boxes with those names.
-* Choose scopes. **It is very important you check everything on this list or Context Bot will not work correctly**
-    * edit
-    * flair
-    * history
-    * identity
-    * modcontributors
-    * modflair
-    * modposts
-    * modself
-    * mysubreddits
-    * read
-    * report
-    * submit
-    * wikiread
-    * wikiedit (if you are using Toolbox User Notes)
-* Click **Generate tokens**, you will get a popup asking you to approve access (or login) -- **the account you approve access with is the account that Bot will control.**
-* After approving an **Access Token** and **Refresh Token** will be shown at the bottom of the page. Write these down. 
-  
-You should now have all the information you need to start the bot.
+![Grafana Dashboard](/docs/images/grafana.jpg)
 
 ## License
 

_config.yml

@@ -0,0 +1,45 @@
+title: ContextMod
+description: Documentation for ContextMod
+theme: just-the-docs
+
+source: docs
+
+url: https://contextmod.dev
+
+color_scheme: dark
+
+mermaid:
+  version: "9.1.3"
+
+aux_links:
+  Github: https://github.com/foxxmd/context-mod
+
+plugins:
+  - jekyll-readme-index
+  - jekyll-default-layout
+  - jekyll-titles-from-headings
+  - jekyll-optional-front-matter
+  - jekyll-relative-links
+
+titles_from_headings:
+  enabled:     true
+  strip_title: false
+  collections: false
+
+readme_index:
+  enabled:          true
+  remove_originals: true
+  with_frontmatter: true
+
+optional_front_matter:
+  remove_originals: true
+
+defaults:
+  - scope:
+      path: ""
+    values:
+      has_toc: false
+  - scope:
+      path: "images"
+    values:
+      image: true

act.env.example

@@ -0,0 +1,3 @@
+GITHUB_TOKEN=
+DOCKERHUB_USERNAME=
+DOCKER_PASSWORD=

app.json

@@ -1,7 +1,7 @@
 {
   "name": "Reddit Context Bot",
   "description": "An event-based, reddit moderation bot built on top of snoowrap and written in typescript",
-  "repository": "https://github.com/FoxxMD/reddit-context-bot",
+  "repository": "https://github.com/FoxxMD/context-mod",
   "stack": "container",
   "env": {
     "CLIENT_ID": {
@@ -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"

docker-compose.yml

@@ -0,0 +1,62 @@
+version: '3.7'
+
+services:
+  app:
+    image: foxxmd/context-mod:latest
+    # use the settings below, instead of 'image', if running context-mod from the repository (developing local changes)
+#    build:
+#      context: .
+    volumes:
+      # Location of config file to use with CM
+      # The path BEFORE the colon (:) is the path on the host machine
+      # which defaults to a folder named 'data' in the same directory this file is run in.
+      - './data:/config'
+      # For a new installation you should use the config from the repository included for use with docker-compose
+      # https://github.com/FoxxMD/context-mod/blob/master/docker/config/docker-compose/config.yaml
+      # Copy config.yaml to /(this directory)/data/config.yaml and then modify to match any changed settings below (see comments on config.yaml)
+    ports:
+      - "${CM_WEB-8085}:8085"
+    environment:
+      IS_DOCKER: true
+      # If using a linux host, uncomment these and set them accordingly https://github.com/FoxxMD/context-mod/blob/master/docs/operator/installation.md#linux-host
+#      PUID: 1000
+#      PGID: 1000
+
+  cache:
+    image: 'redis:7-alpine'
+    volumes:
+      # on linux will need to make sure this directory has correct permissions for container to access
+      - './data/cache:/data'
+
+  database:
+    image: 'mariadb:10.9.3'
+    environment:
+      MYSQL_ROOT_PASSWORD: CHANGE_THIS
+      MYSQL_USER: cmuser
+      # this should match the password set in config.yaml
+      MYSQL_PASSWORD: CHANGE_THIS
+      MYSQL_DATABASE: ContextMod
+    volumes:
+      - './data/db:/var/lib/mysql'
+
+  influx:
+    image: 'influxdb:latest'
+    volumes:
+      - './data/influx:/var/lib/influxdb2'
+    ports:
+      - "${INFLUX_WEB:-8086}:8086"
+    profiles:
+      - full
+
+  grafana:
+    image: 'grafana/grafana'
+    volumes:
+      - './data/grafana:/var/lib/grafana'
+    ports:
+      - "${GRAFANA_WEB:-3000}:3000"
+    environment:
+      GF_SECURITY_ADMIN_PASSWORD: CHANGE_THIS
+    depends_on:
+      - influx
+    profiles:
+      - full

docker/config/docker-compose/config.yaml

@@ -0,0 +1,43 @@
+operator:
+  name: CHANGE_THIS #YOUR REDDIT USERNAME HERE
+logging:
+  # default level for all transports
+  level: debug
+  file:
+    # override default level
+    level: warn
+    # true -> log folder at projectDir/log
+    dirname: true
+caching:
+  provider:
+    store: redis
+    host: cache
+    port: 6379
+    prefix: prod
+databaseConfig:
+  migrations:
+    continueOnAutomatedBackup: true
+    #force: true # uncomment this to make cm run new migrations without confirmation
+  #logging: ['query', 'error', 'warn', 'log'] # uncomment this to get typeorm to log EVERYTHING
+  connection:
+    type: 'mariadb'
+    host: 'database'
+    username: 'cmuser'
+    # This should match the password set in docker-compose.yaml
+    password: 'CHANGE_THIS'
+    database: 'ContextMod'
+web:
+  credentials:
+    redirectUri: 'http://localhost:8085/callback'
+  session:
+    storage: cache
+  port: 8085
+#
+# Influx/Grafana requires additional configuration. See https://github.com/FoxxMD/context-mod/blob/master/docs/operator/database.md#influx
+#
+#influxConfig:
+#  credentials:
+#    url: 'http://influx:8086'
+#    token: 'YourInfluxToken'
+#    org: YourInfluxOrg
+#    bucket: contextmod

docker/root/etc/cont-init.d/10-config

@@ -0,0 +1,14 @@
+#!/usr/bin/with-contenv bash
+
+# used https://github.com/linuxserver/docker-plex as a template
+
+# make data folder if not /config
+if [ ! -d "${DATA_DIR}" ]; then \
+mkdir -p "${DATA_DIR}"
+chown -R abc:abc /config
+fi
+
+# permissions
+chown abc:abc \
+  /config \
+  /config/*

docker/root/etc/services.d/node/run

@@ -0,0 +1,9 @@
+#!/usr/bin/with-contenv bash
+
+# used https://github.com/linuxserver/docker-plex as a template
+
+# NODE_ARGS can be passed by ENV in docker command like "docker run foxxmd/context-mod -e NODE_ARGS=--optimize_for_size"
+
+exec \
+	s6-setuidgid abc \
+	/usr/local/bin/node $NODE_ARGS /app/src/index.js run

docs/README.md

@@ -0,0 +1,167 @@
+---
+title: Overview
+permalink: /overview.html
+nav_order: 2
+---
+
+# Table of Contents
+
+* [Getting Started](#getting-started)
+* [How It Works](#how-it-works)
+* [Concepts](#concepts)
+  * [Event](#event)
+  * [Activity](#activity)
+  * [Run](#runs)
+  * [Check](#checks)
+  * [Rule](#rule)
+    * [Available Rules](#available-rules)
+  * [Rule Set](#rule-set)
+  * [Action](#action)
+    * [Available Actions](#available-actions)
+  * [Filters](#filters)
+* [Configuration and Usage](#configuration-and-usage)
+* FAQ
+
+## Getting Started
+
+Review **at least** the **How It Works** and **Concepts** below, then:
+
+* For **Operators** (running a bot instance) refer to [**Operator Getting Started**](operator/gettingStarted.md)  guide
+* For **Moderators** (configuring an existing bot for your subreddit) refer to the [**Moderator Getting Started**](moderators/gettingStarted.md) guide
+
+## How It Works
+
+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 markdown="block">
+<summary>Diagram</summary>
+
+![Flow Diagram](images/diagram-highlevel.jpg)
+
+</details>
+
+CM's lifecycle looks like this:
+
+#### 1) A new Activity in your subreddit is received by CM
+
+The Activities CM watches for are configured by you. These can be new modqueue/unmoderated items, submissions, or comments.
+
+#### 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**](#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**
+
+#### 4) Each Check is processed, *in order*, until a Check is **triggered**
+
+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.
+
+#### 5) All Actions from the triggered Check are executed
+
+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.
+
+### Event
+
+An **Event** refers to the [Activity](#activity) (Comment or Submission) CM receives to process as well as the results of processing that Activity.
+
+### Activity
+
+An Activity is a Comment or Submission from Reddit.
+
+### 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).
+
+[Full Documentation for Runs](subreddit-configuration/README.md#runs)
+
+### Checks
+
+A **Check** is the main logical unit of behavior for the bot. It is equivalent to "if X then Y". A Check is composed of:
+
+* One or more **Rules** that are tested against an **Activity**
+* One of more **Actions** that are performed when the **Rules** are satisfied
+
+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.
+
+[Full Documentation for Checks](subreddit-configuration/README.md#checks)
+  
+### Rule
+
+A **Rule** is some set of **criteria** (conditions) that are tested against an Activity (comment/submission), a User, or a User's history. A Rule is considered **triggered** when the **criteria** for that rule are found to be **true** for whatever is being tested against.
+
+CM has different **Rules** that can test against different types of behavior and aspects of a User, their history, and the Activity (submission/common) being checked.
+
+[Full Documentation for Rules](subreddit-configuration/README.md#rules)
+
+#### Available Rules
+
+All available rules can be found in the [components documentation](subreddit-configuration/README.md#rules)
+
+### Rule Set
+
+A **Rule Set** is a "grouped" set of `Rules` with a **trigger condition** specified. 
+
+Rule Sets can be used interchangeably with other **Rules** and **Rule Sets** in the `rules` list of a **Check**. 
+
+They allow you to create more complex trigger behavior by combining multiple rules into one "parent rule".
+
+[Rule Sets Documentation](subreddit-configuration/README.md#rule-sets)
+
+### Action
+
+An **Action** is some action the bot can take against the checked Activity (comment/submission) or Author of the Activity. CM has Actions for most things a normal reddit user or moderator can do.
+
+#### Available Actions
+
+[Available Actions Documentation](subreddit-configuration/README.md#list-of-actions)
+
+### Filters
+
+**Runs, Checks, Rules, and Actions** all have two additional (optional) criteria "pre-tests". These tests are different from rules/checks in these ways:
+
+* Filters test against the **current state** of the Activity, the Author of the Activity, or the Subreddit of the Activity -- rather than looking at history/context/etc...
+* Filter test results only determine if the Run, Check, Rule, or Action **should run** -- rather than triggering it
+  * When the filter test **passes** the thing being tested continues to process as usual
+  * When the filter test **fails** the thing being tested **fails**.
+
+[Full Documentation for Filters](subreddit-configuration/README.md#filters)
+
+## Configuration And Usage
+
+* For **Operator/Bot maintainers** see **[Operation Guide](operator/README.md)**
+* For **Moderators** 
+  * Start with the [Subreddit/Moderator docs](moderators/README.md) or [Moderator Getting Started guide](moderators/gettingStarted.md)
+  * Refer to the [Subreddit Components Documentation](subreddit-configuration) or the [subreddit-ready examples](subreddit-configuration/cookbook)
+  * as well as the [schema](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) which has
+    * fully annotated configuration data/structure
+    * generated examples in json/yaml
+
+## FAQ
+
+TODO

docs/development.md

@@ -0,0 +1,416 @@
+---
+nav_order: 7
+---
+
+# Development
+
+# Serving Docs Locally
+
+Requirements:
+
+* [Jeykll](https://jekyllrb.com/) installed
+  * Ruby 2.5.0 or higher and [RubyGems](https://rubygems.org/pages/download) (usually bundled)
+* [Bundler](https://bundler.io/) installed
+
+## Install Doc Dependencies
+
+```bash
+npm run docs-install
+```
+
+## Serve Docs
+
+```bash
+npm run docs-start
+```
+
+# Developing/Testing Github Actions
+
+Use [act](https://github.com/nektos/act) to run Github actions locally.
+
+An example secrets file can be found in the project working directory at [act.env.example](../act.env.example)
+
+Modify [push-hook-sample.json](../.github/push-hook-sample.json) to point to the local branch you want to run a `push` event trigger on, then run this command from the project working directory:
+
+```bash
+act -e .github/push-hook-sample.json --secret-file act.env
+```
+
+# Mocking Reddit API
+
+Using [MockServer](https://www.mock-server.com/)
+
+## Installation
+
+https://www.mock-server.com/mock_server/running_mock_server.html
+
+Easiest way is to install the [docker container](https://www.mock-server.com/mock_server/running_mock_server.html#pull_docker_image) ([from here](https://hub.docker.com/r/mockserver/mockserver))
+
+Map port `1080:1080` -- acts as both the proxy port and the UI endpoint with the below URL:
+
+```
+http(s)://localhost:1080/mockserver/dashboard
+```
+
+In your [operator configuration](operator/configuration.md) define a proxy for snoowrap at the top-level:
+
+```yaml
+snoowrap:
+  proxy: 'http://localhost:8010'
+  #debug: true # optionally set debug to true to make snoowrap requests output to log
+```
+
+## Usage
+
+### Forwarding Requests (Monitoring Behavior)
+
+This is what will make MockServer act as an actual **proxy server**. In this state CM will operate normally. In the MockServer UI you will be able to monitor all requests/responses made.
+
+```HTTP
+PUT /mockserver/expectation HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 155
+
+```
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/expectation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "httpRequest": {},
+    "priority": 0,
+    "httpForward": {
+        "host": "oauth.reddit.com",
+        "port": 443,
+        "scheme": "HTTPS"
+    }
+}'
+```
+
+</details>
+
+### Mocking Network Issues
+
+MockServer is a bit confusing and regex'ing for specific paths don't work well (for me??)
+
+The lifecycle of a mock call I do:
+
+* Make sure [forwarding](#forwarding-requests-monitoring-behavior) is set, to begin with
+* Breakpoint before the code you want to test with mocking
+* [Mock the network issue](#create-network-issue-behavior)
+* Once the mock behavior should be "done" then
+  * [Clear all exceptions](#clearing-behavior)
+  * Set [forwarding behavior](#forwarding-requests-monitoring-behavior) again
+
+### Create Network Issue Behavior
+
+#### All Responses return 403
+
+<details markdown="block">
+<summary>HTTP</summary>
+
+```HTTP
+PUT /mockserver/expectation HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 1757
+
+```
+
+</details>
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/expectation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "id": "error",
+    "httpRequest": {
+        "path": ".*"
+    },
+    "priority": 1,
+    "httpResponse": {
+        "statusCode": 403,
+        "reasonPhrase": "Forbidden",
+        "headers": {
+            "Connection": [
+                "keep-alive"
+            ],
+            "Content-Type": [
+                "application/json; charset=UTF-8"
+            ],
+            "x-ua-compatible": [
+                "IE=edge"
+            ],
+            "x-frame-options": [
+                "SAMEORIGIN"
+            ],
+            "x-content-type-options": [
+                "nosniff"
+            ],
+            "x-xss-protection": [
+                "1; mode=block"
+            ],
+            "expires": [
+                "-1"
+            ],
+            "cache-control": [
+                "private, s-maxage=0, max-age=0, must-revalidate, no-store, max-age=0, must-revalidate"
+            ],
+            "x-ratelimit-remaining": [
+                "575.0"
+            ],
+            "x-ratelimit-used": [
+                "25"
+            ],
+            "x-ratelimit-reset": [
+                "143"
+            ],
+            "X-Moose": [
+                "majestic"
+            ],
+            "Accept-Ranges": [
+                "bytes"
+            ],
+            "Date": [
+                "Wed, 05 Jan 2022 14:37:37 GMT"
+            ],
+            "Via": [
+                "1.1 varnish"
+            ],
+            "Vary": [
+                "accept-encoding"
+            ],
+            "Strict-Transport-Security": [
+                "max-age=15552000; includeSubDomains; preload"
+            ],
+            "Server": [
+                "snooserv"
+            ],
+            "X-Clacks-Overhead": [
+                "GNU Terry Pratchett"
+            ]
+        }
+    }
+}'
+```
+
+</details>
+
+#### All Responses Timeout
+
+<details markdown="block">
+<summary>HTTP</summary>
+
+```HTTP
+PUT /mockserver/expectation HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 251
+
+```
+
+</details>
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/expectation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "id": "error",
+    "httpRequest": {
+        "path": ".*"
+    },
+    "priority": 1,
+    "httpResponse": {
+        "body": "should never receive this",
+        "delay": {
+            "timeUnit": "SECONDS",
+            "value": 60
+        }
+    }
+}'
+```
+
+</details>
+
+#### All Responses Drop After Delay (Connection Closed by Server)
+
+<details markdown="block">
+<summary>HTTP</summary>
+
+```HTTP
+PUT /mockserver/expectation HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 234
+
+```
+
+</details>
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/expectation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "id": "error",
+    "httpRequest": {
+        "path": ".*"
+    },
+    "priority": 1,
+    "httpError": {
+        "dropConnection": true,
+        "delay": {
+            "timeUnit": "SECONDS",
+            "value": 2
+        }
+    }
+}'
+```
+
+</details>
+
+### Clearing Behavior
+
+
+```HTTP
+PUT /mockserver/clear?type=EXPECTATIONS HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 26
+
+```
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/clear?type=EXPECTATIONS' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "path": "/.*"
+}'
+```
+
+</details>
+        }
+    }
+}
+```
+
+</details>
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/expectation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "id": "error",
+    "httpRequest": {
+        "path": ".*"
+    },
+    "priority": 1,
+    "httpResponse": {
+        "body": "should never receive this",
+        "delay": {
+            "timeUnit": "SECONDS",
+            "value": 60
+        }
+    }
+}'
+```
+
+</details>
+
+#### All Responses Drop After Delay (Connection Closed by Server)
+
+<details markdown="block">
+<summary>HTTP</summary>
+
+```HTTP
+PUT /mockserver/expectation HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 234
+
+{
+    "id": "error",
+    "httpRequest": {
+        "path": ".*"
+    },
+    "priority": 1,
+    "httpError": {
+        "dropConnection": true,
+        "delay": {
+            "timeUnit": "SECONDS",
+            "value": 2
+        }
+    }
+}
+```
+
+</details>
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/expectation' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "id": "error",
+    "httpRequest": {
+        "path": ".*"
+    },
+    "priority": 1,
+    "httpError": {
+        "dropConnection": true,
+        "delay": {
+            "timeUnit": "SECONDS",
+            "value": 2
+        }
+    }
+}'
+```
+
+</details>
+
+### Clearing Behavior
+
+
+```HTTP
+PUT /mockserver/clear?type=EXPECTATIONS HTTP/1.1
+Host: localhost:8010
+Content-Type: application/json
+Content-Length: 26
+
+{
+    "path": "/user/.*"
+}
+```
+
+<details markdown="block">
+<summary>CURL</summary>
+
+```bash
+curl --location --request PUT 'http://localhost:8010/mockserver/clear?type=EXPECTATIONS' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+    "path": "/.*"
+}'
+```
+
+</details>

docs/index.md

@@ -0,0 +1,169 @@
+---
+title: Home
+nav_order: 1
+---
+# 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="/logo.png" align="right"
+alt="ContextMod logo" width="180" height="176">
+
+[**Context Mod**](https://contextmod.dev/) (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/).
+
+It is designed to help fill in the gaps for [automoderator](https://www.reddit.com/wiki/automoderator/full-documentation) in regard to more complex behavior with a focus on **user-history based moderation.**
+
+An example of the above that Context Bot can do:
+
+> * On a new submission, check if the user has also posted the same link in **N** number of other subreddits within a timeframe/# of posts
+> * On a new submission or comment, check if the user has had any activity (sub/comment) in **N** set of subreddits within a timeframe/# of posts
+>
+>In either instance Context Bot can then perform any action a moderator can (comment, report, remove, lock, etc...) against that user, comment, or submission.
+
+Feature Highlights for **Moderators:**
+
+* Complete bot **autonomy**. YAML config is [stored in your subreddit's wiki](moderators/gettingStarted.md#setup-wiki-page) (like automoderator)
+* Simple rule-action behavior can be combined to create **complex behavior detection**
+* Support Activity filtering based on:
+  * [Author criteria](subreddit-configuration/in-depth/filters/README.md#author-filter) (name, css flair/text, age, karma, moderator status, [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/usernotes), and more!)
+  * [Activity state](subreddit-configuration/in-depth/filters/README.md#item-filter) (removed, locked, distinguished, etc...)
+  * State of Subreddit Activity is in [Subreddit](subreddit-configuration/in-depth/filters/README.md#subreddit-filter) (nsfw, name, profile, etc...)
+* Rules and Actions support [named references](subreddit-configuration/README.md#named-rules) -- **write once, reference anywhere**
+* Powerful [logic control](subreddit-configuration/advancedConcepts/flowControl.md) (if, then, goto)
+* [Delay/re-process activities](subreddit-configuration/README.md#dispatch) using arbitrary rules
+* [**Image Comparisons**](subreddit-configuration/imageComparison.md) via fingerprinting and/or pixel differences
+* [**Repost detection**](subreddit-configuration/in-depth/repost) with support for external services (youtube, etc...)
+* Event notification via Discord
+* [**Web interface**](#web-ui-and-screenshots) for monitoring, administration, and oauth bot authentication
+* [**Placeholders**](subreddit-configuration/actionTemplating.md) (like automoderator) can be configured via a wiki page or raw text and supports [mustache](https://mustache.github.io) templating
+* [**Partial Configurations**](subreddit-configuration/README.md#partial-configurations) -- offload parts of your configuration to shared locations to consolidate logic between multiple subreddits
+* [Guest Access](moderators/README.md#guest-access) enables collaboration and easier setup by allowing temporary access
+* [Toxic content prediction](subreddit-configuration/README.md#moderatehatespeechcom-predictions) using [moderatehatespeech.com](https://moderatehatespeech.com) machine learning model
+
+Feature highlights for **Developers and Hosting (Operators):**
+
+* [Server/client architecture](operator/serverClientArchitecture.md)
+  * 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
+* Global/subreddit-level [**caching**](operator/caching.md) of Reddit APIs responses and CM results
+* [Database Persistence](operator/database.md) using SQLite, MySql, or Postgres
+  * Audit trails for bot activity
+  * Historical statistics
+* [Docker container](operator/installation.md#docker-recommended) and [docker-compose](operator/installation.md#docker-compose) support
+* Easy, UI-based [OAuth authentication](operator/addingBot.md) for adding Bots and moderator dashboard
+* Integration with [InfluxDB](https://www.influxdata.com) for detailed [time-series metrics](operator/database.md#influx) and a pre-built [Grafana](https://grafana.com) [dashboard](operator/database.md#grafana)
+
+# Table of Contents
+
+* [How It Works](#how-it-works)
+* [Getting Started](#getting-started)
+* [Configuration And Documentation](#configuration-and-documentation)
+* [Web UI and Screenshots](#web-ui-and-screenshots)
+
+### How It Works
+
+Each subreddit using the RCB bot configures its behavior via their own wiki page. 
+
+When a monitored **Activity** (new comment/submission, new modqueue item, etc.) is detected the bot runs through a list of [**Checks**](subreddit-configuration/README.md#checks) to determine what to do with the **Activity** from that Event. Each **Check** consists of :
+
+#### Kind
+
+Is this check for a submission or comment?
+
+#### Rules
+
+A list of [**Rules**](subreddit-configuration/README.md#rules) to run against the **Activity**. Triggered Rules can cause the whole Check to trigger and run its **Actions**
+
+#### Actions
+
+A list of [**Actions**](subreddit-configuration/README.md#actions) that describe what the bot should do with the **Activity** or **Author** of the activity (comment, remove, approve, etc.). The bot will run **all** Actions in this list.
+
+___
+
+The **Checks** for a subreddit are split up into **Submission Checks** and **Comment Checks** based on their **kind**. Each list of checks is run independently based on when events happen (submission or comment).
+
+When an Event occurs all Checks of that type are run in the order they were listed in the configuration. When one check is triggered (an Action is performed) the remaining checks will not be run.
+
+___
+
+[Learn more about the RCB lifecycle and core concepts in the docs.](/README.md#how-it-works)
+
+## Getting Started
+
+#### Operators
+
+This guide is for users who want to **run their own bot on a ContextMod instance.**
+
+See the [Operator's Getting Started Guide](operator/gettingStarted.md)
+
+#### Moderators
+
+This guide is for **reddit moderators** who want to configure an existing CM bot to run on their subreddit.
+
+See the [Moderator's Getting Started Guide](moderators/gettingStarted.md)
+
+## Configuration and Documentation
+
+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](operator/configuration.md) guide
+* For **moderators** consult the [Subreddit Configuration Docs](subreddit-configuration/README.md)
+
+[**Check the full docs for in-depth explanations of all concepts and examples**](/docs)
+
+## Web UI and Screenshots
+
+### 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
+  * View statistics on bot usage (# of events, checks run, actions performed) and cache usage
+  * View various parts of your subreddit's configuration and manually update configuration
+  * View **real-time logs** of what the bot is doing on your subreddit
+  * **Run bot on any permalink**
+
+![Subreddit View](images/subredditStatus.jpg)
+
+### Bot Setup/Authentication
+
+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.](operator/addingBot.md#cm-oauth-helper-recommended)
+
+Operator view/invite link generation:
+
+![Oauth View](images/oauth.jpg)
+
+Moderator view/invite and authorization:
+
+![Invite View](images/oauth-invite.jpg)
+
+A similar helper and invitation experience is available for adding **subreddits to an existing bot.**
+
+![Subreddit Invite View](images/subredditInvite.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](images/editor.jpg)
+
+### [Grafana Dashboard](operator/database.md#grafana)
+
+* Overall stats (active bots/subreddits, api calls, per second/hour/minute activity ingest)
+* Over time graphs for events, per subreddit, and for individual rules/check/actions
+
+![Grafana Dashboard](images/grafana.jpg)
+
+## License
+
+[MIT](/LICENSE)

docs/moderators/README.md

@@ -0,0 +1,101 @@
+---
+has_children: true
+title: Moderators
+nav_order: 3
+---
+
+This section is for **reddit moderators**. It covers how to use a CM bot for your subreddit.
+
+If you are trying to run a ContextMod instance (the actual software) please refer to the [operator section](../operator/README.md).
+
+# Table of Contents
+
+* [Overview](#overview)
+  * [Your Relationship to CM](#your-relationship-to-cm)
+    * [Operator](#operator)
+    * [Your Bot](#your-bot)
+* [Getting Started](#getting-started)
+* [Accessing The Bot](#accessing-the-bot)
+  * [Editing The Bot](#editing-the-bot)
+* [Configuration](#configuration)
+* [Guest Access](#guest-access)
+
+# Overview
+
+The Context Mod **software** can manage multiple **bots** (reddit accounts used as bots, like `/u/MyCMBot`). Each bot can manage (run) multiple **subreddits** which is determined by the subreddits the account is a moderator of.
+
+You, the moderator of a subreddit a CM bot runs in, can access/manage the Bot using the CM software's [web interface](../images/subredditStatus.jpg) and control its behavior using the [web editor.](../images/editor.jpg)
+
+## Your Relationship to CM
+
+It is important to understand the relationship between you (the moderator), the bot, and the operator (the person running the CM software).
+
+The easiest way to think about this is in relation to how you use Automoderator and interact with Reddit as a moderator. As an analogy:
+
+### Operator
+
+The operator is the person running the actual server/machine the Context Mod software is on. 
+
+They are best thought of as **Reddit:**
+
+* Mostly hands-off when it comes to the bot and interacting with your subreddit
+* You must interact with Reddit first before you can use automoderator (login, create a subreddit, etc...)
+
+Unlike reddit, though, there is a greater level of trust required between you and the Operator because what you make the Bot do ultimately affects the Operator since they are the ones actually running your Bot and making API calls to reddit.
+
+### Your Bot
+
+Your bot is like an **invite-only version of Automoderator**:
+
+* Unlike automoderator, you **must** interact with the Operator in order to get the bot working. It is not public for anyone to use.
+* Like automoderator, you **must** create a [configuration](../subreddit-configuration/README.md) for it do anything.
+  * The bot does not come pre-configured for you. It is a blank slate and requires user input to be useful.
+* Also like automoderator, you are **entirely in control of the bot.**
+  * You can start, stop, and edit its behavior at any time without needing to communicate with the Operator.
+  * CM provides you _tools_, different ways the Bot can detect patterns in your subreddit/users as well as actions it can, and you can decide to use them however you want.
+* Your bot is **only accessible to moderators of your subreddit.**
+
+# Getting Started
+
+The [Getting Started](gettingStarted.md) guide lays out the steps needed to go from nothing to a working Bot. If you are a moderator new to Context Mod this is where you want to begin.
+
+# Accessing The Bot
+
+All bot management and editing is done through the [web interface.](/../images/subredditStatus.jpg) The URL used for accessing this interface is given to you by the **Operator** once they have agreed to host your bot/subreddit.
+
+NOTE: This interface is **only access to moderators of your subreddit** and [guests.](#guest-access) You must login to the web interface **with your moderator account** in order to access it.
+
+A **guided tour** that helps show how to manage the bot at a high-level is available on the web interface by clicking the **Help** button in the top-right of the page.
+
+## Editing The Bot
+
+Find the [editor in the web interface](../webInterface.md#editingupdating-your-config) to access the built-in editor for the bot.
+
+[The editor](../images/editor.jpg) should be your all-in-one location for viewing and editing your bot's behavior. **It is equivalent to Automoderator's editor page.**
+
+The editor features:
+
+* syntax validation and highlighting
+* configuration auto-complete and documentation (hover over properties)
+* built-in validation using Microsoft Word "squiggly lines" indicators and an error list at the bottom of the window
+* built-in saving (at the top of the window)
+
+# Configuration
+
+Use the [Configuration Reference](../subreddit-configuration/README.md) to learn about all the different components available for building a CM configuration.
+
+Additionally, refer to [How It Works](../README.md#how-it-works) and [Core Concepts](../README.md#concepts) to learn the basic of CM configuration.
+
+After you have the basics under your belt you could use the [subreddit configurations cookbook](../subreddit-configuration/cookbook) to familiarize yourself with a complete configuration and ways to use CM.
+
+# Guest Access
+
+CM supports **Guest Access**. Reddit users who are given Guest Access to your bot are allowed to access the web interface even though they are not moderators.
+
+Additionally, they can edit the subreddit's config using the bot. If a Guest edits your config their username will be mentioned in the wiki page edit reason.
+
+Guests can do everything a regular mod can except view/add/remove Guest. They can be removed at any time or set with an expiration date that their access is removed on.
+
+**Guests are helpful if you are new to CM and know reddit users that can help you get started.**
+
+[Add guests from the Subreddit tab in the main interface.](../images/guests.jpg)

docs/moderators/gettingStarted.md

@@ -0,0 +1,184 @@
+---
+parent: Moderators
+nav_order: 1
+---
+
+# Getting Started
+
+This getting started guide is for **reddit moderators** -- that is, someone who wants **an existing ContextMod bot to run on their subreddit.** If you are trying to run a ContextMod
+instance (software) please refer to the [operator getting started](../operator/gettingStarted.md) guide.
+
+# Table of Contents
+
+* [Prior Knowledge](#prior-knowledge)
+* [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)
+
+# Prior Knowledge
+
+Before continuing with this guide you should first make sure you understand how a ContextMod works. Please review this documentation:
+
+* [How It Works](../README.md#how-it-works)
+* [Core Concepts](../README.md#concepts)
+
+# Choose A Bot
+
+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)
+
+## 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**)](../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 markdown="block">
+
+* 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**
+
+</details>
+
+## Procure a configuration
+
+Now you need to make the actual configuration that will be used to configure the bot's behavior on your subreddit. This may have already been done for you by your operator or you may be copying a fellow moderator's configuration.
+
+If you already have a configuration you may skip the below step and go directly to [saving your configuration](#saving-your-configuration)
+
+### Using an Example Config
+
+Visit the [Examples](https://github.com/FoxxMD/context-mod/tree/master../examples) folder to find various examples of individual rules or see the [subreddit cookbook examples.](../subreddit-configuration/cookbook)
+
+After you have found a configuration to use as a starting point:
+
+* Copy the URL for the configuration file EX `https://github.com/FoxxMD/context-mod/blob/master../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
+
+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.
+
+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
+
+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
+
+### 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**](../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 markdown="block">
+
+* 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.
+
+# Monitor the Bot
+
+Monitoring the behavior of the bot is dependent on how your operator setup their instance. ContextMod comes with a built-in web interface that is secure and accessible only to moderates of subreddits it is running on. However there is some additional setup for the operator to perform in order to make this interface accessible publicly. If you do not have access to this interface please communicate with your operator.
+
+After logging in to the interface you will find your subreddit in a tab at the top of the web page. Selecting your subreddit will give you access to:
+
+* Current status of the bot
+* Current status of your configuration
+* Statistics pertaining to the number of checks/rules/actions run and cache usage
+* **A real-time view for bot logs pertaining to your subreddit**
+
+The logs are the meat and potatoes of the bot and the main source of feedback you have for fine-tuning the bot's behavior. The **verbose** log level will show you:
+
+* The event being processed
+* The individual results of triggered rules, per check
+* The checks that were run and their rules
+* The actions performed, with markdown content preview, of triggered checks
+
+This information should enable you to tweak the criteria for your rules in order to get the required behavior from the bot.
+
+Additionally, you can test your bot on any comment/submission by entering its permalink in the text bot at the top of the logs and selecting **Dry Run** -- this will run the bot on an Activity without actually performing any actions allowing you to preview the results of a run.

docs/operator/README.md

@@ -0,0 +1,83 @@
+---
+has_children: true
+nav_order: 4
+---
+
+# Operator
+
+An **Operator** is the user **running the ContextMod software.**
+
+They are responsible for configuring the software at a high-level and managing associated infrastructure such as:
+
+* Creating cache/database servers and configuring their connections in CM
+* Provisioning the [Reddit Clients](#provisioning-a-reddit-client) needed to run bots and the CM UI
+* Providing [global-level configuration](configuration.md) that affects general bot/subreddit behavior
+* Onboarding new bots/subreddits
+
+# Table of Contents
+
+* [Overview](#overview)
+  * [Client-Server Architecture](serverClientArchitecture.md)
+* [Getting Started](gettingStarted.md)
+* [Installation](installation.md)
+* [Provisioning a Reddit Client](#provisioning-a-reddit-client)
+* [Configuration](configuration.md)
+* [Adding A Bot](addingBot.md)
+
+# Overview
+
+CM is composed of two applications that operate independently but are packaged together such that they act as one piece of software:
+
+* **Server** -- Responsible for **running the bot(s)** and providing an API to retrieve information on and interact with them EX start/stop bot, reload config, retrieve operational status, etc.
+* **Client** -- Responsible for serving the **web interface** and handling the bot oauth authentication flow between operators and subreddits/bots.
+
+Both applications authenticate, and are primarily operated, by using [Reddit's API through OAuth.](https://github.com/reddit-archive/reddit/wiki/OAuth2) The **Client** uses OAuth to verify the identity of moderators logging into the web interface. The **Server** uses oauth tokens to interact with Reddit's API and operate all the configured bots.
+
+In its default mode of operation CM takes care of all the interaction between **Server** and **Client** for you so that you can effectively treat it as a monolithic application. Learn more about CM's architecture and other operation modes in the [Server-Client Architecture documentation.](../serverClientArchitecture.md)
+
+# [Getting Started](gettingStarted.md)
+
+The [Getting Started](gettingStarted.md) guide serves as a straight-forward "how-to" for standing up a CM server from scratch with minimal explanation.
+
+# [Installation](installation.md)
+
+CM has many installation options:
+
+* Locally, from source, as a typescript project
+* Built/pulled from a Docker image hosted on Dockerhub
+* Deployed to Heroku with a Quick Deploy template (experimental)
+
+Refer to the [Installation](installation.md) docs for more information.
+
+# Provisioning A Reddit Client
+
+As mentioning in the [Overview](#overview), CM operates primarily using Reddit's API through OAuth. You must create a [Reddit Client](https://github.com/reddit-archive/reddit/wiki/OAuth2#getting-started) in order to interact with the API.
+
+## Create Application
+
+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/callback`
+
+Click **create app**.
+
+Then write down your **Client ID, Client Secret, and Redirect Uri** somewhere
+
+# [Configuration](configuration.md)
+
+The [Configuration](configuration.md) documentation covers:
+
+* How CM's configuration can be defined
+* How to create and define location for a config file
+* Running CM from the command line
+* Documentation for configuration on Bots, the web client, API, and more...
+
+# [Adding A Bot](addingBot.md)
+
+The [Adding A Bot](addingBot.md) documentation covers:
+
+* What is a Bot?
+* What is needed to add a Bot to CM?
+* Different approaches to authenticating and adding a Bot to CM

docs/operator/addingBot.md

@@ -0,0 +1,93 @@
+---
+parent: Operator
+nav_order: 4
+---
+
+# Adding A Bot
+
+# Table of Contents
+
+* [What is a Bot?](#what-is-a-bot)
+* [Prerequisites](#Prerequisites)
+* [Adding a Bot to CM](#adding-a-bot-to-cm)
+  * [Using CM OAuth Helper (Recommended)](#cm-oauth-helper-recommended)
+  * [Using Aardvark OAuth Helper](#aardvark-oauth-helper)
+
+# What is a Bot?
+
+A **reddit bot** is composed of two components:
+
+* A normal **reddit account** like `u/MyRedditAccount`
+* Software that performs actions **on behalf of that reddit account** using Reddit's API
+
+There is nothing special about the account! What's special is how its used -- through the API *with bot software* like ContextMod.
+
+# Prerequisites
+
+These things need to be done before a Bot can be added to CM:
+
+* [Provisioned a Reddit Client](README.md#provisioning-a-reddit-client)
+* You or the person who controls the Bot account must have account credentials (username/password). Logging in to reddit is part of the setup process.
+  * If the bot does not exist **create a reddit account for it.**
+  * If the bot does exist make sure you are in communication with the owner of the account.
+
+# Adding A Bot to CM
+
+## CM OAuth Helper (Recommended)
+
+This method will use CM's built in oauth flow. It is recommended because:
+
+* It's easy!
+* Will ensure your bot is authenticated with the correct oauth permissions
+
+### Start CM with the Minimum Configuration (Initial Setup)
+
+If this is your **first time adding a bot** you must make sure you have
+
+* done the [prerequisites](#prerequisites)
+* created a [minimum operator configuration](configuration.md#minimum-config)
+  * that specifies the client id/secret from provisioning your reddit client
+  * specified **Operator Name** in the configuration
+
+It is important you define **Operator Name** because the auth route is **protected.** You must login to CM's web interface in order to access the route.
+
+### Create A Bot Invite
+
+Open the CM web interface (default is [http://localhost:8085](http://localhost:8085)) and login with the reddit account specified in **Operator Name.**
+
+If this is your first time setting up a bot you should be automatically redirected to the auth page. Otherwise, visit [http://localhost:8085/auth/helper](http://localhost:8085/auth/helper)
+
+Follow the directions in the helper to create a **Bot Invite Link.**
+
+### Onboard the Bot
+
+Visit the **Bot Invite Link** while **logged in to reddit as the bot account** to begin the onboarding process. Refer to the [Onboarding Your Bot]() subreddit documentation for more information on this process.
+
+At the end of the onboarding process the bot should be automatically added to your operator configuration. If there is an issue with automatically adding it then the oauth credentials will be displayed at the end of onboarding and can be [manually added to the configuration.](configuration.md#manually-adding-a-bot)
+
+## Aardvark OAuth Helper
+
+This method should only be used if you cannot use the [CM OAuth Helper method.](#cm-oauth-helper-recommended)
+
+* Visit [https://not-an-aardvark.github.io/reddit-oauth-helper/](https://not-an-aardvark.github.io/reddit-oauth-helper/) and follow the instructions given.
+  * **Note:** You will need to update the **redirect uri** you set when [provisioning your reddit client.](README.md#provisioning-a-reddit-client)
+* Input your **Client ID** and **Client Secret** in the text boxes with those names.
+* Choose scopes. **It is very important you check everything on this list or CM may not work correctly**
+  * edit
+  * flair
+  * history
+  * identity
+  * modcontributors
+  * modflair
+  * modposts
+  * modself
+  * modnote
+  * mysubreddits
+  * read
+  * report
+  * submit
+  * wikiread
+  * wikiedit (if you are using Toolbox User Notes)
+* Click **Generate tokens**, you will get a popup asking you to approve access (or login) -- **the account you approve access with is the account that Bot will control.**
+* After approving an **Access Token** and **Refresh Token** will be shown at the bottom of the page. Use these to [manually add a bot to your operator configuration.](configuration.md#manually-adding-a-bot)
+  * After adding the bot you will need to restart CM.

docs/operator/caching.md

@@ -0,0 +1,167 @@
+---
+parent: Operator
+---
+
+# Caching
+
+# Table of Contents
+
+* [Overview](#overview)
+  * [What Is Cache?](#what-is-cache)
+  * [How CM Uses Caching](#how-cm-uses-caching)
+    * [Reddit API Calls](#reddit-api-calls)
+    * [Rules and Filters](#rules-and-filters)
+* [Configuration](#configuration)
+  * [Cache Provider](#cache-provider)
+
+# Overview
+
+**Caching** is a major factor in CM's performance and optimization of Reddit API usage. Leveraging caching effectively in your operator configuration and in individual subreddit configurations can make or break your CM instance.
+
+### What Is Cache?
+
+A **Cache** is a storage medium with high **write** and **read** speed that is generally used to store **temporary, but frequently accessed data.**
+
+## How CM Uses Caching
+
+CM primarily **caches** two types of data:
+
+### Reddit API Calls
+
+#### How Reddit's API Works
+
+In order to communicate with Reddit to retrieve posts, comments, user information, etc... CM uses API calls. Each API call is composed of a
+
+* **request** -- CM asks Reddit for certain information
+* **response** -- Reddit responds with the request information
+
+[Reddit imposes an **api quota**](https://github.com/reddit-archive/reddit/wiki/API#rules) on every **individual account** using the API through an application. This quota is **600 requests per 10 minutes.** At the end of the 10 minutes period the quota is reset.
+
+Additionally, some API calls have limits on how much data they can return. The most relevant of these is **user history can only be returned 100 activities (submission/comments) per API call**. EX if you want to get **500** activities from a user's history you will need to make **5** api calls.
+
+#### Caching API Responses
+
+In order to most effectively use the limited quota of API calls CM will **automatically cache API responses based on the "fingerprint" of the request sent.**
+
+On an individual "item" basis that means these resources are always cached:
+
+* General user information (name, karma, age, profile description, etc..)
+* General subreddit information (name, nsfw, quarantined, etc...)
+* Individually processed activities (comment body, is comment author op, submission title, reports, link, etc...)
+
+Additionally (and most importantly), responses for **user history** are cached **based on what was requested**. Example "fingerprint":
+
+* username
+* type of activities to retrieve (overview, only submissions, only comments)
+* range of activities to retrieve (last 100, last 6 months, etc...)
+
+If the above "fingerprint" is used in three different Rules then
+
+* First fingerprint appearance -> CM make API call and caches response
+* Second fingerprint appearance -> CM uses cached response
+* Third fingerprint appearance -> CM uses cached response
+
+So only **one** API call is made even though the history is used three times.
+
+It is therefore **important to re-use window criteria** wherever possible to take advantage of this caching.
+
+### Rules and Filters
+
+Once CM has processed a Rule or Filter (`itemIs` or `authorIs`) the results of that component is stored in cache. For Rules the result is stored for the lifecycle of the Activity being processed and then discarded. For Filters the result is stored for a short time in cache and can be re-used by other Activities.
+
+Re-using Rules and Filters by either using the exact same configuration or by using **names** provides:
+
+* A major performance benefit since these do not need to be re-calculated
+* A low-to-medium optimization on API caching, depending on what criteria are being tested.
+
+In general re-use should always be a goal.
+
+# Configuration
+
+## Cache Provider
+
+CM supports two cache **providers**. By default all providers use `memory`:
+
+* `memory` -- in-memory (non-persistent) backend
+  * Cache will be lost when CM is restarted/exits
+* `redis` -- [Redis](https://redis.io/) backend
+
+Each `provider` object in configuration can be specified as:
+
+* one of the above **strings** to use the **defaults settings** or
+* an **object** with keys to override default settings
+
+[Refer to full documentation on cache providers in the schema](https://json-schema.app/view/%23/%23%2Fdefinitions%2FOperatorCacheConfig/%23%2Fdefinitions%2FCacheOptions?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+Some examples:
+
+```json5
+{
+ "provider": {
+   "store": "memory", // one of "memory" or "redis"
+   "ttl": 60, // the default max age of a key in seconds
+   "max": 500, // the maximum number of keys in the cache (for "memory" only)
+   
+   // the below properties only apply to 'redis' provider
+   "host": 'localhost',
+   "port": 6379,
+   "auth_pass": null,
+   "db": 0,
+ }
+}
+```
+
+YAML
+
+```yaml
+provider:
+  store: redis
+  ttl: 60
+  max: 500
+  host: localhost
+  port: 6379
+  auth_pass: null
+  db: 0
+```
+
+Providers can be specified in multiple locations, with each more specific location overriding the parent-level config:
+
+* top-level config
+* in individual bot configurations
+* in the web config
+
+```yaml
+operator:
+ name: example
+# top level
+caching:
+ provider:
+  ...
+bots:
+  - name: u/MyBot
+    # overrides top level
+    caching:
+     provider:
+      ...
+web:
+  # overrides top level
+  caching:
+    provider:
+     ...
+```
+
+## Cache TTL
+
+The **Time To Live (TTL)** -- how long data may live in the cache before "expiring" -- can be controlled indepedently for different data types. Sane defaults are provided for all types but tweaking these can improve API caching optimization depending on the subreddit's configuration (use case).
+
+Each of these can be specified in the `caching` property. TTL is measured in seconds.
+
+* `authorTTL` (default 60) -- user activity (overview, submissions, comments)
+* `commentTTL` (default 60) -- individually fetched comments
+* `submissionTTL` (default 60) -- individually fetched submissions
+* `filterCriteriaTTL` (default 60) -- filter results (`itemIs` and `authorIs`)
+* `selfTTL` (default 60) -- actions performed by the bot (creating comment reply, report). If action is in cache the bot ignores it if found during polling.
+  * This helps prevent bot from reacting to things it did itself IE you don't want it to remove a comment because it reported the comment itself
+* `subredditTTL` (default 60) -- general information on fetched subreddit
+* `userNotesTTL` (default 300) -- Amount of time [Toolbox User Notes](https://www.reddit.com/r/toolbox/wiki/docs/usernotes) are cached
+* `wikiTTL` (default 300) -- Wiki pages used for content (in messages, reports, bans, etc...) are cached for this amount of time

docs/operator/configuration.md

@@ -0,0 +1,415 @@
+---
+parent: Operator
+nav_order: 3
+---
+
+# Configuration
+
+The **Operator** configuration refers to configuration used configure to the actual application/bot. This is different
+from the **Subreddit** configuration that is defined in each Subreddit's wiki and determines the rules/actions for
+activities the Bot runs on.
+
+**The full documentation** for all options in the operator configuration can be found [**here in the operator schema.**](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+# Table of Contents
+
+* [Defining Configuration](#defining-configuration)
+* [CLI Usage](#cli-usage)
+* [Minimum Configuration](#minimum-configuration)
+* [Bots](#bots)
+* [Examples](#example-configurations)
+  * [Minimum Config](#minimum-config)
+  * [Using Config Overrides](#using-config-overrides)
+* [Cache Configuration](#cache-configuration)
+* [Database Configuration](#database-configuration)
+
+# Defining Configuration
+
+CM can be configured using **any or all** of the approaches below. **It is recommended to use FILE ([File Configuration](#file-configuration-recommended))**
+
+Any values defined at a **lower-listed** level of configuration will override any values from a higher-listed
+configuration.
+
+* **ENV** -- Environment variables loaded from an [`.env`](https://github.com/toddbluhm/env-cmd) file (path may be
+  specified with `--file` cli argument)
+* **ENV** -- Any already existing environment variables (exported on command line/terminal profile/etc.)
+* **FILE** -- Values specified in a YAML/JSON configuration file using the structure [in the schema](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+  * When reading the **schema** if the variable is available at a level of configuration other than **FILE** it will be
+    noted with the same symbol as above. The value shown is the default.
+* **ARG** -- Values specified as CLI arguments to the program (see [ClI Usage](#cli-usage) below)
+
+## File Configuration (Recommended)
+
+Using a file has many benefits over using ARG or ENV:
+
+* CM can automatically update your configuration
+* CM can automatically add bots via the [CM OAuth Helper](addingBot.md#cm-oauth-helper-recommended)
+* CM has a built-in configuration editor that can help you build and validate your configuration file
+* File config is **required** if adding multiple bots to CM
+
+### Specify File Location
+
+By default CM will look for `config.yaml` or `config.json` in the `DATA_DIR` directory:
+
+* [Local installation](installation.md#locally) -- `DATA_DIR` is the root of your installation directory (same folder as `package.json`)
+* [Docker](installation.md#docker-recommended) -- `DATA_DIR` is at `/config` in the container
+
+The `DATA_DIR` directory can be changed by passing `DATA_DIR` as an environmental variable EX `DATA_DIR=/path/to/directory`
+
+The name of the config file can be changed by passing `OPERATOR_CONFIG` as an environmental variable:
+
+* As filename -- `OPERATOR_CONFIG=myConfig.yaml` -> CM looks for `/path/to/directory/myConfig.yaml`
+* As absolute path -- `OPERATOR_CONFIG=/a/path/myConfig.yaml` -> CM looks for `/a/path/myConfig.yaml`
+
+[**Refer to the Operator Config File Schema for full documentation**](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+### Defining Multiple Bots or CM Instances
+
+One ContextMod instance can
+
+* Run multiple bots (multiple reddit accounts -- each as a bot)
+* Connect to many other, independent, ContextMod instances
+
+However, the default configuration (using **ENV/ARG**) assumes your intention is to run one bot (one reddit account) on one CM instance without these additional features. This is to make this mode of operation easier for users with this intention.
+
+To take advantage of this additional features you **must** use a **FILE** configuration. Learn about how this works and how to configure this scenario in the [Architecture Documentation.](serverClientArchitecture.md)
+
+## CLI Usage
+
+Running CM from the command line is accomplished with the following command:
+
+```bash
+
+node src/index.js run
+
+```
+
+Run `node src/index.js run help` to get a list of available command line options (denoted by **ARG** above):
+
+<details markdown="block">
+
+```
+Usage: index [options] [command]
+
+Options:
+  -h, --help                                   display help for command
+
+Commands:
+  run [options] [interface]                    Monitor new activities from configured subreddits.
+  check [options] <activityIdentifier> [type]  Run check(s) on a specific activity
+  unmoderated [options] <subreddits...>        Run checks on all unmoderated activity in the modqueue
+  help [command]                               display help for command
+
+
+Options:
+  -c, --operatorConfig <path>   An absolute path to a JSON file to load all parameters from (default: process.env.OPERATOR_CONFIG)
+  -i, --clientId <id>           Client ID for your Reddit application (default: process.env.CLIENT_ID)
+  -e, --clientSecret <secret>   Client Secret for your Reddit application (default: process.env.CLIENT_SECRET)
+  -a, --accessToken <token>     Access token retrieved from authenticating an account with your Reddit Application (default: process.env.ACCESS_TOKEN)
+  -r, --refreshToken <token>    Refresh token retrieved from authenticating an account with your Reddit Application (default: process.env.REFRESH_TOKEN)
+  -u, --redirectUri <uri>       Redirect URI for your Reddit application (default: process.env.REDIRECT_URI)
+  -t, --sessionSecret <secret>  Secret use to encrypt session id/data (default: process.env.SESSION_SECRET || a random string)
+  -s, --subreddits <list...>    List of subreddits to run on. Bot will run on all subs it has access to if not defined (default: process.env.SUBREDDITS)
+  -d, --logDir [dir]            Absolute path to directory to store rotated logs in. Leaving undefined disables rotating logs (default: process.env.LOG_DIR)
+  -l, --logLevel <level>        Minimum level to log at (default: process.env.LOG_LEVEL || verbose)
+  -w, --wikiConfig <path>       Relative url to contextbot wiki page EX https://reddit.com/r/subreddit/wiki/<path> (default: process.env.WIKI_CONFIG || 'botconfig/contextbot')
+  --snooDebug                   Set Snoowrap to debug. If undefined will be on if logLevel='debug' (default: process.env.SNOO_DEBUG)
+  --authorTTL <s>               Set the TTL (seconds) for the Author Activities shared cache (default: process.env.AUTHOR_TTL || 60)
+  --heartbeat <s>               Interval, in seconds, between heartbeat checks. (default: process.env.HEARTBEAT || 300)
+  --softLimit <limit>           When API limit remaining (600/10min) is lower than this subreddits will have SLOW MODE enabled (default: process.env.SOFT_LIMIT || 250)
+  --hardLimit <limit>           When API limit remaining (600/10min) is lower than this all subreddit polling will be paused until api limit reset (default: process.env.SOFT_LIMIT || 250)
+  --dryRun                      Set all subreddits in dry run mode, overriding configurations (default: process.env.DRYRUN || false)
+  --proxy <proxyEndpoint>       Proxy Snoowrap requests through this endpoint (default: process.env.PROXY)
+  --operator <name...>          Username(s) of the reddit user(s) operating this application, used for displaying OP level info/actions in UI (default: process.env.OPERATOR)
+  --operatorDisplay <name>      An optional name to display who is operating this application in the UI (default: process.env.OPERATOR_DISPLAY || Anonymous)
+  -p, --port <port>             Port for web server to listen on (default: process.env.PORT || 8085)
+  -q, --shareMod                If enabled then all subreddits using the default settings to poll "unmoderated" or "modqueue" will retrieve results from a shared request to /r/mod (default: process.env.SHARE_MOD || false)
+  -h, --help                    display help for command
+```
+
+</details>
+
+# Minimum Configuration
+
+The minimum configuration required to run CM assumes you have no bots and want to use CM to [add your first bot.](addingBot.md#cm-oauth-helper-recommended)
+
+You will need have this information available:
+
+* From [provision a reddit client](README.md#provisioning-a-reddit-client)
+  * Client ID
+  * Client Secret
+  * Redirect URI (if different from default `http://localhost:8085/callback`)
+* Operator Name -- username of the reddit account you want to use to administer CM with
+
+See the [**example minimum configuration** below.](#minimum-config)
+
+This configuration can also be **generated** by CM if you start CM with **no configuration defined** and visit the web interface.
+
+# Bots
+
+Configured using the `bots` top-level property. Bot configuration can override and specify many more options than are available at the operator-level. Many of these can also set the defaults for each subreddit the bot runs:
+
+* Of the subreddits this bot moderates, specify a subset of subreddits to run or exclude from running
+* default caching behavior
+* control the soft/hard api usage limits
+* Flow Control defaults
+* Filter Criteria defaults
+* default Polling behavior
+
+[Full documentation for all bot instance options can be found in the schema.](https://json-schema.app/view/%23/%23%2Fdefinitions%2FBotInstanceJsonConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+## Adding A Bot
+
+If you use the [CM OAuth Helper](addingBot.md#cm-oauth-helper-recommended) and it works successfully then the configuration for the Bot will be automatically added.
+
+### Manually Adding a Bot
+
+Add a new *object* to the `bots` property at the top-level of your configuration. If `bots` does not exist create it now.
+
+Minimum information required for a valid bot:
+
+* Client Id
+* Client Secret
+* Refresh Token
+* Access Token
+
+<details markdown="block">
+<summary>Example</summary>
+
+```yaml
+operator:
+  name: YourRedditUsername
+
+bots:
+  - name: u/MyRedditBot # name is optional but highly recommend for readability in both config and web interface
+    credentials:
+      reddit:
+        clientId: f4b4df1c7b2
+        clientSecret: 34v5q1c56ub
+        accessToken: 34_f1w1v4
+        refreshToken: p75_1c467b2
+
+web:
+  credentials:
+    clientId: f4b4df1c7b2
+    clientSecret: 34v5q1c56ub
+    redirectUri: 'http://localhost:8085/callback'
+```
+
+</details>
+
+# Web Client
+
+Configured using the `web` top-level property. Allows specifying settings related to:
+
+* UI port
+* Database and caching connection, if different from global settings
+* Session max age and secret
+* Invite max age
+* Connections to CM API instances (if using multiple)
+
+[Full documentation for all web settings can be found in the schema.](https://json-schema.app/view/%23/%23%2Fproperties%2Fweb?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+# Example Configurations
+
+## Minimum Config
+
+Below are examples of the minimum required config to run the application using all three config approaches independently.
+
+Using **FILE**
+
+<details markdown="block">
+
+See [Specify File Location](#specify-file-location) for where this file would be located.
+
+YAML (`config.yaml`)
+
+```yaml
+operator:
+  name: YourRedditUsername
+web:
+  credentials:
+    clientId: f4b4df1c7b2
+    clientSecret: 34v5q1c56ub
+    redirectUri: 'http://localhost:8085/callback'
+```
+
+JSON (`config.json5`)
+
+```json5
+{
+  "operator": {
+    "name": "YourRedditUsername"
+  },
+  "web": {
+    "credentials": {
+      "clientId": "f4b4df1c7b2",
+      "clientSecret": "34v5q1c56ub",
+      "redirectUri": "http://localhost:8085/callback"
+    }
+  }
+}
+```
+
+</details>
+
+Using **ENV** (`.env`)
+
+<details markdown="block">
+
+```
+OPERATOR=YourRedditUsername
+CLIENT_ID=f4b4df1c7b2
+CLIENT_SECRET=34v5q1c56ub
+REDIRECT_URI=http://localhost:8085/callback
+```
+
+</details>
+
+Using **ARG**
+
+<details markdown="block">
+
+```
+node src/index.js run --clientId=f4b4df1c7b2 --clientSecret=34v5q1c56ub --redirectUri=http://localhost:8085/callback
+```
+
+</details>
+
+## Using Config Overrides
+
+An example of using multiple configuration levels together IE all are provided to the application:
+
+**FILE**
+
+<details markdown="block">
+
+```json
+{
+  "logging": {
+    "level": "debug"
+  }
+}
+```
+
+YAML
+
+```yaml
+logging:
+  level: debug
+```
+
+</details>
+
+**ENV** (`.env`)
+
+<details markdown="block">
+
+```
+CLIENT_SECRET=34v5q1c56ub
+SUBREDDITS=sub1,sub2,sub3
+PORT=9008
+```
+
+</details>
+
+**ARG**
+
+<details markdown="block">
+
+```
+node src/index.js run --subreddits=sub1 --clientId=34v5q1c56ub
+```
+
+</details>
+
+When all three are used together they produce these variables at runtime for the application:
+
+```
+clientId: f4b4df1c7b2
+clientSecret: 34v5q1c56ub
+subreddits: sub1
+port: 9008
+log level: debug
+```
+
+## Configuring Client for Many Instances
+
+See the [Architecture Docs](erverClientArchitecture.md) for more information.
+
+<details markdown="block">
+
+YAML
+
+```yaml
+bots:
+  - credentials:
+      clientId: f4b4df1c7b2
+      clientSecret: 34v5q1c56ub
+      refreshToken: 34_f1w1v4
+      accessToken: p75_1c467b2
+web:
+  credentials:
+    clientId: f4b4df1c7b2
+    clientSecret: 34v5q1c56ub
+    redirectUri: 'http://localhost:8085/callback'
+  clients:
+      # server application running on this same CM instance
+    - host: 'localhost:8095'
+      secret: localSecret
+      # a server application running somewhere else
+    - host: 'mySecondContextMod.com:8095'
+      secret: anotherSecret
+api:
+  secret: localSecret
+```
+
+JSON
+
+```json5
+{
+  "bots": [
+    {
+      "credentials": {
+        "clientId": "f4b4df1c7b2",
+        "clientSecret": "34v5q1c56ub",
+        "refreshToken": "34_f1w1v4",
+        "accessToken": "p75_1c467b2"
+      }
+    }
+  ],
+  "web": {
+    "credentials": {
+      "clientId": "f4b4df1c7b2",
+      "clientSecret": "34v5q1c56ub",
+      "redirectUri": "http://localhost:8085/callback"
+    },
+    "clients": [
+      // server application running on this same CM instance
+      {
+        "host": "localhost:8095",
+        "secret": "localSecret"
+      },
+      // a server application running somewhere else
+      {
+        // api endpoint and port
+        "host": "mySecondContextMod.com:8095",
+        "secret": "anotherSecret"
+      }
+    ]
+  },
+  "api": {
+    "secret": "localSecret",
+  }
+}
+```
+
+</details>
+
+# Cache Configuration
+
+See the [Cache Configuration](caching.md) documentation.
+
+# Database Configuration
+
+See the [Database Configuration](database.md) documentation.

docs/operator/database.md

@@ -0,0 +1,194 @@
+---
+parent: Operator
+---
+
+# Database
+
+# Overview
+
+CM uses a database to store three types of data:
+
+* **Recorded Events** -- an "audit" of how CM processed an Activity (Comment/Submission) and what actions it took based on the result of processing it (comment, report, remove, etc.)
+* Persistent Settings/Data
+  * Settings like the last known state of a Subreddit's bot before the application exited
+  * Web Client sessions and invites -- stuff that should survive a restart
+* Statistics
+  * All-time and time-series high-level statistics like # of events, # of checks run, etc...
+
+CM does NOT store subreddit configurations or any runtime alterations of these configurations. This is to keep configurations **portable** -- on principle, if you (a moderator) choose to use a different CM instance to run your subreddit's bot then it should not function differently.
+
+# Providers
+
+CM uses [TypeORM](https://typeorm.io/) as the database access layer and specifically supports three database types:
+
+* SQLite -- using either [SQL.js](https://sql.js.org) or native SQLite through [better-sqlite3](https://github.com/JoshuaWise/better-sqlite3)
+* MySQL/MariaDB
+* Postgres
+
+The database configuration is specified in the top-level `databaseConfig.connection` property in the operator configuration. EX:
+
+```yaml
+operator:
+  name: u/MyRedditAccount
+databaseConfig:
+  connection:
+   ...
+```
+
+## SQLite
+
+When using a [local installation](installation.md#locally) the default database is `sqljs`, which requires no binary dependencies. When using [docker](installation.md#docker-recommended) the default is `better-sqlite3`.
+
+**NOTE:** It is **NOT RECOMMENDED** to use `sqljs` in a production environment for performance reasons. You should at least switch to `better-sqlite3` or preferably MySql/Postgres.
+
+* [`sqljs` connection options](https://typeorm.io/data-source-options#sqljs-data-source-options)
+* [`better-sqlite3` connection options](https://typeorm.io/data-source-options#better-sqlite3-data-source-options)
+
+For both sqlite types, if no database/location is specified, it will be created in the [`DATA_DIR` directory.](configuration.md#specify-file-location)
+
+If CM detects it cannot **read and write** to the database files, or directory if no files exist, it will fallback to using an in-memory database that will be lost when CM restarts. If you have trouble with r/w permissions and are using docker make sure [file permissions are correct for your mounted volume.](installation.md#linux-host)
+
+## MySQL/MariaDB
+
+[MySQL/MariaDB connection options](https://typeorm.io/data-source-options#mysql--mariadb-data-source-options)
+
+The `database` you specify should exist before using CM.
+
+## Postgres
+
+[Postgres connection options](https://typeorm.io/data-source-options#postgres--cockroachdb-data-source-options)
+
+The `database` and `schema` you specify should exist before using CM.
+
+# Migrations
+
+CM implements database migrations. On startup it will check for any pending migrations. If the database doesn't exist (sqlite) or is empty or no tables conflict it will automatically execute migrations.
+
+If there is any kind of conflict it will **pause startup** and display a prompt in the user interface to confirm migration execution. **You should always backup your database before running migrations.**
+
+To force CM to always run migrations without confirmation set `force` to `true` in the `migrations` property within `databaseConfig`:
+
+```yaml
+databaseConfig:
+  migrations:
+    force: true # always run migrations
+```
+
+### SQLite
+
+When using a SQLite driver CM can create automatic backups for you. Another prompt will be displayed on the migrations page in the web interface to make a copy of your database. You can make CM automatically backup and continue with migrations like so:
+
+```yaml
+databaseConfig:
+  migrations:
+    continueOnAutomatedBackup: true # try to backup sqlite files automatically and continue with migrations if successful
+```
+
+# Recorded Event Retention
+
+The **Recorded Events** CM stores in the database can be controlled per subreddit. By default events will be stored indefinitely.
+
+A **Retention Policy** is a metric to determine what "range" of Recorded Events CM should keep in the database. It can be either:
+
+* A **number** -- The last X number of Recorded Events will be kept
+  * EX `1000` -> Keep the last 1000 events and discard any others.
+* A **duration** -- A time period, starting from now until X `duration` in the past, for which events will be kept
+  * EX `3 months` -> Keep all events created between now and 3 months ago. Anything older than 3 months ago will be discarded.
+
+The Retention Policy can be specified at operator level, bot, subreddit *override*, and subreddit configuration level:
+
+```yaml
+operator:  
+  name: u/MyRedditAccount
+databaseConfig:
+  retention: '3 months' # each subreddit will retain 3 months of recorded events
+bots:
+    # all subreddits this bot moderates will have 3 month retention
+  - name: u/OneBotAccount
+    credentials:
+      ...
+    subreddits:
+      overrides:
+        - name: aSpecialSubredit
+          databaseConfig:
+            # overrides retention for THIS SUBBREDIT ONLY, will retain last 1000 events
+            # -- also overrides any retention set in the subreddit's actual configuration
+            retention: 1000 
+  
+  - name: u/TwoBotAccount
+    credentials:
+      ...
+    databaseConfig:
+      retention: '1 month' # overrides top-level rentention for all subeddits this bot moderates
+```
+
+In a subreddit's config:
+
+```yaml
+polling:
+  - unmoderated
+
+# will retain last 2000 events
+# -- will override top-level operator retention or bot-specific retention
+# -- will NOT override a subreddit override specified in bot coniguration
+retention: 2000 
+
+runs:
+  ...
+```
+
+# Influx
+
+ContextMod supports writing detailed time-series data to [InfluxDB](https://www.influxdata.com/). 
+
+This data can be used to monitor the overall health, performance, and metrics for a ContextMod server. Currently, this data can **only be used by an Operator** as it requires access to the operator configuration and CM instance.
+
+CM supports InfluxDB OSS > 2.3 or InfluxDB Cloud.
+
+**Note:** This is an **advanced feature** and assumes you have enough technical knowledge to follow the documentation provided by each application to deploy and configure them. No support is guaranteed for installation, configuration, or use of Influx and Grafana.
+
+## Supported Metrics
+
+TBA
+
+## Setup
+
+### InfluxDB OSS
+
+* Install [InfluxDB](https://docs.influxdata.com/influxdb/v2.3/install/)
+* [Configure InfluxDB using the UI](https://docs.influxdata.com/influxdb/v2.3/install/#set-up-influxdb-through-the-ui)
+  * You will need **Username**, **Password**, **Organization Name**, and **Bucket Name** later for Grafana setup so make sure to record them somewhere
+* [Create a Token](https://docs.influxdata.com/influxdb/v2.3/security/tokens/create-token/) with enough permissions to write/read to the bucket you configured
+  * After the token is created **view/copy the token** to clipboard by clicking the token name. You will need this for Grafana setup.
+
+### ContextMod
+
+Add the following block to the top-level of your operator configuration:
+
+```yaml
+influxConfig:
+  credentials:
+    url: 'http://localhost:8086' # URL to your influx DB instance
+    token: '9RtZ5YZ6bfEXAMPLENJsTSKg==' # token created in the previous step
+    org: MyOrg # organization created in the previous step
+    bucket: contextmod # name of the bucket created in the previous step
+```
+
+## Grafana
+
+A pre-built dashboard for [Grafana](https://grafana.com) can be imported to display overall metrics/stats using InfluxDB data.
+
+![Grafana Dashboard](../images/grafana.jpg)
+
+* Create a new Data Source using **InfluxDB** type
+  * Choose **Flux** for the **Query Language**
+  * Fill in the details for **URL**, **Basic Auth Details** and **InfluxDB Details** using the data you created in the [Influx Setup step](#influxdb-oss)
+  * Set **Min time interval** to `60s`
+  * Click **Save and test**
+* Import Dashboard
+  * **Browse** the Dashboard pane
+  * Click **Import** and **upload** the [grafana dashboard json file](grafana.json)
+    * Chose the data source you created from the **InfluxDB CM** dropdown
+    * Click **Import**
+
+The dashboard can be filtered by **Bots** and **Subreddits** dropdowns at the top of the page to get more specific details.

docs/operator/gettingStarted.md

@@ -0,0 +1,61 @@
+---
+parent: Operator
+nav_order: 1
+---
+
+# Getting Started
+
+This getting started guide is for **Operators** -- that is, someone who wants to run the actual software for a ContentMod bot. If you are a **Moderator** check out the [moderator getting started](/docs/moderators/gettingStarted.md) guide instead.
+
+# Table of Contents
+
+* [Installation](#installation)
+* [Create a Reddit Client](#create-a-reddit-client)
+* [Start ContextMod](#start-contextmod)
+* [Add a Bot to CM](#add-a-bot-to-cm)
+* [Access The Dashboard](#access-the-dashboard)
+* [What's Next?](#whats-next)
+
+# Installation
+
+Follow the [installation](installation.md) documentation. It is recommended to use **Docker** since it is self-contained.
+
+# Create a Reddit Client
+
+[Create a reddit client](README.md#provisioning-a-reddit-client)
+
+# Start ContextMod 
+
+Start CM using the example command from your [installation](#installation) and visit http://localhost:8085
+
+The First Time Setup page will ask you to input:
+
+* Client ID (from [Create a Reddit Client](#create-a-reddit-client))
+* Client Secret (from [Create a Reddit Client](#create-a-reddit-client))
+* Operator -- this is the username of your main Reddit account.
+
+**Write Config** and then restart CM. You have now created the [minimum configuration](configuration.md#minimum-configuration) required to run CM.
+
+# Add A Bot to CM
+
+You should automatically be directed to the [Bot Invite Helper](addingBot.md#cm-oauth-helper-recommended) used to authorize and add a Bot to your CM instance.
+
+Follow the directions here and **create an Authorization Invite** at the bottom of the page. 
+
+Next, login to Reddit with the account you will be using as the Bot and then visit the **Authorization Invite** link you created. Follow the steps there to finish adding the Bot to your CM instance.
+
+# Access The Dashboard
+
+Congratulations! You should now have a fully authenticated bot running on a ContextMod instance.
+
+In order for your Bot to operate in a subreddit it **must be a moderator in that subreddit.** This may be your own subreddit or someone else's.
+
+To monitor the behavior of bots running on your instance visit http://localhost:8085.
+
+# What's Next?
+
+As an operator you should familiarize yourself with how the [operator configuration](configuration.md) you made works. This will help you understand how to get the most of your CM instance by leveraging the [Cache](caching.md) and [Database](database.md) effectively as well as provide you will all possible options for configuring CM using the [schema.](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+If you are also the moderator of the subreddit the bot will be running you should check out the [moderator getting started guide.](../moderators/gettingStarted.md#setup-wiki-page)
+
+You might also be interested in these [quick tips for using the web interface](../webInterface.md). Additionally, on the dashboard click the **Help** button at the top of the page to get a guided tour of the dashboard.

docs/operator/installation.md

@@ -0,0 +1,133 @@
+---
+parent: Operator
+nav_order: 2
+---
+
+# Installation
+
+In order to run a ContextMod instance you must first you must install it somewhere.
+
+ContextMod can be run on almost any operating system but it is recommended to use Docker due to ease of deployment.
+
+## Docker (Recommended)
+
+PROTIP: Using a container management tool like [Portainer.io CE](https://www.portainer.io/products/community-edition) will help with setup/configuration tremendously.
+
+Images available from these registeries:
+
+* [Dockerhub](https://hub.docker.com/r/foxxmd/context-mod) - `docker.io/foxxmd/context-mod`
+* [GHCR](https://github.com/foxxmd/context-mod/pkgs/container/context-mod) - `ghcr.io/foxxmd/context-mod`
+
+An example of starting the container using the [minimum configuration](configuration.md#minimum-config):
+
+* Bind the directory where your config file, logs, and database are located on your host machine into the container's default `DATA_DIR` by using `-v /host/path/folder:/config`
+  * Note: **You must do this** or else your configuration will be lost next time your container is updated.
+* Expose the web interface using the container port `8085`
+
+```
+docker run -d -v /host/path/folder:/config -p 8085:8085 ghcr.io/foxxmd/context-mod:latest
+```
+
+The location of `DATA_DIR` in the container can be changed by passing it as an environmental variable EX `-e "DATA_DIR=/home/abc/config`
+
+### Linux Host
+
+**NOTE:** If you are using [rootless containers with Podman](https://developers.redhat.com/blog/2020/09/25/rootless-containers-with-podman-the-basics#why_podman_) this DOES NOT apply to you.
+
+If you are running Docker on a **Linux Host** you must specify `user:group` permissions of the user who owns the **configuration directory** on the host to avoid [docker file permission problems.](https://ikriv.com/blog/?p=4698) These can be specified using the [environmental variables **PUID** and **PGID**.](https://docs.linuxserver.io/general/understanding-puid-and-pgid)
+
+To get the UID and GID for the current user run these commands from a terminal:
+
+* `id -u` -- prints UID
+* `id -g` -- prints GID
+
+```
+docker run -d -v /host/path/folder:/config -p 8085:8085 -e PUID=1000 -e PGID=1000 ghcr.io/foxxmd/context-mod:latest
+```
+
+### Docker-Compose
+
+The included [`docker-compose.yml`](/docker-compose.yml) provides production-ready dependencies for CM to use:
+
+* [Redis](https://redis.io/) for caching
+* [MariaDB](https://mariadb.org/) for database
+* Optionally, [Influx/Grafana](database.md#influx) instances
+
+#### Setup
+
+The included `docker-compose.yml` file is written for **Docker Compose v2.**
+
+For new installations copy [`config.yaml`](/docker/config/docker-compose/config.yaml) into a folder named `data` in the same folder `docker-compose.yml` will be run from. For users migrating their existing CM instances to docker-compose, copy your existing `config.yaml` into the same `data` folder.
+
+Read through the comments in both `docker-compose.yml` and `config.yaml` and makes changes to any relevant settings (passwords, usernames, etc...). Ensure that any settings used in both files (EX mariaDB passwords) match.
+
+To build and start CM:
+
+```bash
+docker compose up -d
+```
+
+To include Grafana/Influx dependencies run:
+
+```bash
+docker compose --profile full up -d
+```
+
+## Locally
+
+Requirements:
+
+* [Typescript](https://www.typescriptlang.org/) >=4.3.5
+* [Node](https://nodejs.org) >=16
+  * [NPM](https://www.npmjs.com/) >=8 (usually bundled with Node)
+
+Clone this repository somewhere and then install from the working directory
+
+```bash
+git clone https://github.com/FoxxMD/context-mod.git .
+cd context-mod
+npm install
+tsc -p .
+```
+
+An example of running CM using the [minimum configuration](configuration.md#minimum-config) with a [configuration file](configuration.md#file-configuration-recommended):
+
+```bash
+node src/index.js run
+```
+
+## [Heroku Quick Deploy](https://heroku.com/about)
+
+**NOTE:** This is still experimental and requires more testing.
+
+[![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.
+
+# Memory Management
+
+Node exhibits [lazy GC cleanup](https://github.com/FoxxMD/context-mod/issues/90#issuecomment-1190384006) which can result in memory usage for long-running CM instances increasing to unreasonable levels. This problem does not seem to be an issue with CM itself but with Node's GC approach. The increase does not affect CM's performance and, for systems with less memory, the Node *should* limit memory usage based on total available.
+
+In practice CM uses ~130MB for a single bot, single subreddit setup. Up to ~350MB for many (10+) bots or many (20+) subreddits.
+
+If you need to reign in CM's memory usage for some reason this can be addressed by setting an upper limit for memory usage with `node` args by using either:
+
+**--max_old_space_size=**
+
+Value is megabytes. This sets an explicit limit on GC memory usage.
+
+This is set by default in the [Docker](#docker-recommended) container using the env `NODE_ARGS` to `--max_old_space_size=512`. It can be disabled by overriding the ENV.
+
+**--optimize_for_size**
+
+Tells Node to optimize for (less) memory usage rather than some performance optimizations. This option is not memory size dependent. In practice performance does not seem to be affected and it reduces (but not entirely prevents) memory increases over long periods.

docs/operator/serverClientArchitecture.md

@@ -0,0 +1,76 @@
+---
+parent: Operator
+---
+
+# Architecture
+
+# Overview
+
+ContextMod's high-level functionality is separated into two **independently run** applications.
+
+Each application consists of an [Express](https://expressjs.com/) web server that executes the core logic for that application and communicates via HTTP API calls:
+
+Applications:
+
+* **Server** -- Responsible for **running the bots** and providing an API to retrieve information on and interact with them EX start/stop bot, reload config, retrieve operational status, etc.
+* **Client** -- Responsible for serving the **web interface** and handling the bot oauth authentication flow between operators and moderators.
+
+Both applications operate independently and can be run individually. The determination for which is run is made by environmental variables, operator config, or cli arguments.
+
+# Authentication
+
+Communication between the applications is secured using [Json Web Tokens](https://github.com/mikenicholson/passport-jwt) signed/encoded by a **shared secret** (HMAC algorithm). The secret is defined in the operator configuration.
+
+# Configuration
+
+## Default Mode
+
+**ContextMod is designed to operate in a "monolith" mode by default.**
+
+This is done by assuming that when configuration is provided by **environmental variables or CLI arguments** the user's intention is to run the client/server together with only one bot, as if ContextMod is a monolith application. When using these configuration types the same values are parsed to both the server/client to ensure interoperability/transparent usage for the operator. Some examples of this in the **operator configuration**:
+
+* The **shared secret** for both client/secret cannot be defined using env/cli -- at runtime a random string is generated that is set for the value `secret` on both the `api` and `web` properties.
+* The `bots` array cannot be defined using env/cli -- a single entry is generated by the configuration parser using the combined values provided from env/cli
+* The `PORT` env/cli argument only applies to the `client` wev server to guarantee the default port for the `server` web server is used (so the `client` can connect to `server`)
+
+**The end result of this default behavior is that an operator who does not care about running multiple CM instances does not need to know or understand anything about the client/server architecture.**
+
+## Server
+
+To run a ContextMod instance as **sever only (headless):**
+
+* Config file -- define top-level `"mode":"server"`
+* ENV -- `MODE=server`
+* CLI - `node src/index.js run server`
+
+The relevant sections of the **operator configuration** for the **Server** are:
+
+* [`operator.name`](https://json-schema.app/view/%23/%23%2Fproperties%2Foperator?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json) -- Define the reddit users who will be able to have full access to this server regardless of moderator status
+* `api`
+
+### [`api`](https://json-schema.app/view/%23/%23%2Fproperties%2Fapi?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+* `port` - The port the Server will listen on for incoming api requests. Cannot be the same as the Client (when running on the same host)
+* `secret` - The **shared secret** that will be used to verify incoming api requests coming from an authenticated Client.
+* `friendly` - An optional string to identify this **Server** on the client. It is recommended to provide this otherwise it will default to `host:port`
+
+## Client
+
+To run a ContextMod instance as **client only:**
+
+* Config file -- define top-level `"mode":"client"`
+* ENV -- `MODE=client`
+* CLI - `node src/index.js run client`
+
+### [`web`](https://json-schema.app/view/%23/%23%2Fproperties%2Fweb?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FOperatorConfig.json)
+
+In the **operator configuration** the top-level `web` property defines the configuration for the **Client** application.
+
+* `web.credentials` -- Defines the reddit oauth credentials used to authenticate users for the web interface
+  * Must contain a `redirectUri` property to work
+  * Credentials are parsed from ENV/CLI credentials when not specified (IE will be same as default bot)
+* `web.operators` -- Parsed from `operator.name` if not specified IE will use same users as defined for the bot operators
+* `port` -- the port the web interface will be served from, defaults to `8085`
+* `clients` -- An array of `BotConnection` objects that specify what **Server** instances the web interface should connect to. Each object should have:
+  * `host` -- The URL specifying where the server api is listening ie `localhost:8085`
+  * `secret` -- The **shared secret** used to sign api calls. **This should be the same as `api.secret` on the server being connected to.**

docs/subreddit-configuration/actionTemplating.md

@@ -0,0 +1,204 @@
+---
+parent: Subreddit Configuration
+---
+
+# Action Templating
+
+Actions that can submit text (Report, Comment, UserNote, Message, Ban, Submission) will have their `content` values run through a [Mustache Template](https://mustache.github.io/). This means you can insert data generated by Rules into your text before the Action is performed.
+
+See here for a [cheatsheet](https://gist.github.com/FoxxMD/d365707cf99fdb526a504b8b833a5b78) and [here](https://www.tsmean.com/articles/mustache/the-ultimate-mustache-tutorial/) for a more thorough tutorial.
+
+# Template Data
+
+Some data can always be accessed at the top-level. Example
+
+```
+This action was run from {{manager}} in Check {{check}}.
+
+The bot intro post is {{botLink}}
+
+Message the moderators of this subreddit using this [compose link]({{modmailLink}})
+```
+
+
+
+|     Name      |                                         Description                                         |                                                                         Example                                                                          |
+|---------------|---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `manager`     | The name of the subreddit the bot is running in                                             | mealtimevideos                                                                                                                                           |
+| `check`       | The name of the Check that was triggered                                                    | myCheck                                                                                                                                                  |
+| `botLink`     | A link to the bot introduction                                                              | https://www.reddit.com/r/ContextModBot/comments/otz396/introduction_to_contextmodbot                                                                     |
+| `modmailLink` | A link that opens reddit's DM compose with the subject line as the Activity being processed | https://www.reddit.com/message/compose?to=/r/mealtimevideos&message=https://www.reddit.com/r/ContextModBot/comments/otz396/introduction_to_contextmodbot |
+
+
+## Activity Data
+
+**Activity data can be accessed using the `item` variable.** Example
+
+```
+This activity is a {{item.kind}} with {{item.votes}} votes, created {{item.age}} ago.
+```
+Produces:
+
+> This activity is a submission with 10 votes created 5 minutes ago.
+
+### Common
+
+All Actions with `content` have access to this data:
+
+|     Name     |                                             Description                                             |                         Example                          |
+|--------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------|
+| `kind`       | The Activity type (submission or comment)                                                           | submission                                               |
+| `author`     | Name of the Author of the Activity being processed                                                  | FoxxMD                                                   |
+| `permalink`  | URL to the Activity                                                                                 | https://reddit.com/r/mySuibreddit/comments/ab23f/my_post |
+| `votes`      | Number of upvotes                                                                                   | 69                                                       |
+| `age`        | The age of the Activity in a [human friendly format](https://day.js.org/docs/en/durations/humanize) | 5 minutes                                                |
+| `subreddit`  | The name of the subreddit the Activity is from                                                      | mealtimevideos                                           |
+| `id`         | The `Reddit Thing` ID for the Activity                                                              | t3_0tin1                                                 |
+| `title`      | As comments => the body of the comment. As Submission => title                                      | Test post please ignore                                  |
+| `shortTitle` | The same as `title` but truncated to 15 characters                                                  | test post pleas...                                       |
+
+#### Common Author
+
+Additionally, `author` has these properties accessible:
+
+|      Name      |             Description             | Example  |
+|----------------|-------------------------------------|----------|
+| `age`          | (Approximate) Age of account        | 3 months |
+| `linkKarma`    | Amount of link karma                | 10       |
+| `commentKarma` | Amount of comment karma             | 3        |
+| `totalKarma`   | Combined link+comment karma         | 13       |
+| `verified`     | Does account have a verified email? | true     |
+
+NOTE: Accessing these properties may require an additional API call so use sparingly on high-volume comments
+
+##### Example Usage
+
+```
+The user {{item.author}} has been a redditor for {{item.author.age}}
+```
+Produces:
+
+> The user FoxxMD has been a redditor for 3 months
+
+### Submissions
+
+If the **Activity** is a Submission these additional properties are accessible:
+
+| Name          | Description                                                     | Example                 |
+|---------------|-----------------------------------------------------------------|-------------------------|
+| `upvoteRatio` | The upvote ratio                                                | 100%                    |
+| `nsfw`        | If the submission is marked as NSFW                             | true                    |
+| `spoiler`     | If the submission is marked as a spoiler                        | true                    |
+| `url`         | If the submission was a link then this is the URL for that link | http://example.com      |
+| `title`       | The title of the submission                                     | Test post please ignore |
+
+### Comments
+
+If the **Activity** is a Comment these additional properties are accessible:
+
+| Name | Description                                                  | Example |
+|------|--------------------------------------------------------------|---------|
+| `op` | If the Author is the OP of the Submission this comment is in | true    |
+
+### Moderator
+
+If the **Activity** occurred in a Subreddit the Bot moderates these properties are accessible:
+
+| Name          | Description                         | Example |
+|---------------|-------------------------------------|---------|
+| `reports`     | The number of reports recieved      | 1       |
+| `modReports`  | The number of reports by moderators | 1       |
+| `userReports` | The number of reports by users      | 1       |
+
+## Rule Data
+
+### Summary
+
+A summary of what rules were processed and which were triggered, with results, is available using the `ruleSummary` variable. Example:
+
+```
+A summary of rules processed for this activity:
+
+{{ruleSummary}}
+```
+
+Would produce:
+> A summary of rules processed for this activity:
+> 
+> * namedRegexRule - ✘
+> * nameAttributionRule - ✓ - 1 Attribution(s) met the threshold of < 20%, with 1 (3%) of 32 Total -- window: 6 months
+> * noXPost ✓ - ✓ 1 of 1 unique items repeated <= 3 times, largest repeat: 1
+
+
+### Individual
+
+Individual **Rules** can be accessed using the name of the rule, **lower-cased, with all spaces/dashes/underscores.** Example:
+
+```
+Submission was repeated {{rules.noxpost.largestRepeat}} times
+```
+Produces
+
+> Submission was repeated 7 times
+
+## Action Data
+
+### Summary
+
+A summary of what actions have already been run **when the template is rendered**  is available using the `actionSummary` variable. It is therefore important that the Action you want to produce the summary is run **after** any other Actions you want to get a summary for.
+
+Example:
+
+```
+A summary of actions processed for this activity, so far:
+
+{{actionSummary}}
+```
+
+Would produce:
+> A summary of actions processed for this activity, so far:
+>
+> * approve - ✘ - Item is already approved??
+> * lock - ✓
+> * modnote - ✓ - (SOLID_CONTRIBUTOR) User is good
+
+### Individual
+
+Individual **Actions** can be accessed using the name of the action, **lower-cased, with all spaces/dashes/underscores.** Example:
+
+```
+User was banned for {{actions.exampleban.duration}} for {{actions.exampleban.reason}}
+```
+Produces
+
+> User was banned for 4 days for toxic behavior
+
+# Quick Templating Tutorial
+
+As a quick example for how you will most likely be using templating -- wrapping a variable in curly brackets, `{{variable}}`, will cause the variable value to be rendered instead of the brackets:
+
+```
+
+myVariable = 50;
+myOtherVariable = "a text fragment"
+template = "This is my template, the variable is {{myVariable}}, my other variable is {{myOtherVariable}}, and that's it!";
+
+console.log(Mustache.render(template, {myVariable});
+// will render...
+"This is my template, the variable is 50, my other variable is a text fragment, and that's it!";
+
+```
+
+**Note: When accessing an object or its properties you must use dot notation**
+
+```
+
+const item = {
+    aProperty: 'something',
+    anotherObject: {
+        bProperty: 'something else'
+    }
+}
+const content = "My content will render the property {{item.aProperty}} like this, and another nested property {{item.anotherObject.bProperty}} like this."
+
+```

docs/subreddit-configuration/activitiesWindow.md

@@ -0,0 +1,497 @@
+---
+parent: Subreddit Configuration
+---
+
+# Activities `window`
+
+# Table Of Contents
+
+* [Overview](#overview)
+  * [Lifecycle](#lifecycle)
+* Window Components
+  * [Range](#range)
+    * [Count](#count)
+    * [Duration](#duration)
+      * [Duration String](#duration-string-recommended)
+      * [Duration Object](#duration-object)
+    * [Specifying Range](#specifying-range)
+  * [Specifying Activity Type](#types-of-activities)
+  * [Filters](#filters)
+    * [Properties](#filter-properties)
+    * [Lifecycle](#filter-lifecycle)
+      * [`pre`](#pre-filter)
+      * [`post`](#post-filter)
+* [More Examples](#more-examples)
+  * [Count](#count-examples)
+  * [Duration](#duration-examples)
+  * [Count And Duration](#count-and-duration-examples)
+  * [Activity Types](#activity-type-examples)
+  * [Filter](#filter-examples)
+
+# Overview
+
+An **Activity Window** (`window`) is a group of properties that describe a **range** of [**Activities**](../README.md#activity) to retrieve from Reddit and how to **filter** them.
+
+The main components of an Activity Window:
+
+* **Range** -- How many Activities ([`count`](#count)) or what time period ([`duration`](#duration)) of Activities to fetch
+* **Type of Activities** -- When **fetching** from an Author's history, should it return overview (any Activities), just Submissions, or just Comments?
+* **Filters** -- How the retrieved Activities should be [filtered](README.md#filters) before returning them to a Rule
+
+
+As an example, if you want to run a **Recent Activity Rule** to check if a user has had activity in /r/mealtimevideos you also need to define what range of activities you want to look at from that user's history.
+
+## Lifecycle
+
+Understanding the lifecycle for how CM uses the Activity Window to retrieve Activities is important to effectively using it.
+
+```mermaid
+graph TD
+    RangReq["Determine Range requirements (Parse `count` and `duration` values)"] --> EmptyList>Create empty Activities List]
+    EmptyList --> Fetch>"Fetch Activities chunk (1 API Call)"]
+    Fetch --> PreFilter>Invoke `pre` filter on Activities from chunk]
+    PreFilter --> Add[Add filtered chunk to Activities list] 
+    Add --> CheckRange>Check Range Satisfaction]
+    CheckRange -->|`count` Range| CountReq[Are there `count` # of Activities?]
+    CheckRange -->|`duration` Range| DurationReq[Is the oldest Activity `duration` old?]
+    CheckRange -->|`count` and `duration` Range| CountDurReq[Is either `count` and/or `duration` satisfied?]
+
+
+    CountReq -->|No| Fetch
+    DurationReq -->|No| Fetch
+    CountDurReq -->|No| Fetch
+
+    CountReq -->|Yes| FetchDone
+    DurationReq -->|Yes| FetchDone
+    CountDurReq -->|Yes| FetchDone
+
+    FetchDone[Fetch Complete] --> PostFilter>Invoke `post` filter on all Activities]
+    PostFilter --> Return>Return Activities to Rule]
+
+    click PreFilter href "#pre-filter"
+    click PostFilter href "#post-filter"
+    click CountReq href "#count"
+    click DurationReq href "#duration"
+    click CountDurReq href "#specifying-range"
+```
+
+# Range
+
+There are two types of values that can be used when defining a range:
+
+## Count
+
+This is the **number** of activities you want to retrieve. It's straightforward -- if you want to look at the last 100 activities for a user you can use `100` as the value.
+
+### Shorthand
+
+If **count** is the only property you want to define (leaving everything else as default) then `window` can be defined with just this value:
+
+```yaml
+window: 70 # retrieve 70 activities
+```
+****
+Otherwise, use the `count` property on a full `window` object:
+
+```yaml
+window:
+  count: 70 # retrieve 70 activities
+  ...
+```
+
+## Duration
+
+A **duration of time** between which all activities will be retrieved. This is a **relative value** that calculates the actual range based on **the duration of time subtracted from when the rule is run.**
+
+For example:
+
+* Today is **July 15th**
+* You define a duration of **10 days**
+
+Then the range of activities to be retrieved will be between **July 5th and July 15th** (10 days).
+
+### Shorthand
+
+If a Duration string is the only property you want to define (leaving everything else as default) then `window` can be defined with just this value:
+
+```yaml
+window: '9 days' # retrieve last 9 days of activities
+```
+
+Otherwise, use the `duration` property on a full `window` object:
+
+```yaml
+window:
+  duration: '9 days'
+  ...
+```
+
+### Duration Types
+
+The value used to define the duration can be **one of these two types**:
+
+#### Duration String (recommended)
+
+A string consisting of
+
+* A [Dayjs unit of time](https://day.js.org/docs/en/durations/creating#list-of-all-available-units)
+* The value of that unit of time
+
+Examples:
+
+* `9 days`
+* `14 hours`
+* `80 seconds`
+
+You can ensure your string is valid by testing it [here.](https://regexr.com/61em3)
+
+##### As ISO 8601 duration string
+
+If you're a real nerd you can also use a [standard duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) string.
+
+Examples
+
+* `PT15M` (15 minutes)
+
+Ensure your string is valid by testing it [here.](https://regexr.com/61em9)
+
+#### Duration Object
+
+If you need to specify multiple units of time for your duration you can instead provide a [Dayjs duration **object**](https://day.js.org/docs/en/durations/creating#list-of-all-available-units) consisting of Dayjs unit-values.
+
+```yaml
+window:
+  duration:
+    days: 4
+    hours: 6
+    minutes: 20
+```
+
+## Specifying Range
+
+You may use **one or both range properties.**
+
+If both range properties are specified then the value `satisfyOn` determines how the final range is determined
+
+
+### Using `satisfyOn: any` (default)
+
+If **any** then Activities will be retrieved until one of the range properties is met, **whichever occurs first.**
+
+```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
+* If 80 activities is only 20 days of range => 80 activities
+
+### Using `satisfyOn: all`
+
+If **all** then both ranges must be satisfied. Effectively, whichever range produces the most Activities will be the one that is used.
+
+```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
+  * continue retrieving results until 100 activities
+  * so range is >90 days of activities
+* If at 100 activities => 20 days of activities retrieved
+  * continue retrieving results until 90 days of range
+  * so results in >100 activities
+
+# Types of Activities
+
+When retrieving an Author's history the window can specify if it should return all Activities (overview), just Comments, or just Submissions, using the `fetch` property:
+
+```yaml
+window:
+  # defaults to 'overview'
+  fetch: 'submission' # must be one of: overview, comment, submission
+```
+
+# Filters
+
+Activity Window can also specify [Item and Subreddit Filters](README.md#filters) to filter the Activities retrieved from Reddit before they are returned to a Rule.
+
+Activities can be filtered **during** (`pre`) retrieval or **after** (`post`) retrieval. **When**, during the window **lifecycle**, the Activities are filtered can change the set of Activities returned to a Rule drastically.
+
+## Filter Properties
+
+Regardless of when you are filtering Activities the shape of the filter is the same. Filter properties:
+
+* `subreddits` -- A [Filter Shape](README.md#filter-shapes) for filtering by the [Subreddit Criteria](README.md#subreddit-filter) of each Activity
+* `submissionState` -- A [Filter Shape](README.md#filter-shapes) for [Submission Criteria](README.md#item-filter). Will run only if filtering a Submission.
+* `commentState` -- A [Filter Shape](README.md#filter-shapes) for [Comment Criteria](README.md#item-filter). Will run only if filtering a Comment.
+* `activityState` -- A [Filter Shape](README.md#filter-shapes) for either [Submission or Comment Criteria](README.md#item-filter). Will run only if `submissionState` or `commentState` is not defined for their respective Activity types.
+
+In this example the filter only returns Activities:
+
+* With a subreddit that
+  * Is from the subreddit /r/mealtimevideos OR
+  * Has a name that matches the regex `/ask.*/i` (starts with `ask`) OR
+  * Is marked as NSFW
+* AND if the Activity is a Submission:
+  * must be self text
+* AND if the Activity is a Comment (because `activityState` is defined and `commentState` is not):
+  * Comment is NOT removed 
+
+```yaml
+subreddits:
+  include:
+    - 'mealtimevideos'
+    - '/ask.*/i'
+    - over18: true
+      
+submissionState:
+  include:
+    - is_self: true
+
+activityState:
+  exclude:
+    - removed: false
+```
+
+## Filter Lifecycle
+
+Filters can be independently specified for two different "locations" during the window lifecycle using the `filterOn` property.
+
+### `pre` Filter
+
+`pre` will filter Activities from **each API call, before** they are added to the full list of retrieved Activities and, most importantly, **before CM checks if Range conditions have been satisfied.** See the [Lifecycle Diagram](#lifecycle).
+
+This is useful when you want the Range conditions to be applied to an "already filtered" list of Activities -- as opposed to afterwards (like `post`).
+
+#### `max` restriction
+
+However, `pre` introduces the possibility of **near impossible range conditions.** 
+
+For example, if you want 200 activities from a subreddit a user has never created activities in then CM would fetch the user's **entire history** before finishing since each chunk of Activities would be filtered to 0.
+
+To prevent this scenario all `pre` filters must also specify a `max` [range](#range) that tell CM:
+
+> if X range of **non-filtered** Activities is reached stop immediately
+
+#### `pre` Example
+
+Let's follow an example scenario where you want the last 200 activities a user has in /r/mealtimevideos
+
+```yaml
+window:
+  count: 200
+  filterOn:
+    pre:
+      subreddits:
+        include:
+          - mealtimevideos
+      max: 400
+```
+
+* CM fetches the first chunk of 100 Activities (100 total unfiltered)
+  * `pre` Filter finds 70 of those 100 are from /r/mealtimevideos => Total Filtered Activities 70
+  * CM Checks range condition => 70 is less than 200
+  * CM Checks max condition => 100 unfiltered is less than 400
+* CM fetches second chunk of 100 Activities (200 total unfiltered)
+  * `pre` Filter finds another 70 of those 100 are from /r/mealtimevideos => Total Filtered Activities 140
+  * CM Checks range condition => 140 is less than 200
+  * CM Checks max condition => 200 unfiltered is less than 400
+* CM fetches third chunk of 100 activities (300 total unfiltered)
+  * `pre` Filter finds 90 of those 100 are from /r/mealtimevideos => Total Filtered Activities 230
+  * CM checks range condition => 230 is more than 200
+  * CM Checks max condition => 300 unfiltered is less than 400
+
+**CM is done fetching activities with 230 Filtered Activities**
+
+Now let's look at the same scenario but `max` is hit:
+
+* CM fetches the first chunk of 100 Activities (100 total unfiltered)
+  * `pre` Filter finds 10 of those 100 are from /r/mealtimevideos => Total Filtered Activities 10
+  * CM Checks range condition => 10 is less than 200
+  * CM Checks max condition => 100 unfiltered is less than 400
+* CM fetches second chunk of 100 Activities (200 total unfiltered)
+  * `pre` Filter finds another 15 of those 100 are from /r/mealtimevideos => Total Filtered Activities 25
+  * CM Checks range condition => 25 is less than 200
+  * CM Checks max condition => 200 unfiltered is less than 400
+* CM fetches third chunk of 100 activities (300 total unfiltered)
+  * `pre` Filter finds 5 of those 100 are from /r/mealtimevideos => Total Filtered Activities 30
+  * CM checks range condition => 30 is less than 200
+  * CM Checks max condition => 300 unfiltered is less than 400
+* CM fetches fourth chunk of 100 activities (400 total unfiltered)
+  * `pre` Filter finds 0 of those 100 are from /r/mealtimevideos => Total Filtered Activities 30
+  * CM checks range condition => 30 is less than 200
+  * CM Checks max condition => 400 unfiltered is NOT less than 400
+    * CM stops fetching due to max condition hit
+
+**CM is done fetching activities with 30 Filtered Activities**
+
+### `post` Filter
+
+`post` will filter the full list of Activities **after range conditions are satisfied**. This also means it receives the list of Activities filtered by the [`pre` filter](#pre-filter), if one is defined.
+
+The list returned by `post` is what the Rule receives.
+
+#### Example
+
+Let's follow an example scenario where you want to get the last 200 activities from a User's history **and then** return any of those 200 that were made in /r/mealtimevideos -- contrast this wording to the [`pre` example](#pre-example)
+
+```yaml
+window:
+  count: 200
+  filterOn:
+    post:
+      subreddits:
+        include:
+          - mealtimevideos
+```
+
+* CM fetches the first chunk of 100 Activities (100 total unfiltered)
+  * CM checks range condition => 100 is less than 200
+* CM fetches the second chunk of 100 Activities (200 total unfiltered)
+  * CM checks range condition => 200 is equal to 200
+* CM is done fetching activities with 200 unfiltered Activities
+  * `post` filter finds 10 of those 200 are from /r/mealtimevideos
+  * CM returns 10 Activities to the Rule
+
+# More Examples
+
+### Count Examples
+
+#### Get last 100 activities in a User's history
+
+```yaml
+window: 100
+```
+or
+
+```yaml
+window:
+  count: 100
+```
+
+### Duration Examples
+
+#### Get last 2 weeks of a User's history
+
+```yaml
+window: '2 weeks'
+```
+or
+
+```yaml
+window:
+  duration: '2 weeks'
+```
+
+#### Get last 24 hours and 30 minutes of User's history
+
+```yaml
+window:
+  duration:
+    hours: 24
+    minutes: 30
+```
+
+### Count and Duration Examples
+
+#### Get EITHER last 6 months or last 200 activities of User's history
+
+Whichever is [satisifed first](#using-satisfyon-any-default)
+
+```yaml
+window:
+  count: 200
+  duration: '6 months'
+```
+
+#### Get AT LEAST the last 6 months and last 200 activities of User's history
+
+Both must be [satisifed](#using-satisfyon-all)
+
+```yaml
+window:
+  count: 200
+  duration: '6 months'
+  satisfyOn: 'all'
+```
+
+### Activity Type Examples
+
+#### Get the last 200 submissions from User's history
+
+```yaml
+window:
+  count: 200
+  fetch: 'submission'
+```
+
+#### Get the last 200 comments from User's history
+
+```yaml
+window:
+  count: 200
+  fetch: 'comment'
+```
+
+#### Get the last 200 activities (submissions or comments) from User's history
+
+```yaml
+window:
+  count: 200
+  fetch: 'overview' # or do not include 'fetch' at all, this is the default
+```
+
+### Filter Examples
+
+#### Get the all activities from NSFW subreddits in the User's last 200 activities
+
+```yaml
+window:
+  count: 200
+  filterOn:
+    post:
+      subreddits:
+        include:
+          - over18: true
+```
+
+#### Get the all comments from NSFW subreddits where user is OP, in the User's last 200 activities
+
+```yaml
+window:
+  count: 200
+  fetch: 'comment'
+  filterOn:
+    post:
+      subreddits:
+        include:
+          - over18: true
+      commentState:
+        include:
+          - op: true
+```
+
+#### Get the last 200 self-text submissions from a User's history and return any from ask* subreddits
+
+```yaml
+window:
+  count: 200
+  fetch: 'submission'
+  filterOn:
+    pre:
+      submissionState:
+        include:
+          - is_self: true
+      max: 500
+    post:
+      subreddits:
+        include:
+          - '/ask.*/i'
+```

docs/subreddit-configuration/advancedConcepts/flowControl.md

@@ -0,0 +1,235 @@
+---
+parent: Subreddit Configuration
+has_toc: false
+---
+
+# Flow Control
+
+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](../README.md#Checks) or 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/operator/gettingStarted.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/subreddit-configuration/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/subreddit-configuration/advancedConcepts/ruleNameReuse.json5

@@ -0,0 +1,79 @@
+{
+  "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/subreddit-configuration/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/subreddit-configuration/advancedConcepts/ruleSets.json5

@@ -0,0 +1,88 @@
+{
+  "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
+              // OR = 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/subreddit-configuration/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
+            # OR = 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/subreddit-configuration/cookbook/README.md

@@ -0,0 +1,205 @@
+---
+parent: Subreddit Configuration
+---
+
+# Cookbook
+
+Here you will find useful configs for CM that provide real-world functionality. This is where you should look first for **"how do i..."** questions.
+
+## How To Use
+
+Each recipe includes what type of config piece it is (Rule, Check, Action, Run, etc...). Keep this in mind before copy-pasting to make sure it goes in the right place in your config.
+
+### Copy-Pasting
+
+If the type is **Check** or **Run** the recipe contents will have instructions in the comments on how to use it as a **full subreddit config** OR **by itself (default).** If not Check/Run then when copy-pasting you will need to ensure it is placed in the correct spot in your config.
+
+
+### As Config Fragment
+
+**Checks, Runs, Actions, and Rule** recipes can be referenced in your config without copy-pasting by using them as [Config Fragments.](../README.md#partial-configurations) These need to be placed in the correct spot in your config, just like copy-pasting, but only require the URL of the recipe instead of all the code.
+
+To use a recipe as a fragment **copy** the URL of the config and insert into your config like this:
+
+```yaml
+- 'url:https://URL_TO_CONFIG'
+```
+
+EXAMPLE: Using the **Config** link from the [Free Karma](#remove-submissions-from-users-who-have-used-freekarma-subs-to-bypass-karma-checks) check below -- copy the **Config** link and insert it into a full subreddit config like this:
+
+<details markdown="block">
+<summary>Config</summary>
+
+```yaml
+polling:
+  - newSub
+runs:
+  - name: MyFirstRun
+    checks:
+       # freekarma check
+      - 'url:https://github.com/FoxxMD/context-mod/blob/master/docs/subreddit/components/cookbook/freekarma.yaml'
+      - name: MyRegularCheck
+        kind: submission
+        # ...
+```
+</details>
+
+# Recipes
+
+## Spam Prevention
+
+### Remove submissions from users who have used 'freekarma' subs to bypass karma checks
+
+* Type: **Check**
+* [Config](freekarma.yaml)
+
+If the user has any activity (comment/submission) in known freekarma subreddits in the past (100 activities) then remove the submission.
+
+### Remove submissions that are consecutively spammed by the author
+
+* Type: **Check**
+* [Config](crosspostSpam.yaml)
+
+If the user has crossposted the same submission in the past (100 activities) 4 or more times in a row then remove the submission.
+
+### Remove submissions if users is flooding new
+
+* Type: **Check**
+* [Config](floodingNewSubmissions.yaml)
+
+If the user has made more than 4 submissions in your subreddit in the last 24 hours than new submissions are removed and user is tagged with a modnote.
+
+### Remove submissions posted in diametrically-opposed subreddit
+
+* Type: **Check**
+* [Config](diametricSpam.yaml)
+
+If the user makes the same submission to another subreddit(s) that are "thematically" opposed to your subreddit it is probably spam. This check removes it. Detects all types of submissions (including images).
+
+### Remove comments that are consecutively spammed by the author
+
+* Type: **Check**
+* [Config](commentSpam.yaml)
+
+If the user made the same comment (with some fuzzy matching) 4 or more times in a row in the past (100 activities or 6 months) then remove the comment.
+
+### Remove comment if it is a chat invite link spam
+
+* Type: **Check**
+* [Config](chatSpam.yaml)
+
+This rule goes a step further than automod can by being more discretionary about how it handles this type of spam.
+
+* Remove the comment if:
+  * Comment being checked contains **only** a chat link (no other text) OR
+  * Chat links appear **anywhere** in three or more of the last 100 comments the Author has made
+
+This way ContextMod can more easily distinguish between these use cases for a user commenting with a chat link:
+
+* actual spammers who only spam a chat 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)
+
+## Repost Detection
+
+### Remove comments reposted from youtube video submissions
+
+* Type: **Check**
+* [Config](youtubeCommentRepost.yaml)
+
+**Requires bot has an API Key for Youtube.**
+
+Removes comment on reddit if the same comment is found on the youtube video the submission is for.
+
+### Remove comments reposted from reddit submissions
+
+* Type: **Check**
+* [Config](commentRepost.yaml)
+
+Checks top-level comments on submissions younger than 30 minutes:
+* Finds other reddit submissions based on crosspost/duplicates/title/URL, takes top 10 submissions based # of upvotes
+  * If this comment matches any top comments from those other submissions with at least 85% sameness then it is considered a repost and removed
+
+### Remove reposted reddit submission
+
+* Type: **Check**
+* [Config](submissionRepost.yaml)
+
+Checks reddit for top posts with a **Title** that is 90% or more similar to the submission being checked and removes it, if found.
+
+## Self Promotion
+
+### Remove link submissions where the user's history is comprised of 10% or more of the same link
+
+* Type: **Check**
+* [Config](selfPromo.yaml)
+
+If the link origin (youtube author, twitter author, etc. or regular domain for non-media links)
+
+* comprises 10% or more of the users **entire** history in the past (100 activities or 6 months)
+* or comprises 10% or more of the users **submission** history in the past (100 activities or 6 months) and the user has low engagement (<50% of history is comments or 40%> of comment are as OP)
+
+then remove the submission
+
+### Remove submissions posted in 'newtube' subreddits
+
+* Type: **Check**
+* [Config](newtube.yaml)
+
+If the user makes the same submission to a 'newtube' or self-promotional subreddit it is removed and a modnote is added.
+
+## Safety
+
+### Remove comments on brigaded submissions when user has no history
+
+* Type: **Check**
+* [Config](brigadingNoHistory.yaml)
+
+The users of comments on a brigaded submission (based on a special submission flair) have their comment history checked -- if they have no participation in your subreddit then the comment is removed.
+
+### Remove submissions from users with a history of sex solicitation 
+
+* Type: **Check**
+* [Config](sexSolicitationHistory.yaml)
+
+If the author of a submission has submissions in their history that match common reddit "sex solicitation" tags (MFA, R4F, M4F, etc...) the submission is removed and a modnote added.
+
+This is particularly useful for subreddits with underage audiences or mentally/emotionally vulnerable groups. 
+
+The check can be modified to removed comments by changing `kind: submission` to `kind: comment`
+
+## Verification
+
+### Verify users from r/TranscribersOfReddit
+
+* Type: **Check**
+* [Config](transcribersOfReddit.yaml)
+
+[r/TranscribersOfReddit](https://www.reddit.com/r/transcribersofreddit) is a community of volunteers transcribing images and videos, across reddit, into plain text.
+
+This Check detects their standard transcription template and also checks they have a history in r/transcribersofreddit -- then approves the comment and flairs the user with **Transcriber ✍️**
+
+### Require submission authors have prior subreddit participation
+
+* Type: **Check**
+* [Config](requireNonOPParticipation.yaml)
+
+Submission is removed if the author has **less than 5 non-OP comments** in your subreddit prior to making the submission.
+
+### Require submission authors make a top-level comment with 15 minutes of posting
+
+* Type: **Check**
+* [Config](requireNonOPParticipation.yaml)
+
+After making a submission the author must make a top-level comment with a regex-checkable pattern within X minutes. If the comment is not made the submission is removed.
+
+# Monitoring
+
+### Sticky a comment on popular submissions
+
+* Type: **Run**
+* [Config](popularSubmissionMonitoring.yaml)
+
+This **Run** should come after any other Runs you have that may remove a Submission.
+
+The Run will cause CM to check new submissions for 3 hours at a 10 minute interval. The bot will then make a comment and sticky it WHEN it detects the number of upvotes is abnormal for how long the Submission has been "alive".

docs/subreddit-configuration/cookbook/brigadingNoHistory.yaml

@@ -0,0 +1,44 @@
+#polling:
+#  - newComm
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      #
+      # Report comments from users with no history in the subreddit IF the submission is flaired as being brigaded
+      # optionally, remove comment
+      #
+      - name: Brigading No History
+        kind: comment
+        # only runs on comments in a submission with a link flair css class of 'brigaded'
+        itemIs:
+          - submissionState:
+              # can use any or all of these to detect brigaded submission
+              - link_flair_css: brigaded
+                #flairTemplate: 123-1234
+                #link_flair_text: Restricted
+        rules:
+          - name: noHistory
+            kind: recentActivity
+            # check last 100 activities that have not been removed
+            window:
+              count: 100
+              filterOn:
+                post:
+                  commentState:
+                    include:
+                      - removed: false
+            thresholds:
+              # triggers if user has only one activity (this one) in your subreddit
+              - subreddits:
+                  - MYSUBREDDIT
+                threshold: '<= 1'
+        actions:
+          - kind: report
+            enable: true
+            content: User has no history in subreddit
+
+          - kind: remove
+            enable: false
+            note: User has no history in subreddit

docs/subreddit-configuration/cookbook/chatSpam.yaml

@@ -0,0 +1,58 @@
+#polling:
+#  - newComm
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      #
+      # Remove comments from users who spam discord and telegram links
+      # -- differs from just using automod:
+      # 1) removes comment if it is ONLY discord/telegram link
+      # 2) if not *only* link then checks user's history to see if link is spammed many times and only removes if it is
+      #
+      - name: ban chat only spammer
+        description: ban a user who spams only a chat link many times historically
+        kind: comment
+        condition: AND
+        rules:
+          - linkOnlySpam
+          - linkAnywhereHistoricalSpam
+        actions:
+          - kind: remove
+          - kind: ban
+            content: spamming discord links
+      - name: remove chat spam
+        description: >-
+          remove comments from users who only link to chat or mention chat
+          link many times historically
+        kind: comment
+        condition: OR
+        rules:
+          - name: linkOnlySpam
+            kind: regex
+            criteria:
+              - name: only link
+                # https://regexr.com/70j9m
+                # single quotes are required to escape special characters
+                regex: '/^\s*((?:discord\.gg|t\.me|telegram\.me|telegr\.im)\/[\w\d]+)\s*$/i'
+          - condition: AND
+            rules:
+              - name: linkAnywhereSpam
+                kind: regex
+                criteria:
+                  - name: contains link anywhere
+                    # single quotes are required to escape special characters
+                    regex: '/((?:discord\.gg|t\.me|telegram\.me|telegr\.im)\/[\w\d]+)/i'
+              - name: linkAnywhereHistoricalSpam
+                kind: regex
+                criteria:
+                  - name: contains links anywhere historically
+                    # single quotes are required to escape special characters
+                    regex: '/((?:discord\.gg|t\.me|telegram\.me|telegr\.im)\/[\w\d]+)/i'
+                    totalMatchThreshold: '>= 3'
+                    lookAt: comments
+                    window: 100
+        actions:
+          - kind: remove
+            note: Chat spam link

docs/subreddit-configuration/cookbook/commentBasedSubmissionVerification.yaml

@@ -0,0 +1,71 @@
+#polling:
+#  - newSub
+#  - newComm
+#runs:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a series of RUNS
+  - name: approvals
+    checks:
+        - name: approveSubmissionOnComment
+          description: Approve an unapproved submission when OP comments with the magic words
+          kind: comment
+          itemIs:
+             # only check comment if submission is not approved and this comment is by OP
+            - submissionState:
+                - approved: false
+              op: true
+          rules:
+            - name: OPMagic
+              kind: regex
+              criteria:
+                # YOU NEED TO EDIT THIS REGEX TO MATCH THE PATTERN THE OP'S COMMENT SHOULD HAVE IN ORDER TO VERIFY THE SUBMISSION
+                - regex: '/Say Please/i'
+          actions:
+            - kind: approve
+              targets:
+                - parent
+                - self
+              # cancel any delayed dispatched actions
+            - kind: cancelDispatch
+              # tell action to look for delayed items matched parent (submission)
+              target: parent
+              # submission must have 'subVerification' identifier
+              identifier: subVerification
+
+  - name: verification
+    checks:
+      - name: waitForVerification
+        description: Delay processing this submission for 15 minutes
+        kind: submission
+        itemIs:
+          # only dispatch if this is the first time we are seeing this submission
+          - source:
+              - "poll:newSub"
+              - user
+        actions:
+          - kind: dispatch
+            target: self
+            # unique identifier which is a nice hint in the UI and also allows targeting this item while it is delayed
+            identifier: subVerification
+            delay: "15 minutes"
+            # when it is reprocessed go directly to the 'verification' run, skipping everything else
+            goto: verification
+
+      - name: removeNoVerification
+        description: Remove submission if it is not verified after delay
+        kind: submission
+        itemIs:
+          # only process this submission if it comes dispatch with 'subVerification' identifier and is NOT approved after 15 minutes
+          - source: "dispatch:subVerification"
+            approved: false
+        actions:
+          # if this submission is being processed it has been 5 minutes and was not cancelled by OF comment
+          - kind: remove
+            enable: true
+
+          - kind: comment
+            enable: true
+            lock: true
+            distinguish: true
+            content: 'Your submission has been removed because you did not follow verification instructions within 15 minutes of posting.'

docs/subreddit-configuration/cookbook/commentRepost.yaml

@@ -0,0 +1,54 @@
+#polling:
+#  - newComm
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # Checks top-level comments on submissions younger than 30 minutes:
+        # * Finds other reddit submissions based on crosspost/duplicates/title/URL, takes top 10 submissions based # of upvotes
+        #   * If this comment matches any comments from those other submissions with at least 85% sameness then it is considered repost
+        #
+        # optionally, bans user if they have more than one modnote for comment reposts
+        #
+      - name: commRepost
+        description: Check if comment has been reposted from youtube
+        kind: comment
+        itemIs:
+          - removed: false
+            approved: false
+            op: false
+            # top level comments only
+            depth: '< 1'
+            submissionState:
+              - age: '< 30 minutes'
+        condition: AND
+        rules:
+          - name: commRepost
+            kind: repost
+            criteria:
+              - searchOn:
+                  - external
+        actions:
+          - kind: remove
+            spam: true
+            note: 'reposted comment from reddit with {{rules.commrepost.closestSameness}}% sameness'
+
+          - kind: ban
+            authorIs:
+              # if the author has more than one spamwatch usernote then just ban em
+              include:
+                - modActions:
+                    - noteType: SPAM_WATCH
+                      note: "/comment repost.*/i"
+                      search: total
+                      count: "> 1"
+            message: You have been banned for repeated spammy behavior including reposting reddit comments
+            note: reddit comment repost + spammy behavior
+            reason: reddit comment repost + spammy behavior
+
+          - name: commRepostModNote
+            kind: modnote
+            content: 'YT comment repost with {{rules.commrepost.closestSameness}}% sameness'
+            type: SPAM_WATCH

docs/subreddit-configuration/cookbook/commentSpam.yaml

@@ -0,0 +1,32 @@
+#polling:
+#  - newComm
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      #
+      # Remove comments by users who spam the same comment many times
+      #
+      - name: low xp comment spam
+        description: X-posted comment >=4x
+        kind: comment
+        rules:
+          - name: xPostLowComm
+            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: 100
+              duration: 6 months
+        actions:
+          - kind: report
+            enable: false
+            content: 'Remove => Posted same comment {{rules.xpostlowcomm.largestRepeat}}x times'
+
+          - kind: remove
+            enable: true
+            note: 'Posted same comment {{rules.xpostlowcomm.largestRepeat}}x times'

docs/subreddit-configuration/cookbook/crosspostSpam.yaml

@@ -0,0 +1,56 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      #
+      #   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: 100
+              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: false
+            content: >-
+              Remove=>{{rules.xpostlow.largestRepeat}} X-P =>
+              {{rules.loworopcomm.thresholdSummary}}
+
+          - kind: remove
+            enable: true
+            note: 'Repeated submission {{rules.xpostlow.largestRepeat}}x and low comment engagement'
+
+          - 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/subreddit-configuration/cookbook/diametricSpam.yaml

@@ -0,0 +1,34 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      - name: diametricSpam
+        description: Check if author has posted the same image in opposite subs
+        kind: submission
+        rules:
+          - name: recent
+            kind: recentActivity
+            useSubmissionAsReference: true
+            # requires your subreddit to be running on a CM instance that supports image processing
+            imageDetection:
+              enable: true
+            threshold: 5
+            lookAt: submissions
+            window: 30
+            thresholds:
+              - threshold: ">= 1"
+                subreddits:
+                  - AnotherSubreddit
+            actions:
+              - kind: remove
+                enable: true
+                content: "Posted same image in {{rules.recent.subSummary}}"
+
+              - kind: comment
+                distinguish: true
+                sticky: true
+                lock: true
+                content: 'You have posted the same image in another subreddit ({{rules.recent.subSummary}}) that does not make sense given the theme of this subreddit. We consider this spam and it has been removed.'

docs/subreddit-configuration/cookbook/floodingNewSubmissions.yaml

@@ -0,0 +1,34 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # Add a mote note to users who are making more than 4 submissions a day
+        # and optionally remove new submissions by them
+        #
+      - name: Flooding New
+        description: Detect users make more than 4 submission in 24 hours
+        kind: submission
+        rules:
+          - name: Recent In Sub
+            kind: recentActivity
+            useSubmissionAsReference: false
+            window:
+              duration: 24 hours
+              fetch: submissions
+            thresholds:
+              - subreddits:
+                  # change this to your subreddit
+                  - MYSUBREDDIT
+                threshold: "> 4"
+        actions:
+          - kind: modnote
+            type: SPAM_WATCH
+            content: '{{rules.recentinsub.totalCount}} submissions in the last 24 hours'
+
+          - kind: remove
+            enable: false
+            note: '{{rules.recentinsub.totalCount}} submissions in the last 24 hours'

docs/subreddit-configuration/cookbook/freekarma.yaml

@@ -0,0 +1,45 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      #
+      # Remove submissions from users who have recent activity in freekarma subs in the last 100 activities
+      #
+      - name: freekarma removal
+        description: Remove submission if user has used freekarma sub recently
+        kind: submission
+        rules:
+          - name: freekarma
+            kind: recentActivity
+            window: 100
+            useSubmissionAsReference: false
+            thresholds:
+              - subreddits:
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - freekarmaforyou
+                  - KarmaFarming4Pros
+                  - KarmaStore
+                  - upvote
+                  - promote
+                  - shamelessplug
+                  - upvote
+                  - FreeUpVotes
+                  - GiveMeKarma
+                  - nsfwkarma
+                  - GetFreeKarmaAnyTime
+                  - freekarma2021
+                  - FreeKarma2022
+                  - KarmaRocket
+                  - FREEKARMA4PORN
+        actions:
+          - kind: report
+            enable: false
+            content: 'Remove => {{rules.freekarma.totalCount}} activities in freekarma subs'
+
+          - kind: remove
+            enable: true
+            note: '{{rules.freekarma.totalCount}} activities in freekarma subs'

docs/subreddit-configuration/cookbook/newtube.yaml

@@ -0,0 +1,55 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # Add a mote note to users who make a submission that is also posted to a 'newtube' subreddit
+        # and optionally remove new submission
+        #
+      - name: Newtube Submission
+        description: Tag user if submission was posted in 'newtube' subreddit
+        kind: submission
+        rules:
+          - name: newTube
+            kind: recentActivity
+            window:
+              count: 100
+              fetch: submissions
+            thresholds:
+              - subreddits:
+                  - AdvertiseYourVideos
+                  - BrandNewTube
+                  - FreeKarma4U
+                  - FreeKarma4You
+                  - KarmaStore
+                  - GetMoreSubsYT
+                  - GetMoreViewsYT
+                  - NewTubers
+                  - promote
+                  - PromoteGamingVideos
+                  - shamelessplug
+                  - SelfPromotionYouTube
+                  - SmallYTChannel
+                  - SmallYoutubers
+                  - upvote
+                  - youtubestartups
+                  - YouTube_startups
+                  - YoutubeSelfPromotions
+                  - YoutubeSelfPromotion
+                  - YouTubeSubscribeBoost
+                  - youtubepromotion
+                  - YTPromo
+                  - Youtubeviews
+                  - YouTube_startups
+        actions:
+          - name: newtubeModTag
+            kind: modnote
+            type: SPAM_WATCH
+            content: 'New Tube => {{rules.newtube.subSummary}}{{rules.newtubeall.subSummary}}'
+
+          - kind: remove
+            enable: false
+            note: 'New Tube => {{rules.newtube.subSummary}}{{rules.newtubeall.subSummary}}'

docs/subreddit-configuration/cookbook/popularSubmissionMonitoring.yaml

@@ -0,0 +1,89 @@
+polling:
+  - newSub
+
+runs:
+  - name: MyRegularRun
+    itemIs:
+      # regular run/checks should only run on new activities or if from dashboard
+      - source:
+          - 'poll:newSub'
+          - 'poll:newComm'
+          - 'user'
+    checks:
+      - name: RuleBreakingCheck1
+        kind: submission
+      # ...
+      #
+      # your regular checks go here
+      #
+      # assuming if a Submission makes it through all of your Checks then it is "OK"
+      # to be Approved or generally will be visible in the subreddit (valid for monitoring for r/All)
+      # -- at the end of the Run add a Dispath action
+      - name: Dispatch For Popular Monitoring
+        kind: submission
+        actions:
+          - kind: dispatch
+            identifier: 'popular'
+            # CM will wait 5 minutes before processing this submission again
+            delay: '5 minutes'
+            target: 'self'
+
+    # a separate run that only processes Submissions from dispatch:popular
+  - name: PopularWatch
+    itemIs:
+      - source: 'dispatch:popular'
+    checks:
+      # each check here looks at submission age and tests upvotes against what you think is probably r/All number of votes
+      # in descending age (oldest first)
+      # NOTE: You should change the 'age' and 'score' tests to fit the traffic volume for your subreddit!
+      - name: Two Hour Check
+        kind: submission
+        itemIs:
+          - age: '>= 2 hours'
+            score: '> 100'
+        actions:
+          - kind: comment
+            name: popularComment
+            content: 'Looks like this thread is getting a lot of attention. Greetings r/All! Please keep it civil.'
+            sticky: true
+            distinguish: true
+            lock: true
+
+      - name: One Hour Check
+        kind: submission
+        itemIs:
+          - age: '>= 1 hours'
+            score: '> 50'
+        actions:
+          - popularComment
+
+      - name: Thirty Minute Check
+        kind: submission
+        itemIs:
+          - age: '>= 30 minutes'
+            score: '> 25'
+        actions:
+          - popularComment
+
+      - name: Ten Minute Check
+        kind: submission
+        itemIs:
+          - age: '>= 10 minutes'
+            score: '> 10'
+        actions:
+          - popularComment
+
+      # finally, if none of the popular checks passed re-dispatch submission to be checked in another 10 minutes
+      - name: Delay Popular Check
+        kind: submission
+        postTrigger:
+          # don't need to add this Actioned Events
+          recordTo: false
+        itemIs:
+          # only monitor until submission is 3 hours old
+          - age: '<= 3 hours'
+        actions:
+          - kind: dispatch
+            identifier: 'popular'
+            delay: '10 minutes'
+            target: 'self'

docs/subreddit-configuration/cookbook/requireNonOPParticipation.yaml

@@ -0,0 +1,51 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # Report submissions by users with less than 5 non-OP comments in our subreddit
+        # and optionally remove the submission
+        #
+      - name: RequireEngagement
+        description: Remove submission if author has less than X non-op comments in our subreddit
+        kind: submission
+        rules:
+          - name: LittleEngagement
+            kind: recentActivity
+            lookAt: comments
+            useSubmissionAsReference: false
+            # bot will check the last 100 NON-OP comments from user's history
+            window:
+              count: 100
+              fetch: comments
+              filterOn:
+                post:
+                  commentState:
+                    - op: false
+            thresholds:
+                subreddits:
+                  - MYSUBREDDIT
+                # rule is "triggered" if there are LESS THAN 5 comments in our subreddit in the window specified (currently 100 non-op comments)
+                threshold: '< 5'
+
+        actions:
+
+          - kind: report # report the submission
+            enable: true
+            # the text of the report
+            content: 'User has <5 non-OP comments in last 100 comments'
+
+          - kind: remove # remove the submission
+            enable: false
+            note: 'User has <5 non-OP comments in last 100 comments'
+
+          - kind: comment # reply to submission with a comment
+            enable: false
+            # contents of the comment
+            content: We require users to have a minimum level of engagement (>5 comments on other people's posts) in our subreddit before making submissions. Your submission has been automatically removed.
+            sticky: true
+            distinguish: true
+            lock: true

docs/subreddit-configuration/cookbook/selfPromo.yaml

@@ -0,0 +1,77 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      #
+      # 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: true
+            note: '>10% of author's history is content from this creator'
+
+          - 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

docs/subreddit-configuration/cookbook/sexSolicitationHistory.yaml

@@ -0,0 +1,33 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # Remove submission if user has any "redditor for [sex]..." submissions in their history
+        # and optionally bans user
+        #
+      - name: sexSpamHistory
+        description: Detect sex spam language in recent history and ban if found (most likely a bot)
+        kind: submission
+        rules:
+          - kind: regex
+            name: redditorFor
+            criteria:
+              # matches if text has common "looking for" acronym like F4M R4A etc...
+              - regex: '/[RFM]4[a-zA-Z\s0-9]/i'
+                totalMatchThreshold: "> 1"
+                window: 100
+                testOn:
+                  - body
+                  - title
+        actions:
+          - kind: remove
+            enable: true
+            note: 'Has sex solicitation submission history: {{rules.redditorfor.matchSample}}'
+
+          - kind: modnote
+            type: ABUSE_WARNING
+            content: 'Has sex solicitation submission history: {{rules.redditorfor.matchSample}}'

docs/subreddit-configuration/cookbook/submissionRepost.yaml

@@ -0,0 +1,31 @@
+#polling:
+#  - newSub
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+      - name: BotRepost
+        description: Remove submission if it is likely a repost
+        kind: submission
+        rules:
+          # search reddit for similar submissions to see if it is a repost
+          - name: subRepost
+            kind: repost
+            criteria:
+              - searchOn:
+                  # match found Submissions sameness using title against title of Submission being checked
+                  - kind: title
+                    # sameness (confidence) % of a title required to consider Submission being checked as a repost
+                    matchScore: 90
+
+        actions:
+          # report the submission
+          - kind: report
+            enable: true
+            content: '{{rules.subrepost.closestSameness}} confidence this is a repost.'
+
+          # remove the submission
+          - kind: remove
+            enable: false
+            note: '{{rules.subrepost.closestSameness}} confidence this is a repost.'

docs/subreddit-configuration/cookbook/transcribersOfReddit.yaml

@@ -0,0 +1,41 @@
+#polling:
+#  - newComm
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # Detect top-level comments by users from r/transcribersofreddit
+        # and approve/flair the user
+        #
+      - name: transcriber comment
+        description: approve/flair transcribed video comment
+        kind: comment
+        itemIs:
+          # top-level comments
+          depth: '< 1'
+        condition: AND
+        rules:
+          - name: transcribedVideoFormat
+            kind: regex
+            criteria:
+              - regex: '/^[\n\r\s]*\*Video Transcription\*[\n\r]+---[\S\s]+---/gim'
+          - name: transcribersActivity
+            kind: recentActivity
+            window:
+              count: 100
+              duration: 1 week
+            useSubmissionAsReference: false
+            thresholds:
+              - subreddits:
+                  - transcribersofreddit
+        actions:
+          - kind: approve
+          - name: flairTranscriber
+            kind: flair
+            authorIs:
+              exclude:
+                - flairText:
+                    - Transcriber ✍️
+            text: Transcriber ✍️

docs/subreddit-configuration/cookbook/youtubeCommentRepost.yaml

@@ -0,0 +1,47 @@
+#polling:
+#  - newComm
+#runs:
+#  - checks:
+#### Uncomment the code above to use this as a FULL subreddit config
+####
+#### Otherwise copy-paste the code below to use as a CHECK
+        #
+        # If submission type is a youtube video CM will check top comments on the video and remove comment if it at least 85% the same
+        # optionally, bans user if they have more than one modnote for comment reposts
+        #
+      - name: commRepostYT
+        description: Check if comment has been reposted from youtube
+        kind: comment
+        itemIs:
+          - removed: false
+            approved: false
+            op: false
+        condition: AND
+        rules:
+          - name: commRepost
+            kind: repost
+            criteria:
+              - searchOn:
+                  - external
+        actions:
+          - kind: remove
+            spam: true
+            note: 'reposted comment from youtube with {{rules.commrepostyt.closestSameness}}% sameness'
+
+          - kind: ban
+            authorIs:
+              # if the author has more than one spamwatch usernote then just ban em
+              include:
+                - modActions:
+                    - noteType: SPAM_WATCH
+                      note: "/comment repost.*/i"
+                      search: total
+                      count: "> 1"
+            message: You have been banned for repeated spammy behavior including reposting youtube comments
+            note: yt comment repost + spammy behavior
+            reason: yt comment repost + spammy behavior
+
+          - name: commRepostYTModNote
+            kind: modnote
+            content: 'YT comment repost with {{rules.commrepostyt.closestSameness}}% sameness'
+            type: SPAM_WATCH

docs/subreddit-configuration/imageComparison.md

@@ -0,0 +1,243 @@
+---
+title: Image Comparison
+parent: Subreddit Configuration
+---
+
+# 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](in-depth/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
+imageDetection:
+  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
+```

docs/subreddit-configuration/in-depth/README.md

@@ -0,0 +1,9 @@
+---
+parent: Subreddit Configuration
+has_children: true
+has_toc: true
+---
+
+# In Depth
+
+Further details and examples for CM components.

docs/subreddit-configuration/in-depth/attribution/README.md

@@ -0,0 +1,36 @@
+---
+grand_parent: Subreddit Configuration
+parent: In Depth
+---
+
+# Attribution Rule
+
+The **Attribution** rule will aggregate an Author's content Attribution (youtube channels, twitter, website domains, etc.) and can check on their totals or percentages of all Activities over a time period:
+* Total # of attributions 
+* As percentage of all Activity or only Submissions
+* Look at all domains or only media (youtube, vimeo, etc.)
+* Include self posts (by reddit domain) or not
+
+Consult the [schema](https://json-schema.app/view/%23/%23%2Fdefinitions%2FCheckJson/%23%2Fdefinitions%2FAttributionJSONConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) for a complete reference of the rule's properties.
+
+# [Template Variables](../../actionTemplating.md)
+
+|          Name          |                                                                      Description                                                                       |                                          Example                                          |
+|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
+| `result`               | Summary of rule results (also found in Actioned Events)                                                                                                | 1 Attribution(s) met the threshold of >= 20%, with 6 (40%) of 15 Total -- window: 3 years |
+| `triggeredDomainCount` | Number of domains that met the threshold                                                                                                               | 1                                                                                         |
+| `window`               | Number or duration of Activities considered from window                                                                                                | 3 years                                                                                   |
+| `largestCount`         | The count from the largest aggregated domain                                                                                                           | 6                                                                                         |
+| `largestPercentage`    | The percentage of Activities the largest aggregated domain comprises                                                                                   | 40%                                                                                       |
+| `smallestCount`        | The count from the smallest aggregated domain                                                                                                          | 1                                                                                         |
+| `smallestPercentage`   | The percentage of Activities the smallest aggregated domain comprises                                                                                  | 6%                                                                                        |
+| `countRange`           | A convenience string displaying "smallestCount - largestCount" or just one number if both are the same                                                 | 5                                                                                         |
+| `percentRange`         | A convenience string displaying "smallestPercentage - largestPercentage" or just one percentage if both are the same                                   | 34%                                                                                       |
+| `domainsDelim`         | A comma-delimited list of all the domain URLs that met the threshold                                                                                   | youtube.com/example1, youtube.com/example2, rueters.com                                   |
+| `titlesDelim`          | A comma-delimited list of friendly-names of the domain if one is present, otherwise the URL (IE youtube.com/c/34ldfa343 => "My Youtube Channel Title") | My Channel A, My Channel B, reuters.com                                                   |
+| `threshold`            | The threshold you configured for this Rule to trigger                                                                                                  | `>= 20%`                                                                                  |
+
+# Examples
+
+* Self Promotion as percentage of all Activities [YAML](redditSelfPromoAll.yaml) | [JSON](redditSelfPromoAll.json5) - Check if Author is submitting much more than they comment.
+* Self Promotion as percentage of Submissions [YAML](redditSelfPromoSubmissionsOnly.yaml) | [JSON](redditSelfPromoSubmissionsOnly.json5) - Check if any of Author's aggregated submission origins are >10% of their submissions

docs/subreddit-configuration/in-depth/attribution/redditSelfPromoAll.json5

@@ -0,0 +1,43 @@
+{
+  "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 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
+                }
+              ],
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr10all.largestPercent}}% of {{rules.attr10all.activityTotal}} items over {{rules.attr10all.window}}"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

docs/subreddit-configuration/in-depth/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/subreddit-configuration/in-depth/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/subreddit-configuration/in-depth/attribution/redditSelfPromoSubmissionsOnly.json5

@@ -0,0 +1,44 @@
+{
+  "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 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
+                }
+              ],
+            }
+          ],
+          "actions": [
+            {
+              "kind": "report",
+              "content": "{{rules.attr10sub.largestPercent}}% of {{rules.attr10sub.activityTotal}} items over {{rules.attr10sub.window}}"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

docs/subreddit-configuration/in-depth/author/README.md

@@ -0,0 +1,53 @@
+---
+grand_parent: Subreddit Configuration
+parent: In Depth
+---
+
+# Author
+
+## Rule
+
+The **Author** rule triggers if any [AuthorCriteria](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorCriteria?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) from a list are either **included** or **excluded**, depending on which property you put them in.
+
+**AuthorCriteria** that can be checked:
+* name (u/userName)
+* author's subreddit flair text
+* author's subreddit flair css
+* author's subreddit mod status
+* [Toolbox User Notes](../userNotes)
+
+The Author **Rule** is best used in conjunction with other Rules to short-circuit a Check based on who the Author is. It is easier to use a Rule to do this then to write **author filters** for every Rule (and makes Rules more re-useable).
+
+Consult the [schema](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorRuleJSONConfig?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
+
+* Basic examples
+    * Flair new user Submission [YAML](flairNewUserSubmission.yaml) | [JSON](flairNewUserSubmission.json5) - If the Author does not have the `vet` flair then flair the Submission with `New User`
+    * Flair vetted user Submission [YAML](flairNewUserSubmission.yaml) | [JSON](flairNewUserSubmission.json5) - If the Author does have the `vet` flair then flair the Submission with `Vetted`
+* Used with other Rules
+    * Ignore vetted user [YAML](flairNewUserSubmission.yaml) | [JSON](flairNewUserSubmission.json5) - Short-circuit the Check if the Author has the `vet` flair
+    
+## Filter
+
+All **Rules** and **Checks** have an optional `authorIs` property that takes an [AuthorOptions](https://json-schema.app/view/%23%2Fdefinitions%2FAuthorOptions?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fcontext-mod%2Fmaster%2Fsrc%2FSchema%2FApp.json) object. 
+
+**This property works the same as the Author Rule except that:**
+* On **Rules** if all criteria fail the Rule is **skipped.** 
+  * If a Rule is skipped **it does not fail or pass** and so does not affect the outcome of the Check.
+  * However, if all Rules on a Check are skipped the Check will fail.
+* On **Checks** if all criteria fail the Check **fails**.
+
+### Examples
+
+* Skip recent activity check based on author [YAML](authorFilter.yaml) | [JSON](authorFilter.json5) - Skip a Recent Activity check for a set of subreddits if the Author of the Submission has any set of flairs.
+
+## 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](onlyfansFlair.yaml) | [JSON](onlyfansFlair.json5) - Check whether submitter has typical OF keywords in their profile and flair both author + submission accordingly.

docs/subreddit-configuration/in-depth/author/authorFilter.json5

@@ -0,0 +1,73 @@
+{
+  "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/subreddit-configuration/in-depth/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/subreddit-configuration/in-depth/author/flairNewUserSubmission.json5

@@ -0,0 +1,33 @@
+{
+  "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/subreddit-configuration/in-depth/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/subreddit-configuration/in-depth/author/flairVettedUserSubmission.json5

@@ -0,0 +1,33 @@
+{
+  "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/subreddit-configuration/in-depth/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/subreddit-configuration/in-depth/author/ignoreVettedUser.json5

@@ -0,0 +1,79 @@
+{
+  "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"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}