diff --git a/.gitignore b/.gitignore
index f3cda28..69b460e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,22 @@
-go.sum
-.DS_Store
\ No newline at end of file
+.DS_Store
+.idea
+*.iml
+
+vendor/*
+bin/*
+dist/*
+# Yaegi / Traefik local-plugin runtime work directory.
+plugins-local/*
+
+# Go coverage directories (GOCOVERDIR)
+.cover/
+coverage.out
+coverage.txt
+*.cover.out
+*_coverage.out
+unit.out
+int.out
+nohup.out
+
+*.test
+*.exe
diff --git a/README.md b/README.md
index 88e7d55..cc5cef6 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,13 @@
 # Pangolin Middleware: Badger
 
+[![GitHub Release](https://img.shields.io/github/release/fosrl/badger?sort=semver)](https://github.com/fosrl/badger/releases)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/fosrl/badger)](https://github.com/fosrl/badger/blob/main/go.mod)
+[![CI](https://github.com/fosrl/badger/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fosrl/badger/actions/workflows/ci.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/fosrl/badger)](https://goreportcard.com/report/github.com/fosrl/badger)
+[![License](https://img.shields.io/github/license/fosrl/badger)](https://github.com/fosrl/badger/blob/main/LICENSE)
+[![Traefik Plugin](https://img.shields.io/badge/Traefik-Plugin-24A1C1)](https://plugins.traefik.io/)
+[![Pangolin](https://img.shields.io/badge/Pangolin-Middleware-blue)](https://github.com/fosrl/pangolin)
+
 Badger is a middleware plugin designed to work with Traefik in conjunction with [Pangolin](https://github.com/fosrl/pangolin), an identity-aware reverse proxy and zero-trust VPN. Badger acts as an authentication bouncer, ensuring only authenticated and authorized requests are allowed through the proxy.
 
 > [!NOTE]
@@ -7,6 +15,32 @@ Badger is a middleware plugin designed to work with Traefik in conjunction with
 
 This plugin is **required** to be installed alongside [Pangolin](https://github.com/fosrl/pangolin) to enforce secure authentication and session management.
 
+## What Badger does
+
+Badger runs as a Traefik middleware in front of protected services.
+
+For each request, Badger can:
+
+1. determine the real client IP from Cloudflare or a trusted upstream proxy,
+2. normalize `X-Real-IP` and `X-Forwarded-For` for downstream services,
+3. call the Pangolin API to verify authentication and resource access,
+4. allow, block, or redirect the request based on the verification result.
+
+## Modes
+
+### Pangolin authentication mode
+
+This is the default mode. Badger validates incoming requests against the
+Pangolin API before forwarding them to the upstream service.
+
+### IP handling only mode
+
+Set `disableForwardAuth: true` to disable Pangolin authentication and only use
+Badger for real-client-IP handling.
+
+Use this only when authentication is handled elsewhere or when you explicitly
+want Badger to act only as an IP normalization middleware.
+
 ## Installation
 
 Badger is automatically installed with Pangolin. Learn how to install Pangolin in the [Pangolin Documentation](https://docs.pangolin.net/self-host/quick-install).