README: motivation and capabilities

README.md

@@ -17,12 +17,23 @@ objects, so the secret stays reachable by its SHA. Revenant is built to find tho
 
 Built and maintained by [smakarim](https://github.com/smakarim).
 
-## Why
+## Why Revenant exists
 
-TruffleHog, Gitleaks, and GitHound scan the current state of repositories you already know
-about. The deleted and force-pushed surface, where credentials get "removed" and forgotten,
-is not covered by those tools. Revenant targets that surface and folds the ordinary history
-scan into the same run, so you do not have to stitch several tools together.
+Secrets get committed by accident constantly. The usual reaction is to delete the offending
+commit, or force-push over it, and rotate the key "later." That is not enough. GitHub keeps the
+underlying commit objects, so a deleted or rewritten commit stays reachable by its SHA, and the
+secret stays valid until the credential is actually rotated. Deleting is not remediation.
+
+Standard secret scanners (TruffleHog, Gitleaks, GitHound) look at the current state of the
+repositories you already point them at. The higher-value surface goes unscanned: secrets in
+deleted and force-pushed commits, in gists, and in unrelated repositories scattered across all
+of GitHub. Covering that surface today means stitching several narrow tools together by hand.
+
+Revenant exists to cover it in one place. It recovers commits that are no longer reachable from
+any branch, scans current history and gists, searches all of GitHub for a target's leaks,
+confirms which secrets are still live, attributes each to the developer who committed it, and
+ranks findings by blast radius. In testing against public GitHub it surfaced live database
+credentials in unrelated repositories within seconds.
 
 ## How Revenant compares
 
@@ -49,21 +60,30 @@ on their own. The table reflects each tool's documented, out-of-the-box behavior
    deleted commits, gists, and code-search dorking in one pass, deduplicated, attributed to the
    author, and ranked.
 
-## Features
-
-- Scans reachable history, deleted and force-pushed commits, and gists in one run. Every
-  finding carries a SOURCE tag (history, deleted, gist, or dork).
-- Discovers a wider footprint: a user's gists by default, and with `--members` an org's
-  members along with their personal repos and gists.
-- GitHub-wide dorking (`--dork`) searches all of GitHub with a code-search dork corpus and
-  scans each matching file. A custom dork file and a domain term are supported.
-- Live-key intelligence (`--analyze`) reports a verified GitHub token's identity and scopes,
-  so you know what the key can actually do.
-- Verifies each secret with TruffleHog and caches the result, so a repeated secret is checked
-  once.
-- Attributes every finding to org, repo, commit, and author, with first and last seen.
-- Ranks findings by a transparent score based on verified status, secret type, and spread.
-- Handles GitHub rate limits with adaptive backoff and rotation across multiple tokens.
+## What it can do
+
+Point Revenant at an organization, a user, or a list of repositories, and in a single run it
+will:
+
+- **Recover deleted work.** Find commits force-pushed or deleted out of history and scan them
+  for secrets, using the repository activity log so it is immediate and does not brute-force
+  commit hashes.
+- **Scan the whole footprint.** Cover each repository's current history and public gists, and
+  with `--members` enumerate an organization's members and fold in their personal repos and
+  gists.
+- **Search all of GitHub.** With `--dork`, run a code-search dork corpus across GitHub for the
+  target's leaks and scan every matching file (`--domain`, `--dork-file`, and `--dork-max`
+  refine it).
+- **Confirm what is live.** Verify each finding with TruffleHog so you see which secrets are
+  actually active, not just present; `--verified-only` shows only the live ones.
+- **Measure the blast radius.** With `--analyze`, report what a verified GitHub token can do
+  (its identity and scopes), and rank every finding by a transparent score.
+- **Attribute and deduplicate.** Tie each finding to org, repo, commit, and author with
+  first/last seen, collapse duplicates, and tag each result by `SOURCE` (history, deleted,
+  gist, or dork). Output is a ranked table or JSON.
+
+It is built for real targets: scanning runs concurrently (`--concurrency`), rotates across
+multiple tokens, and backs off on GitHub rate limits.
 
 ## Install