GeiserX · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/GeiserX/Wayback-Diff/main/docs/images/banner.svg" alt="Wayback-Diff Banner" width="900"/>
+  <img src="https://raw.githubusercontent.com/GeiserX/Wayback-Diff/main/docs/images/banner.svg" alt="Wayback-Diff banner" width="900"/>
 </p>
 
 <p align="center">
@@ -10,7 +10,7 @@
   <a href="https://pypi.org/project/wayback-diff/"><img src="https://img.shields.io/pypi/v/wayback-diff?style=flat-square" alt="PyPI"></a>
   <a href="https://github.com/GeiserX/Wayback-Diff/releases/latest"><img src="https://img.shields.io/github/v/release/GeiserX/Wayback-Diff?color=orange" alt="Version"/></a>
   <a href="https://github.com/GeiserX/Wayback-Diff/actions/workflows/main.yml"><img src="https://github.com/GeiserX/Wayback-Diff/actions/workflows/main.yml/badge.svg" alt="CI"/></a>
-  <a href="https://github.com/GeiserX/Wayback-Diff/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-green" alt="License: GPL-3.0"/></a>
+  <a href="https://github.com/GeiserX/Wayback-Diff/blob/main/LICENSE"><img src="https://img.shields.io/github/license/GeiserX/Wayback-Diff" alt="License"/></a>
   <a href="https://codecov.io/gh/GeiserX/Wayback-Diff"><img src="https://codecov.io/gh/GeiserX/Wayback-Diff/graph/badge.svg" alt="codecov"/></a>
 </p>
 
@@ -21,7 +21,7 @@ Comparing web pages gets hard once Wayback Machine injections, whitespace noise
 - Strips Wayback Machine banners, analytics and playback scripts, and URL rewrites, so you compare the real content.
 - Tags every change High, Medium or Low.
 - Screenshots in Chrome, Firefox, Edge and Opera, with side-by-side and pixel-diff images (`--visual`).
-- Site-wide crawl and compare with `--traverse --depth N`.
+- Site-wide crawl and compare with `--traverse --max-depth N`.
 - Text, JSON and unified diff output, plus Markdown reports (`--markdown`).
 - CI exit codes: `0` no changes, `1` low or medium, `2` high.
 - Installs from PyPI, from source or as a Docker image.
