From 248525715334678891109b8cf730e979fcf494b7 Mon Sep 17 00:00:00 2001
From: WeebDataHoarder <57538841+WeebDataHoarder@users.noreply.github.com>
Date: Sun, 13 Apr 2025 13:28:54 +0200
Subject: [PATCH] Add overview at the top of README

---
 README.md | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 7b8ac49..f57b64d 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,19 @@
 # go-away
 
-Self-hosted abuse detection and rule enforcement against low-effort mass AI scraping and bots.
+Self-hosted abuse detection and rule enforcement against low-effort mass AI scraping and bots. 
 
 [![Build Status](https://ci.gammaspectra.live/api/badges/git/go-away/status.svg)](https://ci.gammaspectra.live/git/go-away)
 [![Go Reference](https://pkg.go.dev/badge/git.gammaspectra.live/git/go-away.svg)](https://pkg.go.dev/git.gammaspectra.live/git/go-away)
 
-This documentation is a work in progress. For now, see policy examples under [examples/](examples/).
+go-away sits in between your site and the Internet / upstream proxy.
 
-This Go package can be used as a command on `git.gammaspectra.live/git/go-away/cmd/go-away` or a library under `git.gammaspectra.live/git/go-away/lib`
+Incoming requests can be selected by [rules](#rich-rule-matching) to be [actioned](#extended-rule-actions) or [challenged](#challenges) to filter suspicious requests.
 
+The tool is designed highly flexible so the operator can minimize impact to legit users, while surgically targeting heavy endpoints or scrapers.
+
+[Challenges](#challenges) can be transparent (not shown to user, depends on backend or other logic), [non-JavaScript](#non-javascript-challenges) (challenges common browser properties), or [custom JavaScript](#custom-javascript--wasm-challenges) (from Proof of Work to fingerprinting or Captcha is supported)
+
+See _[Why?](#why)_ section for the challenges and reasoning behind this tool.
 
 ## Support
 
@@ -101,7 +106,7 @@ These can be used for light checking of requests that eliminate most of the low
 
 See [Challenges](#challenges) below for a list of them.
 
-### Custom proof-of-work JS / WASM challenges
+### Custom JavaScript / WASM challenges
 
 A WASM interface for server-side proof generation and checking is offered. We provide `js-pow-sha256` as an example of one.
 
@@ -473,6 +478,8 @@ Example:
 
 ## Development
 
+This Go package can be used as a command on `git.gammaspectra.live/git/go-away/cmd/go-away` or a library under `git.gammaspectra.live/git/go-away/lib`
+
 ### Compiling WASM runtime challenge modules
 
 Custom WASM runtime modules follow the WASI `wasip1` preview syscall API.