geo-checker 0.1.0 → 0.3.1

package/README.ko.md

@@ -0,0 +1,267 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BaRam-OSS/geo-checker/main/docs/assets/baram.png" alt="BaRam" width="260" />
+</p>
+
+<h1 align="center">geo-checker</h1>
+
+<p align="center">
+  <b>Generative Engine Optimization(GEO)</b>을 위한 Lighthouse급 감사 도구. ChatGPT · Claude · Gemini · Perplexity 같은 AI 검색 엔진이 내 사이트를 얼마나 잘 발견하고, 이해하고, 인용할 수 있는지 측정합니다.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/geo-checker"><img src="https://img.shields.io/npm/v/geo-checker.svg" alt="npm" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/geo-checker.svg" alt="license" /></a>
+  <a href="https://github.com/BaRam-OSS/geo-checker/actions/workflows/ci.yml"><img src="https://github.com/BaRam-OSS/geo-checker/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+</p>
+
+<p align="center">
+  <b>한국어</b> · <a href="./README.md">English</a>
+</p>
+
+---
+
+## 왜 필요한가요?
+
+기존 SEO 도구는 **구글 검색이 내 페이지를 랭킹할 수 있는지**를 점검합니다. `geo-checker`는 한 걸음 더 나아가, **AI 검색 엔진이 내 페이지를 인용할 수 있는지**를 점검합니다. **31개의 온페이지 신호**를 4개의 가중치 범주에 걸쳐 검사하고, 0–100점의 카테고리 점수와 함께 인터랙티브 HTML 리포트, 우선순위가 매겨진 개선 기회(Opportunities), 구체적인 수정 방법을 제공합니다.
+
+Google Lighthouse에서 영감을 받아 만들었지만, 대상은 GEO입니다 — AI 크롤러 robots 규칙, `llms.txt`, schema.org 그래프 품질, 인용 신호 등.
+
+## 설치
+
+```sh
+# 일회성 실행
+npx geo-checker https://example.com
+
+# 또는 개발 의존성으로 추가
+npm install --save-dev geo-checker
+```
+
+Node.js **20.18.1 이상**이 필요합니다.
+
+## 사용법 — CLI
+
+```sh
+# 터미널 출력 (impact 칩 + 타이밍 포함)
+geo-checker https://example.com
+
+# 독립 실행형 HTML 리포트 생성
+geo-checker https://example.com --html report.html
+
+# report.json + report.html을 함께 디렉터리에 저장
+geo-checker https://example.com --out ./reports
+
+# stdout으로 JSON 출력 (jq, CI 파이프라이닝용)
+geo-checker https://example.com --json > report.json
+
+# SPA / JS 렌더링 사이트 (playwright 선택 의존성 필요)
+geo-checker https://example.com --render
+
+# 특정 카테고리나 룰만 실행
+geo-checker https://example.com --category crawler
+geo-checker https://example.com --only crawler.https,sd.required-fields
+
+# CI 모드 — warn 또는 fail 시 exit 1
+geo-checker https://example.com --fail-on warn
+```
+
+**전체 플래그 목록:**
+
+| 플래그 | 설명 |
+|---|---|
+| `--json` | JSON을 stdout으로 출력. |
+| `--html <path>` | 독립 실행형 HTML 리포트를 `<path>`에 저장. `-`이면 stdout. |
+| `--out <dir>` | `<dir>`에 `report.json` + `report.html`을 함께 저장 (디렉터리 자동 생성). |
+| `--csv <path>` | 룰별 1행의 플랫 CSV 저장 — BI 대시보드 인제스트용. |
+| `--md <path>` | 점수 뱃지 + 이슈 표가 담긴 Markdown PR 코멘트 템플릿 저장. |
+| `--sarif <path>` | **GitHub Code Scanning** 통합용 SARIF 2.1.0 리포트 저장. |
+| `--baseline <prev.json>` | 이전 JSON 리포트와 비교하여 카테고리 delta, 회귀, 해결 항목 출력. |
+| `--config <path>` | 설정 파일 로드 (기본값: cwd의 `geo-checker.config.{json,mjs,js}`). |
+| `--render` | Playwright 기반 헤드리스 Chromium 사용 (선택 의존성). |
+| `--category <names>` | 쉼표 구분: `crawler`, `structured-data`, `citation`, `content`. |
+| `--only <ids>` | 실행할 rule ID (또는 stableId) 쉼표 구분. |
+| `--fail-on <level>` | `fail`(기본) 또는 `warn`. |
+| `--timeout <ms>` | 요청당 타임아웃 (기본 20 000). |
+
+**배치 모드:**
+
+```sh
+# urls.txt의 모든 URL(한 줄 하나, `#` 주석 허용) 감사, 동시성 4
+geo-checker batch urls.txt --out ./reports --concurrency 4
+```
+
+URL별 `<slug>.json` + `<slug>.html`과 집계된 `summary.json`을 생성합니다. 한 URL 실패가 전체 배치를 중단시키지 않습니다.
+
+**종료 코드:** `0` 성공 · `1` 정책 실패 · `2` 런타임 오류.
+
+## 설정 파일
+
+프로젝트 루트에 `geo-checker.config.json` (또는 `--config <path>`)을 두면 룰을 끄거나, 가중치를 조정하거나, 커스텀 룰을 주입할 수 있습니다:
+
+```json
+{
+  "rules": {
+    "cnt.word-count": { "enabled": false },
+    "crawler.robots-ai-allow": { "weight": 10 }
+  },
+  "categories": {
+    "structured-data": { "weight": 40 }
+  }
+}
+```
+
+`.mjs` / `.js`도 지원합니다 (`export default` 로 config 객체 내보내기). 모든 stableId 목록은 [`docs/rules.md`](./docs/rules.md) 참조.
+
+## HTML 리포트
+
+`--html`은 외부 CSS, 폰트, 네트워크 호출 없이 작동하는 단일 HTML 파일을 생성합니다. 브라우저에서 바로 열면 Lighthouse와 유사한 UX를 경험할 수 있습니다:
+
+- **점수 링(Score Ring)** — 전체 점수와 카테고리별 점수.
+- **Opportunities** — 고치면 회복할 수 있는 점수 순으로 정렬된 개선 기회.
+- **Diagnostics** — 나머지 비통과 감사 항목, 카테고리별로 그룹핑.
+- **Passed audits** — 기본적으로 접혀 있음.
+- **Raw JSON** — 다른 도구로 파이핑할 수 있는 Copy-to-clipboard 버튼.
+
+라이트/다크 모드에 자동으로 대응합니다. 일반 페이지 기준 ~60–80 KB.
+
+## 사용법 — 프로그래매틱 API
+
+```ts
+import { audit } from 'geo-checker';
+
+const report = await audit('https://example.com', { render: false });
+
+console.log(report.overall);                       // 78
+console.log(report.categories.crawler.score);      // 92
+console.log(report.timing);                        // { fetchMs, auditMs, totalMs }
+console.log(report.meta);                          // { toolVersion, nodeVersion, ... }
+```
+
+### HTML 또는 JSON 리포트를 직접 렌더링
+
+```ts
+import { audit } from 'geo-checker';
+import { toHtml } from 'geo-checker/dist/reporters/html.js';
+import { toJson } from 'geo-checker/dist/reporters/json.js';
+
+const report = await audit('https://example.com');
+await fs.writeFile('report.html', toHtml(report));
+await fs.writeFile('report.json', toJson(report));
+```
+
+## 무엇을 검사하나요?
+
+| 카테고리 | 검사 항목 | 룰 수 | 가중치 |
+|---|---|---:|---:|
+| **AI Crawler Access** | HTTPS, robots.txt 도달성, **17개 AI 봇 허용 목록** (GPTBot, OAI-SearchBot, ChatGPT-User, Google-Extended, Google-CloudVertexBot, ClaudeBot, anthropic-ai, Claude-Web, PerplexityBot, Applebot-Extended, Meta-ExternalAgent, Bytespider, DuckAssistBot, YouBot, cohere-ai, CCBot, Amazonbot), `llms.txt`, `llms-full.txt`, sitemap.xml | 7 | 25 |
+| **Structured Data** | JSON-LD 존재/유효성, 인식 가능한 schema.org 타입, 필수 필드 커버리지, microdata/RDFa 폴백, 중복 primary 타입 검사, `sameAs` 지식 그래프 연결, BreadcrumbList 아이템 유효성 | 8 | 30 |
+| **Citation Signals** | `<title>`, meta description, canonical, Open Graph, Twitter Card, `<html lang>`, 저자, 게시/수정 날짜, 콘텐츠 신선도(dateModified ≤ 1년) | 9 | 25 |
+| **Content Structure** | 단일 `<h1>`, 헤딩 계층, 이미지 alt 커버리지, TL;DR / FAQ 블록, 단어 수, 답 추출용 Q&A 구조, 외부 인용(E-E-A-T) | 7 | 20 |
+
+모든 룰은 다음 필드를 선언합니다:
+
+- **`stableId`** — CI 예산용 고정 식별자 (절대 변경되지 않음).
+- **`impact`** — `critical` / `high` / `medium` / `low`.
+- **`effort`** — `low` / `medium` / `high` (수정에 걸리는 시간의 대략적인 지표).
+- **`group`** — `opportunity` (회복 가능한 점수) 또는 `diagnostic` (이진 신호).
+
+전체 룰 목록과 수정 가이드는 [`docs/rules.md`](./docs/rules.md)를 참조하세요.
+
+## 리포트 스키마
+
+```ts
+interface AuditReport {
+  schemaVersion: 1;
+  url: string;
+  finalUrl: string;
+  fetchedAt: string;
+  renderMode: 'static' | 'rendered';
+  overall: number;                                     // 0–100
+  categories: Record<Category, CategoryReport>;
+  warnings: string[];
+  version: string;
+  meta: { toolVersion: string; nodeVersion: string; userAgent?: string };
+  timing: { fetchMs: number; auditMs: number; totalMs: number };
+}
+```
+
+각 감사 결과는 `stableId`, `impact`, `effort`, `group`, `docsUrl`, 그리고 해당되는 경우 `estimatedImpact`(Opportunity가 얼마나 가치 있는 점수인지)를 함께 담고 있습니다.
+
+## 확장성
+
+커스텀 룰을 추가하는 방법:
+
+```ts
+import { audit, defineRule } from 'geo-checker';
+
+const hasJsonFeed = defineRule({
+  id: 'custom.has-json-feed',
+  stableId: 'custom.has-json-feed',
+  category: 'crawler',
+  group: 'opportunity',
+  weight: 2,
+  impact: 'low',
+  effort: 'low',
+  title: 'JSON Feed present',
+  description: 'Site should expose a JSON Feed at /feed.json',
+  docsUrl: 'https://example.com/docs/json-feed',
+  async run(ctx) {
+    // ctx.$ / ctx.headers / ctx.robots 등을 활용한 검사 로직
+    return { status: 'pass', score: 1, rationale: 'JSON feed found' };
+  },
+});
+
+const report = await audit('https://example.com', { extraRules: [hasJsonFeed] });
+```
+
+커스텀 룰은 기본 룰과 자동으로 병합되며, 모든 reporter에서 동일하게 출력됩니다.
+
+## CI 레시피
+
+```yaml
+# .github/workflows/geo.yml
+name: GEO audit
+on: [push, pull_request]
+jobs:
+  geo:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # SARIF 업로드용
+      pull-requests: write    # PR 코멘트용
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: |
+          npx -y geo-checker https://staging.example.com \
+            --fail-on warn \
+            --out ./geo \
+            --sarif ./geo/results.sarif \
+            --md ./geo/summary.md
+      - uses: actions/upload-artifact@v4
+        with:
+          name: geo-report
+          path: ./geo
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: ./geo/results.sarif
+      - if: github.event_name == 'pull_request'
+        run: gh pr comment ${{ github.event.pull_request.number }} --body-file ./geo/summary.md
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**회귀 추적** 은 마지막 안정 `report.json`을 저장해두고 `--baseline`으로 넘기면 됩니다:
+
+```sh
+geo-checker https://staging.example.com --baseline ./baselines/main.json --out ./geo
+```
+
+## 라이선스
+
+MIT © BaRam-OSS. [LICENSE](./LICENSE) 참조.
+
+## 기여하기
+
+새로운 룰, 픽스처, 문서 개선 등 PR을 환영합니다. [CONTRIBUTING.md](./CONTRIBUTING.md) 참조.