@@ -33,19 +33,16 @@ pip install wayback-diff
 wayback-diff https://web.archive.org/web/20230101/https://example.com/ https://example.com/
 ```
 
-Add `--visual --markdown` for screenshots and a report (`pip install wayback-diff[visual]` first).
+Add `--visual --markdown` for screenshots and a report (`pip install "wayback-diff[visual]"` first). Needs Python 3.10 or newer; the source and Docker installs are in [Getting started](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/getting-started.md).
 
 ## Documentation
 
-- [Installation](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/installation.md): PyPI, source, Docker
-- [Usage](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/usage.md): options, visual comparison, Markdown reports, output formats
-- [CI/CD integration](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/ci.md): exit codes, GitHub Actions and shell gates
+- [Getting started](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/getting-started.md): PyPI, source, Docker
+- [Usage](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/usage.md): options, visual comparison, Markdown reports, output formats, and CI/CD gates on the exit codes
 - [How it works](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/how-it-works.md): cleaning, significance scoring, comparison with similar tools
 - [Development](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/development.md): tests and contributing
 - [Related projects](https://github.com/GeiserX/Wayback-Diff/blob/main/docs/related.md)
 
 ## License
 
-This project is licensed under the **GNU General Public License v3.0** (GPL-3.0). See the [LICENSE](LICENSE) file for details.
-
-This software is **not** intended for commercial use.
+[GPL-3.0-or-later](https://github.com/GeiserX/Wayback-Diff/blob/main/LICENSE)
diff --git a/docs/ci.md b/docs/ci.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,37 @@
+# Getting started
+
+Wayback-Diff needs Python 3.10 or newer.
+
+## From PyPI
+
+```bash
+pip install wayback-diff
+
+# With visual comparison support
+pip install "wayback-diff[visual]"
+```
+
+## From source
+
+```bash
+git clone https://github.com/GeiserX/Wayback-Diff.git
+cd Wayback-Diff
+python3 -m venv venv
+source venv/bin/activate      # Windows: venv\Scripts\activate
+pip install -r requirements.txt
+pip install -e .
+```
+
+For visual comparison support:
+
+```bash
+pip install -e ".[visual]"
+```
+
+## Docker
+
+```bash
+docker run --rm drumsergio/wayback-diff:1.1.0 https://example.com/a https://example.com/b
+```
+
+The image is built for `linux/amd64`; on Apple Silicon add `--platform linux/amd64`. To build the image from a checkout instead: `docker build -t wayback-diff .`, then `docker run --rm wayback-diff <url1> <url2>`.
diff --git a/docs/installation.md b/docs/installation.md
diff --git a/docs/related.md b/docs/related.md
@@ -3,8 +3,7 @@
 | Project | Description |
 |---------|-------------|
 | [Wayback-Archive](https://github.com/GeiserX/Wayback-Archive) | Download complete websites from the Wayback Machine with full asset preservation |
-| [Wayback-Diff](https://github.com/GeiserX/Wayback-Diff) | Intelligent web page comparison tool with Wayback Machine support |
 | [Way-CMS](https://github.com/GeiserX/Way-CMS) | Simple web CMS for editing HTML/CSS files downloaded from Wayback Archive |
 | [web-mirror](https://github.com/GeiserX/web-mirror) | Mirror any webpage to a local server for offline access |
 | [media-download](https://github.com/GeiserX/media-download) | Download all media files from any web page into a folder schema |
-| [n8n-nodes-way-cms](https://github.com/GeiserX/n8n-nodes-way-cms) | n8n community node for Way-CMS archived web content management |
+| [n8n-nodes-way-cms](https://github.com/GeiserX/n8n-nodes-way-cms) (archived) | n8n community node for Way-CMS archived web content management |
diff --git a/docs/usage.md b/docs/usage.md
@@ -52,7 +52,7 @@ wayback-diff url1 url2 --format unified
 
 ```bash
 # Crawl and compare across linked pages (depth-limited)
-wayback-diff url1 url2 --traverse --depth 2
+wayback-diff url1 url2 --traverse --max-depth 2
 ```
 
 ## Advanced options
@@ -142,3 +142,64 @@ Structured output for programmatic processing:
 ### Unified diff
 
 Standard unified diff format, compatible with `patch` and code review tools.
+
+## CI/CD integration
+
+Wayback-Diff returns meaningful exit codes designed for pipeline gates:
+
+| Exit Code | Meaning |
+|-----------|---------|
+| `0` | No differences detected |
+| `1` | Low or medium significance changes |
+| `2` | High significance changes detected |
+
+### GitHub Actions example
+
+```yaml
+name: Visual Regression Check
+on:
+  pull_request:
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install Wayback-Diff
+        run: |
+          pip install "wayback-diff[visual]"
+
+      - name: Compare staging vs production
+        run: |
+          wayback-diff \
+            https://staging.example.com \
+            https://production.example.com \
+            --visual --markdown --format json -o diff.json
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: diff-report
+          path: reports/
+```
+
+### Shell script gate
+
+```bash
+wayback-diff "$OLD_URL" "$NEW_URL" --format json -o result.json
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 2 ]; then
+  echo "BLOCKING: high-significance changes detected"
+  exit 1
+elif [ $EXIT_CODE -eq 1 ]; then
+  echo "WARNING: minor changes detected"
+fi
+```
diff --git a/setup.py b/setup.py
@@ -10,12 +10,12 @@
     version="1.1.0",
     author="geiserx",
     author_email="sergio@geiser.cloud",
-    description="A comprehensive tool for comparing web pages with Wayback Machine support",
+    description="Compare web pages, with Wayback Machine artifact cleaning and significance scoring",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/GeiserX/Wayback-Diff",
-    license="GPL-3.0-only",
-    license_files=[],
+    license="GPL-3.0-or-later",
+    license_files=["LICENSE"],
     packages=find_packages(),
     classifiers=[
         "Development Status :: 3 - Alpha",