aeo-audit 1.1.1__tar.gz

aeo_audit-1.1.1/.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Install system deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 libffi-dev
+          npx playwright install-deps chromium
+      - name: Install deps
+        run: pip install hatch && hatch env create
+      - name: Install Playwright Browsers
+        run: hatch run playwright install chromium
+      - name: Run tests
+        run: hatch run pytest -x -v --cov=aeo_audit --cov-fail-under=80
+      - name: Type check
+        run: hatch run mypy --strict aeo_audit/
+      - name: Lint
+        run: hatch run ruff check aeo_audit/
+
+  build-binary:
+    needs: test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Install system deps
+        run: |
+          if [ "${{ runner.os }}" = "Linux" ]; then
+            sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 upx
+          else
+            brew install pango cairo gdk-pixbuf upx
+          fi
+          npx playwright install-deps chromium
+      - name: Build binary
+        run: |
+          pip install pyinstaller
+          pyinstaller --clean aeo_audit.spec
+      - name: Upload binary
+        uses: actions/upload-artifact@v7
+        with:
+          name: aeo-audit-${{ runner.os }}
+          path: dist/aeo-audit
+
+  release:
+    needs: [test, build-binary]
+    if: github.event_name == 'release'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    env:
+      # Empty when no PyPI token is configured, so the publish step self-skips
+      # and the release still ships binaries instead of failing.
+      HAS_PYPI_TOKEN: ${{ secrets.PYPI_API_TOKEN != '' }}
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+      - name: Install Hatch
+        run: pip install hatch
+      - name: Build PyPI Package
+        run: hatch build
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: dist-binaries/
+      - name: Upload binaries to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          cp dist-binaries/aeo-audit-Linux/aeo-audit dist-binaries/aeo-audit-linux-x64
+          cp dist-binaries/aeo-audit-macOS/aeo-audit dist-binaries/aeo-audit-macos-arm64
+          gh release upload "${{ github.event.release.tag_name }}" dist-binaries/aeo-audit-linux-x64 dist-binaries/aeo-audit-macos-arm64 --clobber
+      - name: Publish to PyPI
+        if: env.HAS_PYPI_TOKEN == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+        continue-on-error: true

aeo_audit-1.1.1/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtualenv
+.env
+.env.*
+.venv/
+venv/
+ENV/
+
+# Build
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+
+# SQLite
+*.sqlite
+*.sqlite3
+*.db
+
+# Playwright
+playwright-report/
+test-results/
+
+# Local configs
+config.local.yaml
+.env.local
+
+# Cache
+.cache/
+
+# Scan outputs — scraped page data may contain secrets/PII; keep out of VCS
+results.jsonl
+*.results.jsonl
+case-studies/

aeo_audit-1.1.1/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to `aeo-audit` are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.1] - 2026-06-10
+
+### Changed
+- CI: bumped GitHub Actions to their Node 24 majors (`checkout@v6`,
+  `setup-python@v6`, `upload-artifact@v7`, `download-artifact@v8`).
+- Refreshed the benchmark corpus under the fixed scoring so percentile grades
+  rank sites against a field measured the same way.
+
+### Added
+- First release published to PyPI (`pip install aeo-audit`).
+
+## [1.1.0] - 2026-06-09
+
+Launch-readiness release: makes the score a usable feedback loop and fixes
+reliability and install blockers.
+
+### Changed
+- **Foundation-weighted scoring.** Category and per-check weights now favour the
+  signals well-run APIs already expose today (Trust, Capabilities, Discovery)
+  so the score differentiates real sites instead of collapsing every site to F.
+- **Percentile-relative overall grading.** Grades rank a site against a
+  benchmark corpus (A = top 10%), with absolute-threshold fallback when no
+  corpus is loaded. Category grades remain absolute.
+- **Crawler wait strategy is now `load`** (was `networkidle`, which never
+  settles on long-polling sites); default timeout raised 30s → 45s. Both are
+  config-driven.
+
+### Fixed
+- **`robots_agent` always failed in production.** The crawler never populated
+  `context.robots_txt`, so the check scored 0 for every site. Added a self-fetch
+  fallback and tiered scoring (explicit allow / allow-all / blocked / missing).
+- **Install paths.** Corrected repository-owner references, documented
+  `pipx install git+https://…` and the standalone binary's Chromium runtime
+  requirement, and fixed broken documentation links.
+
+### Added
+- `scripts/gen_benchmark.py` to (re)generate the percentile benchmark corpus
+  from a results file under the current weights.
+- Robust benchmark-path resolution that works from the repo, an installed
+  package, and the bundled binary.
+
+## [1.0.0] - 2026-06-07
+
+- Initial release: 26 checks across 5 dimensions, 4 reporters (terminal, HTML,
+  PDF, JSON), SQLite cache, CLI (scan, batch, diff, config, monitor), and
+  Hatch / PyInstaller / Homebrew packaging.