package/README.md

@@ -1,16 +1,30 @@
-# geo-checker
+<p align="center">
+  <img src="https://raw.githubusercontent.com/BaRam-OSS/geo-checker/main/docs/assets/baram.png" alt="BaRam" width="260" />
+</p>
 
-> Lighthouse-style auditor for **Generative Engine Optimization (GEO)**. Checks how ready your site is to be cited by ChatGPT, Claude, Gemini, and Perplexity.
+<h1 align="center">geo-checker</h1>
 
-[![npm](https://img.shields.io/npm/v/geo-checker.svg)](https://www.npmjs.com/package/geo-checker)
-[![license](https://img.shields.io/npm/l/geo-checker.svg)](./LICENSE)
-[![CI](https://github.com/BaRam-OSS/geo-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/BaRam-OSS/geo-checker/actions/workflows/ci.yml)
+<p align="center">
+  Lighthouse-grade auditor for <b>Generative Engine Optimization (GEO)</b>. Measures how ready your site is to be found, understood, and cited by ChatGPT · Claude · Gemini · Perplexity.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/geo-checker"><img src="https://img.shields.io/npm/v/geo-checker.svg" alt="npm" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/geo-checker.svg" alt="license" /></a>
+  <a href="https://github.com/BaRam-OSS/geo-checker/actions/workflows/ci.yml"><img src="https://github.com/BaRam-OSS/geo-checker/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+</p>
+
+<p align="center">
+  <a href="./README.ko.md">한국어</a> · <b>English</b>
+</p>
 
 ---
 
 ## Why
 
-SEO tools check whether Google can rank your page. `geo-checker` checks whether **AI search engines** can find, understand, and cite it. It inspects 24 on-page signals across four categories and gives you a 0–100 score per category, plus concrete fix suggestions.
+SEO tools tell you whether **Google** can rank your page. `geo-checker` tells you whether **AI search engines** can cite it. It inspects **31 on-page signals** across four weighted categories and returns a 0–100 score per category — plus an interactive HTML report, prioritized Opportunities, and concrete fixes.
+
+Inspired by Google Lighthouse, but built for GEO: AI-crawler robots rules, `llms.txt`, schema.org graph quality, citation signals.
 
 ## Install
 
@@ -18,24 +32,96 @@ SEO tools check whether Google can rank your page. `geo-checker` checks whether
 # One-off
 npx geo-checker https://example.com
 
-# Or as a dependency
+# Or as a dev dependency
 npm install --save-dev geo-checker
 ```
 
-Node.js 20.18.1 or later required.
+Requires Node.js **≥ 20.18.1**.
 
 ## Usage — CLI
 
 ```sh
-geo-checker https://example.com                       # pretty output
-geo-checker https://example.com --json > report.json  # JSON output
-geo-checker https://example.com --render              # use headless browser (SPA sites)
-geo-checker https://example.com --category crawler    # run only one category
-geo-checker https://example.com --only sd.required-fields
-geo-checker https://example.com --fail-on warn        # CI mode (exit 1 on warn/fail)
+# Pretty terminal output (with impact chips and timing)
+geo-checker https://example.com
+
+# Standalone interactive HTML report
+geo-checker https://example.com --html report.html
+
+# Write report.json + report.html side-by-side
+geo-checker https://example.com --out ./reports
+
+# JSON to stdout (for piping to jq, CI, etc.)
+geo-checker https://example.com --json > report.json
+
+# SPA / JS-rendered sites (requires optional playwright)
+geo-checker https://example.com --render
+
+# Filter to a single category or rule set
+geo-checker https://example.com --category crawler
+geo-checker https://example.com --only crawler.https,sd.required-fields
+
+# CI mode — exit 1 on warn or fail
+geo-checker https://example.com --fail-on warn
+```
+
+**All flags:**
+
+| Flag | Description |
+|---|---|
+| `--json` | Emit JSON to stdout. |
+| `--html <path>` | Write a self-contained HTML report to `<path>`. Use `-` for stdout. |
+| `--out <dir>` | Write `report.json` + `report.html` to `<dir>` (directory is created if missing). |
+| `--csv <path>` | Flat CSV export (one row per rule result) — feed into BI dashboards. |
+| `--md <path>` | Markdown PR-comment summary with score badges and an issue table. |
+| `--sarif <path>` | SARIF 2.1.0 report for **GitHub Code Scanning** integration. |
+| `--baseline <prev.json>` | Compare against a prior JSON report and print per-category deltas + regressions/fixes. |
+| `--config <path>` | Load a config file (defaults to `geo-checker.config.{json,mjs,js}` in cwd). |
+| `--render` | Use headless Chromium via Playwright (optional dep). |
+| `--category <names>` | Comma-separated: `crawler`, `structured-data`, `citation`, `content`. |
+| `--only <ids>` | Comma-separated rule IDs (or stableIds) to run. |
+| `--fail-on <level>` | `fail` (default) or `warn`. |
+| `--timeout <ms>` | Per-request timeout (default 20 000). |
+
+**Batch mode:**
+
+```sh
+# Audit every URL in urls.txt (one per line, # comments allowed) with 4 workers
+geo-checker batch urls.txt --out ./reports --concurrency 4
+```
+
+Writes per-URL `<slug>.json` + `<slug>.html` and an aggregated `summary.json`. Per-URL failures are isolated — one timeout doesn't abort the batch.
+
+**Exit codes:** `0` success · `1` policy failure · `2` runtime error.
+
+## Config file
+
+Drop a `geo-checker.config.json` in your project root (or pass `--config <path>`) to disable rules, adjust weights, or inject custom rules:
+
+```json
+{
+  "rules": {
+    "cnt.word-count": { "enabled": false },
+    "crawler.robots-ai-allow": { "weight": 10 }
+  },
+  "categories": {
+    "structured-data": { "weight": 40 }
+  }
+}
 ```
 
-Exit codes: `0` success · `1` policy failure · `2` runtime error.
+`.mjs` and `.js` are also supported (must `export default` the config object). See [`docs/rules.md`](./docs/rules.md) for every rule `stableId`.
+
+## The HTML report
+
+`--html` produces a single, self-contained HTML file — no external CSS, fonts, or network calls. Open it in any browser. It mirrors the Lighthouse UX:
+
+- **Score rings** for overall and each category.
+- **Opportunities** section — ranked by the points you would recover by fixing each issue.
+- **Diagnostics** — the remaining non-passing audits, grouped by category.
+- **Passed audits** — collapsed by default.
+- **Raw JSON** — copy-to-clipboard button for piping into other tools.
+
+Auto-adapts to light/dark mode. ~60–80 KB for a typical page.
 
 ## Usage — Programmatic
 
@@ -43,20 +129,62 @@ Exit codes: `0` success · `1` policy failure · `2` runtime error.
 import { audit } from 'geo-checker';
 
 const report = await audit('https://example.com', { render: false });
-console.log(report.overall);            // 78
-console.log(report.categories.crawler); // { score: 92, results: [...] }
+
+console.log(report.overall);                       // 78
+console.log(report.categories.crawler.score);      // 92
+console.log(report.timing);                        // { fetchMs, auditMs, totalMs }
+console.log(report.meta);                          // { toolVersion, nodeVersion, ... }
+```
+
+### Render an HTML or JSON report directly
+
+```ts
+import { audit } from 'geo-checker';
+import { toHtml } from 'geo-checker/dist/reporters/html.js';
+import { toJson } from 'geo-checker/dist/reporters/json.js';
+
+const report = await audit('https://example.com');
+await fs.writeFile('report.html', toHtml(report));
+await fs.writeFile('report.json', toJson(report));
 ```
 
 ## What gets checked
 
-| Category | What it covers | Weight |
-|---|---|---:|
-| **AI Crawler Access** | HTTPS, robots.txt, AI bot allow-lists (GPTBot, Google-Extended, ClaudeBot, PerplexityBot, CCBot, Amazonbot), `llms.txt`, sitemap.xml | 25 |
-| **Structured Data** | JSON-LD presence & validity, schema.org types (Article, FAQPage, HowTo, Organization, BreadcrumbList, Product), required fields | 30 |
-| **Citation Signals** | title, meta description, canonical, Open Graph, Twitter Card, author, publish/modified dates, `lang` | 25 |
-| **Content Structure** | single H1, heading hierarchy, image alt coverage, TL;DR/FAQ blocks, word count | 20 |
+| Category | Signals | Rules | Weight |
+|---|---|---:|---:|
+| **AI Crawler Access** | HTTPS, robots.txt reachability, **17 AI-bot allow-list** (GPTBot, OAI-SearchBot, ChatGPT-User, Google-Extended, Google-CloudVertexBot, ClaudeBot, anthropic-ai, Claude-Web, PerplexityBot, Applebot-Extended, Meta-ExternalAgent, Bytespider, DuckAssistBot, YouBot, cohere-ai, CCBot, Amazonbot), `llms.txt`, `llms-full.txt`, sitemap.xml | 7 | 25 |
+| **Structured Data** | JSON-LD presence & validity, recognised schema.org types, required-field coverage, microdata/RDFa fallback, no duplicate primary types, `sameAs` knowledge-graph linkage, BreadcrumbList item validity | 8 | 30 |
+| **Citation Signals** | `<title>`, meta description, canonical, Open Graph, Twitter Card, `<html lang>`, author, publish/modified dates, content freshness (dateModified ≤ 1y) | 9 | 25 |
+| **Content Structure** | single `<h1>`, heading hierarchy, image alt coverage, TL;DR / FAQ blocks, word count, Q&A structure for answer extraction, external citations (E-E-A-T) | 7 | 20 |
+
+Every rule declares:
+
+- **`stableId`** — frozen identifier for CI budgets (never renamed).
+- **`impact`** — `critical` / `high` / `medium` / `low`.
+- **`effort`** — `low` / `medium` / `high` (roughly how long the fix takes).
+- **`group`** — `opportunity` (points you can recover) or `diagnostic` (binary signal).
+
+See [`docs/rules.md`](./docs/rules.md) for every rule, why it matters for GEO, and how to fix a failure.
 
-See [`docs/rules.md`](./docs/rules.md) for every individual rule and how to fix a failure.
+## Report schema
+
+```ts
+interface AuditReport {
+  schemaVersion: 1;
+  url: string;
+  finalUrl: string;
+  fetchedAt: string;
+  renderMode: 'static' | 'rendered';
+  overall: number;                                     // 0–100
+  categories: Record<Category, CategoryReport>;
+  warnings: string[];
+  version: string;
+  meta: { toolVersion: string; nodeVersion: string; userAgent?: string };
+  timing: { fetchMs: number; auditMs: number; totalMs: number };
+}
+```
+
+Each audit result carries `stableId`, `impact`, `effort`, `group`, `docsUrl`, and, where applicable, `estimatedImpact` (the points an Opportunity is worth).
 
 ## Extensibility
 
@@ -67,17 +195,67 @@ import { audit, defineRule } from 'geo-checker';
 
 const hasJsonFeed = defineRule({
   id: 'custom.has-json-feed',
+  stableId: 'custom.has-json-feed',
   category: 'crawler',
+  group: 'opportunity',
   weight: 2,
+  impact: 'low',
+  effort: 'low',
   title: 'JSON Feed present',
   description: 'Site should expose a JSON Feed at /feed.json',
+  docsUrl: 'https://example.com/docs/json-feed',
   async run(ctx) {
-    // ...your logic
+    // ...your logic using ctx.$ / ctx.headers / ctx.robots, etc.
     return { status: 'pass', score: 1, rationale: 'JSON feed found' };
   },
 });
 
-await audit('https://example.com', { extraRules: [hasJsonFeed] });
+const report = await audit('https://example.com', { extraRules: [hasJsonFeed] });
+```
+
+Custom rules are merged with the defaults and appear in every reporter automatically.
+
+## CI recipe
+
+```yaml
+# .github/workflows/geo.yml
+name: GEO audit
+on: [push, pull_request]
+jobs:
+  geo:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # for SARIF upload
+      pull-requests: write    # for PR comment
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: |
+          npx -y geo-checker https://staging.example.com \
+            --fail-on warn \
+            --out ./geo \
+            --sarif ./geo/results.sarif \
+            --md ./geo/summary.md
+      - uses: actions/upload-artifact@v4
+        with:
+          name: geo-report
+          path: ./geo
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: ./geo/results.sarif
+      - if: github.event_name == 'pull_request'
+        run: gh pr comment ${{ github.event.pull_request.number }} --body-file ./geo/summary.md
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**Track regressions** by saving last-known-good `report.json` and passing it as `--baseline`:
+
+```sh
+geo-checker https://staging.example.com --baseline ./baselines/main.json --out ./geo
 ```
 
 ## License
@@ -86,4 +264,4 @@ MIT © BaRam-OSS. See [LICENSE](./LICENSE).
 
 ## Contributing
 
-PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+PRs welcome — especially new rules, fixtures, and docs. See [CONTRIBUTING.md](./CONTRIBUTING.md).