aeo_audit-1.1.1/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: aeo-audit
+Version: 1.1.1
+Summary: CLI tool to scan websites and score their Agent/Engine Optimization (AEO) readiness.
+Project-URL: Homepage, https://github.com/AJ-EN/aeo-audit
+Project-URL: Repository, https://github.com/AJ-EN/aeo-audit
+Project-URL: Issues, https://github.com/AJ-EN/aeo-audit/issues
+Author: Ayush Jangid
+License: MIT
+Keywords: aeo,agent,audit,cli,seo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiofiles<25,>=23.0
+Requires-Dist: base58<3,>=2.1
+Requires-Dist: click<9,>=8.1
+Requires-Dist: cryptography<44,>=42.0
+Requires-Dist: dnspython<3,>=2.4
+Requires-Dist: eth-utils<5,>=4.0
+Requires-Dist: extruct<1,>=0.17
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: jinja2<4,>=3.1
+Requires-Dist: jsonschema<5,>=4.20
+Requires-Dist: multiformats<1,>=0.2
+Requires-Dist: openapi-spec-validator<1,>=0.7
+Requires-Dist: playwright<2,>=1.40
+Requires-Dist: pydantic-settings<3,>=2.0
+Requires-Dist: pydantic<3,>=2.0
+Requires-Dist: python-jose[cryptography]<4,>=3.3
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: rich<14,>=13.0
+Provides-Extra: all
+Requires-Dist: hypothesis<7,>=6.90; extra == 'all'
+Requires-Dist: mypy<2,>=1.8; extra == 'all'
+Requires-Dist: pydyf<0.11.0; extra == 'all'
+Requires-Dist: pyinstaller<7,>=6.0; extra == 'all'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'all'
+Requires-Dist: pytest-cov<6,>=5.0; extra == 'all'
+Requires-Dist: pytest-mock<4,>=3.12; extra == 'all'
+Requires-Dist: pytest<9,>=8.0; extra == 'all'
+Requires-Dist: ruff<1,>=0.3; extra == 'all'
+Requires-Dist: types-aiofiles>=23.0; extra == 'all'
+Requires-Dist: types-pyyaml>=6.0; extra == 'all'
+Requires-Dist: weasyprint<62,>=60; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: hypothesis<7,>=6.90; extra == 'dev'
+Requires-Dist: mypy<2,>=1.8; extra == 'dev'
+Requires-Dist: pyinstaller<7,>=6.0; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov<6,>=5.0; extra == 'dev'
+Requires-Dist: pytest-mock<4,>=3.12; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.3; extra == 'dev'
+Requires-Dist: types-aiofiles>=23.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: pdf
+Requires-Dist: pydyf<0.11.0; extra == 'pdf'
+Requires-Dist: weasyprint<62,>=60; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# AEO Auditor CLI
+
+[![Build Status](https://github.com/AJ-EN/aeo-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/AJ-EN/aeo-audit/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+**PageSpeed for AI agents.** Scan any website and score its **Agent/Engine Optimization (AEO) readiness** across 5 dimensions — Discovery, Identity, Capabilities, Commerce, and Trust — then get a graded report with prioritized, actionable fixes.
+
+Grades are **relative**: a site is ranked against a benchmark corpus (A = top tier of agent-readiness today), so the score stays a meaningful, movable target while agent-native standards are still emerging.
+
+---
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    CLI[CLI: aeo-audit] --> Engine[ScanEngine]
+    Engine --> Config[ConfigLoader]
+    Engine --> Crawler[Playwright Crawler]
+    Engine --> Registry[CheckRegistry]
+    Crawler --> Fetch[Fetch URL & Render DOM]
+    Registry --> Run[Run 26 Audit Checks]
+    Run --> Score[Scoring Pipeline]
+    Score --> Reporter[ReporterFactory]
+    Reporter --> Terminal[Rich Terminal]
+    Reporter --> HTML[HTML Report]
+    Reporter --> PDF[WeasyPrint PDF]
+    Reporter --> JSON[JSON Metadata]
+```
+
+---
+
+## Installation
+
+### 1. System Dependencies (Required for WeasyPrint PDF)
+
+PDF reports require external layout libraries installed on your OS:
+
+- **macOS (Homebrew)**:
+
+  ```bash
+  brew install pango cairo gdk-pixbuf upx
+  ```
+
+- **Ubuntu/Debian**:
+
+  ```bash
+  sudo apt-get update
+  sudo apt-get install -y libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 upx
+  ```
+
+### 2. Install Methods
+
+#### Method A: Via `pipx` (Recommended for Python CLI apps)
+
+```bash
+# From GitHub (works today):
+pipx install git+https://github.com/AJ-EN/aeo-audit.git
+
+# From PyPI (once published):
+# pipx install aeo-audit
+```
+
+After installing, download the headless browser Playwright needs:
+
+```bash
+playwright install chromium
+```
+
+#### Method B: Standalone Binary Installer (No Python Needed)
+
+Run the automated installation script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AJ-EN/aeo-audit/main/scripts/install.sh | bash
+```
+
+> [!IMPORTANT]
+> The binary still needs a Chromium runtime. If a scan reports a missing browser,
+> install one with `playwright install chromium` and point the binary at it:
+> `export PLAYWRIGHT_BROWSERS_PATH="$HOME/Library/Caches/ms-playwright"` (macOS)
+> or the equivalent cache path on your OS.
+
+#### Method C: Source installation
+
+```bash
+git clone https://github.com/AJ-EN/aeo-audit.git
+cd aeo-audit
+pip install -e .
+playwright install chromium
+```
+
+> [!NOTE]
+> If WeasyPrint throws rendering or font warnings on Python 3.14+, we recommend pinning `pydyf==0.10.0`.
+
+---
+
+## Quick Start
+
+Scan a site and generate reports using the `scan` command:
+
+```bash
+# Terminal report (default)
+aeo-audit scan https://api.example.com --format terminal
+
+# Premium HTML report with embedded graphs
+aeo-audit scan https://api.example.com --format html --output report.html
+
+# Accessible PDF report
+aeo-audit scan https://api.example.com --format pdf --output report.pdf
+
+# Machine-readable JSON report
+aeo-audit scan https://api.example.com --format json --output report.json
+```
+
+---
+
+## Scoring & Grading
+
+Each of the 26 checks returns a raw score (`0.0`–`1.0`). Checks roll up into 5 weighted category scores, which roll up into a single `0–100` overall score. The grade is then assigned **by percentile rank against a benchmark corpus** — so it reflects how a site compares to the field, not an absolute bar that nobody clears yet.
+
+### Category weights
+
+`aeo-audit` is **foundation-weighted**: dimensions where well-run APIs already differ today (Trust, Capabilities, Discovery) carry the most weight, while emerging agent-native dimensions (Identity, parts of Commerce) contribute upside without dominating the score.
+
+| Category | Weight | What it measures |
+|----------|--------|------------------|
+| **Discovery** | `0.25` | robots/agent access, sitemap, `.well-known`, DNS, and MCP discovery. |
+| **Capabilities** | `0.25` | Interface docs — OpenAPI, JSON Schema, GraphQL, async webhooks. |
+| **Trust** | `0.25` | SLA/status page, structured errors, health checks, audit logs. |
+| **Commerce** | `0.15` | Agent transactions — pricing, Stripe/crypto hints, usage metering. |
+| **Identity** | `0.10` | Ownership & auth — DID docs, OAuth metadata, wallet hints. |
+
+### Grade bands (percentile)
+
+| Grade | Percentile | Meaning |
+|-------|-----------|---------|
+| **A** | top 10% | Leading the field on agent-readiness. |
+| **B** | top 30% | Strong; a few high-leverage gaps. |
+| **C** | top 60% | Foundational signals present, frontier gaps. |
+| **D** | top 85% | Minimal agent-readiness. |
+| **F** | bottom 15% | Not addressed. |
+
+Weights, thresholds, and grade bands are all defined in `config.yaml` and overridable via a custom config. See [docs/CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md).
+
+---
+
+## CI/CD Pipeline Integration
+
+You can easily configure `aeo-audit` as a compliance block (exits with code `2` if scores drop below requirements). Here's a brief example for **GitHub Actions**:
+
+```yaml
+- name: AEO Compliance Gate
+  run: aeo-audit scan https://preview.example.com --fail-on-grade B --format terminal
+```
+
+See [docs/CI_RECIPES.md](docs/CI_RECIPES.md) for GitHub Actions, GitLab CI, and Git hooks code snippets.
+
+---
+
+## Extending: Custom Check Plugins
+
+To implement custom checking rules, subclass `BaseCheck` and expose it under the `aeo_audit.checks` entrypoint.
+
+See [docs/CUSTOM_CHECKS.md](docs/CUSTOM_CHECKS.md) for a complete template walkthrough.
+
+---
+
+## FAQ
+
+#### 1. How do I install Playwright browser binaries?
+
+If running the scanner for the first time, you may need to install Playwright's headless browser binaries:
+
+```bash
+playwright install chromium
+```
+
+#### 2. Where is the SQLite cache stored?
+
+By default, the SQLite cache database is created in your working directory as `.aeo_cache.db` to speed up consecutive audit scans. This can be customized or disabled using `--no-cache`.
+
+#### 3. Why are my PDF files empty or raising font errors?
+
+Ensure you have installed the native `pango` and `cairo` system dependencies (see Step 1 of installation).

aeo_audit-1.1.1/README.md

@@ -0,0 +1,185 @@
+# AEO Auditor CLI
+
+[![Build Status](https://github.com/AJ-EN/aeo-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/AJ-EN/aeo-audit/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+**PageSpeed for AI agents.** Scan any website and score its **Agent/Engine Optimization (AEO) readiness** across 5 dimensions — Discovery, Identity, Capabilities, Commerce, and Trust — then get a graded report with prioritized, actionable fixes.
+
+Grades are **relative**: a site is ranked against a benchmark corpus (A = top tier of agent-readiness today), so the score stays a meaningful, movable target while agent-native standards are still emerging.
+
+---
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    CLI[CLI: aeo-audit] --> Engine[ScanEngine]
+    Engine --> Config[ConfigLoader]
+    Engine --> Crawler[Playwright Crawler]
+    Engine --> Registry[CheckRegistry]
+    Crawler --> Fetch[Fetch URL & Render DOM]
+    Registry --> Run[Run 26 Audit Checks]
+    Run --> Score[Scoring Pipeline]
+    Score --> Reporter[ReporterFactory]
+    Reporter --> Terminal[Rich Terminal]
+    Reporter --> HTML[HTML Report]
+    Reporter --> PDF[WeasyPrint PDF]
+    Reporter --> JSON[JSON Metadata]
+```
+
+---
+
+## Installation
+
+### 1. System Dependencies (Required for WeasyPrint PDF)
+
+PDF reports require external layout libraries installed on your OS:
+
+- **macOS (Homebrew)**:
+
+  ```bash
+  brew install pango cairo gdk-pixbuf upx
+  ```
+
+- **Ubuntu/Debian**:
+
+  ```bash
+  sudo apt-get update
+  sudo apt-get install -y libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 upx
+  ```
+
+### 2. Install Methods
+
+#### Method A: Via `pipx` (Recommended for Python CLI apps)
+
+```bash
+# From GitHub (works today):
+pipx install git+https://github.com/AJ-EN/aeo-audit.git
+
+# From PyPI (once published):
+# pipx install aeo-audit
+```
+
+After installing, download the headless browser Playwright needs:
+
+```bash
+playwright install chromium
+```
+
+#### Method B: Standalone Binary Installer (No Python Needed)
+
+Run the automated installation script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AJ-EN/aeo-audit/main/scripts/install.sh | bash
+```
+
+> [!IMPORTANT]
+> The binary still needs a Chromium runtime. If a scan reports a missing browser,
+> install one with `playwright install chromium` and point the binary at it:
+> `export PLAYWRIGHT_BROWSERS_PATH="$HOME/Library/Caches/ms-playwright"` (macOS)
+> or the equivalent cache path on your OS.
+
+#### Method C: Source installation
+
+```bash
+git clone https://github.com/AJ-EN/aeo-audit.git
+cd aeo-audit
+pip install -e .
+playwright install chromium
+```
+
+> [!NOTE]
+> If WeasyPrint throws rendering or font warnings on Python 3.14+, we recommend pinning `pydyf==0.10.0`.
+
+---
+
+## Quick Start
+
+Scan a site and generate reports using the `scan` command:
+
+```bash
+# Terminal report (default)
+aeo-audit scan https://api.example.com --format terminal
+
+# Premium HTML report with embedded graphs
+aeo-audit scan https://api.example.com --format html --output report.html
+
+# Accessible PDF report
+aeo-audit scan https://api.example.com --format pdf --output report.pdf
+
+# Machine-readable JSON report
+aeo-audit scan https://api.example.com --format json --output report.json
+```
+
+---
+
+## Scoring & Grading
+
+Each of the 26 checks returns a raw score (`0.0`–`1.0`). Checks roll up into 5 weighted category scores, which roll up into a single `0–100` overall score. The grade is then assigned **by percentile rank against a benchmark corpus** — so it reflects how a site compares to the field, not an absolute bar that nobody clears yet.
+
+### Category weights
+
+`aeo-audit` is **foundation-weighted**: dimensions where well-run APIs already differ today (Trust, Capabilities, Discovery) carry the most weight, while emerging agent-native dimensions (Identity, parts of Commerce) contribute upside without dominating the score.
+
+| Category | Weight | What it measures |
+|----------|--------|------------------|
+| **Discovery** | `0.25` | robots/agent access, sitemap, `.well-known`, DNS, and MCP discovery. |
+| **Capabilities** | `0.25` | Interface docs — OpenAPI, JSON Schema, GraphQL, async webhooks. |
+| **Trust** | `0.25` | SLA/status page, structured errors, health checks, audit logs. |
+| **Commerce** | `0.15` | Agent transactions — pricing, Stripe/crypto hints, usage metering. |
+| **Identity** | `0.10` | Ownership & auth — DID docs, OAuth metadata, wallet hints. |
+
+### Grade bands (percentile)
+
+| Grade | Percentile | Meaning |
+|-------|-----------|---------|
+| **A** | top 10% | Leading the field on agent-readiness. |
+| **B** | top 30% | Strong; a few high-leverage gaps. |
+| **C** | top 60% | Foundational signals present, frontier gaps. |
+| **D** | top 85% | Minimal agent-readiness. |
+| **F** | bottom 15% | Not addressed. |
+
+Weights, thresholds, and grade bands are all defined in `config.yaml` and overridable via a custom config. See [docs/CONFIG_REFERENCE.md](docs/CONFIG_REFERENCE.md).
+
+---
+
+## CI/CD Pipeline Integration
+
+You can easily configure `aeo-audit` as a compliance block (exits with code `2` if scores drop below requirements). Here's a brief example for **GitHub Actions**:
+
+```yaml
+- name: AEO Compliance Gate
+  run: aeo-audit scan https://preview.example.com --fail-on-grade B --format terminal
+```
+
+See [docs/CI_RECIPES.md](docs/CI_RECIPES.md) for GitHub Actions, GitLab CI, and Git hooks code snippets.
+
+---
+
+## Extending: Custom Check Plugins
+
+To implement custom checking rules, subclass `BaseCheck` and expose it under the `aeo_audit.checks` entrypoint.
+
+See [docs/CUSTOM_CHECKS.md](docs/CUSTOM_CHECKS.md) for a complete template walkthrough.
+
+---
+
+## FAQ
+
+#### 1. How do I install Playwright browser binaries?
+
+If running the scanner for the first time, you may need to install Playwright's headless browser binaries:
+
+```bash
+playwright install chromium
+```
+
+#### 2. Where is the SQLite cache stored?
+
+By default, the SQLite cache database is created in your working directory as `.aeo_cache.db` to speed up consecutive audit scans. This can be customized or disabled using `--no-cache`.
+
+#### 3. Why are my PDF files empty or raising font errors?
+
+Ensure you have installed the native `pango` and `cairo` system dependencies (see Step 1 of installation).