geoptimize

geoptimize

English | 繁體中文 | 简体中文 | 日本語 | 한국어 | Español | Français | Deutsch | Português do Brasil

Formerly aeoptimize. This is the same project, continued under the geoptimize name from version 0.8.0. Existing aeoptimize users can follow the migration guide.

Current npm package · Legacy npm package and download history · Last release under the old name

AI crawlers read your pages before humans do. Lint them like code.

geoptimize is a deterministic content-readiness lint for static websites and documentation. It checks reproducible properties such as document structure, sourced quantitative claims, structured-data hygiene, indexing controls, metadata quality, and repetitive wording — locally, in CI, or pre-commit.

https://github.com/user-attachments/assets/5dafd888-92c9-428b-b372-62864c58059a

30-second introduction · Download the MP4 · Video source and credits

Open the offline example · After improvements

It does not predict ranking, indexing, rich results, Google AI Overviews, or citation by ChatGPT, Perplexity, or another AI system. Google states that its AI search features need no special AI text file or schema, and valid structured data does not guarantee a search feature. See methodology and limitations.

Quick start

Requires Node.js 22.12 or newer.

npm install --save-dev geoptimize

npx geoptimize scan https://example.com
npx geoptimize scan ./dist --dir
npx geoptimize scan ./dist --dir --json
npx geoptimize audit https://example.com --json
npx geoptimize audit-site https://example.com --max-pages 20 --json

Version 0.11.0 adds a guided terminal menu for scanning a target and saving an offline HTML report. See the interactive CLI guide for npm install and npx usage; explicit commands remain available for scripts and non-TTY environments.

For measured Google Search experiments, initialize the separate SEO ledger:

geo seo init .
geo seo add . --keyword "energy management system integration" --page /services/ems/ --priority high
geo seo status .

The ledger allows one monitoring experiment at a time and preserves fixed query, page, country, device, search type, and date-window evidence. Start its seven-day review period only after the changed page is publicly deployed and read back. The ledger does not affect the readiness score. See SEO experiment ledger.

Example output:

Content Readiness Report
Score: 71/100

Structure        20/25
Citability       18/25
Schema           16/20
AI Metadata      10/15
Content Density   7/15

The score is a versioned heuristic for catching regressions within the same project. Do not treat it as a percentage chance of search or AI visibility, and do not compare unrelated sites as if it were an outcome metric.

What is scored

Dimension	Max	Scope
Structure	25	Document outline and readability heuristics
Citability	25	Claim specificity, source signals, definitions, attribution
Schema	20	JSON-LD structural hygiene when present; absence is not penalized
AI Metadata	15	Page-level indexing control and description quality
Content Density	15	Content/boilerplate and repetition heuristics

Two often-promoted GEO signals are deliberately excluded from the score:

• FAQ content and FAQPage schema are optional. The generator does not infer FAQ schema from question headings.
• llms.txt is an experimental proposal. Generating or publishing it does not add points.

Every rule, its evidence class, and known false-positive boundary is documented in docs/methodology.md and exercised by the versioned public fixture corpus.

Evidence-backed page audit

audit inspects one public URL or one local HTML/Markdown file. It is a separate, versioned contract and does not change the v0.6 readiness score or scan --json output.

npx geoptimize audit https://example.com
npx geoptimize audit ./dist/index.html --json

The first audit contract checks:

• HTTP status, final URL, and redirect evidence for URL targets;
• document title, meta description, headings, language, canonical, and page-level robots directives;
• discovered links, image alt attributes, and JSON-LD structural validity.

Each check returns PASS, WARNING, FAIL, or N/A, the observed evidence, an explanation, an optional remediation, and a validation step. PASS is bounded to the inspected evidence. It does not establish ranking, indexing, rich-result display, traffic, conversion, or AI citation.

The command intentionally reports unavailable site-wide and external measurements as limitations. It does not infer robots.txt policy, sitemap membership, hreflang reciprocity, broken-link status, Core Web Vitals, analytics, or actual search-engine index state from one page.

Bounded site audit

audit-site follows same-origin links in deterministic order and stops at an explicit page limit. It reads robots.txt before subsequent page requests, discovers same-origin sitemap files, and uses response HTML without browser rendering.

npx geoptimize audit-site https://example.com
npx geoptimize audit-site https://example.com --max-pages 50 --json

The site contract reports bounded crawl coverage, robots policy, page status, redirect chains, internal link targets, canonical consistency, sitemap discrepancies, sitemap-only orphan candidates, and duplicate titles. Sitemap-only pages remain candidates until a sufficiently complete crawl or server-log evidence confirms their discovery state.

The default limit is 20 page requests and the accepted range is 1–200. Cross-origin page links are recorded only as counts, and subsequent redirects outside the audited origin are not followed. JavaScript-inserted links, actual search-engine crawl/index state, rankings, traffic, and conversions remain outside this contract.

Visual report

Keep the original total and all five readiness dimensions together with page-score and severity charts. Add site-audit data for HTTP charts, canonical/link/sitemap observations, and baseline comparisons. Search individual pages or expand findings to inspect evidence and suggested actions.

geo scan ./dist --dir --details --json > readiness.json
geo audit-site https://example.com --max-pages 50 --json > site.json
geo report readiness.json --site site.json --output report.html
# Add --baseline previous-readiness.json for score and source comparisons.
# Add --baseline-site previous-site.json for comparable site-count charts.

Detailed scans include original rule results and a source excerpt of up to 6000 characters per page. Review captured source before sharing. Reports without details still open, with unavailable rule/source evidence labeled explicitly.

Click score distributions to filter pages, or a severity label to inspect those scoring findings. Site finding controls expose the complete affected target list. Open a dimension to inspect rule points and diagnostics. A compatible readiness baseline adds total/dimension changes and captured before/after source excerpts.

Open the resulting HTML in a browser. It works offline with no external fonts, scripts, or analytics. Existing output files are preserved; choose a new filename for another report. The scoring algorithm is unchanged. Readiness and site audit scope/timestamps remain visible because the two inputs can cover different pages.

The example reports use the same synthetic HTML for readiness and site audits. In a repository checkout, generate them with node scripts/prepare-metrics-demo.mjs <empty-directory> after building. Browser checks run with node scripts/verify-visual-report.mjs <directory>; set GEO_CHROME to a Chrome executable on platforms outside macOS.

Site metrics and scan comparisons

Summarize the site audit into 19 observed counts, including HTTP failures, redirects, internal link targets, canonical findings, sitemap discrepancies and duplicate titles. Save each scan to a new JSON file to retain its timestamp and evidence.

geo audit-site https://example.com --max-pages 50 --json > before.json
# After updating the site, scan the same URL with the same limit.
geo audit-site https://example.com --max-pages 50 --json > after.json
geo metrics after.json --baseline before.json
geo metrics after.json --baseline before.json --json

The comparison lists count differences and new, persisting, and no-longer-observed findings. An absent observation needs evidence review before calling it a repair. Changes in origin, start URL, page limit, crawled URL set, or metric evidence version suppress deltas. Partial crawls, robots skips, unavailable requests, and a newer baseline also suppress comparison. Absolute counts remain available.

Counts use complete evidence, even when the detailed audit displays only 20 sample URLs. Older reports without complete counts display Not measured. Queue completion is bounded discovery, so no whole-site coverage percentage is inferred. AI mentions, citations, traffic and conversions require separate collection and remain unmeasured.

The terminal demo uses a synthetic three-page fixture with actual audit output. To reproduce it after building, run vhs docs/assets/demo.tape. The preparation script also accepts an empty output directory for inspecting readiness and site JSON reports plus the interactive HTML examples without VHS.

How it compares

	geoptimize	Lighthouse-style SEO audits	Hosted GEO platforms
Question it answers	Is this content machine-readable and citable?	Does the page pass classic SEO checks?	Did my AI visibility change this week?
Deterministic	Yes — versioned rules, fixture-tested	Partially	No — model output varies run to run
Runs where	Local CLI, CI, pre-commit hook, Vite/Next plugins	Browser / DevTools	Vendor cloud
Blocks regressions in CI	Yes, via a stable --json contract	Possible with extra wiring	Rarely
Cost	Free, MIT	Free	Varies by vendor

Visibility trackers answer "did rankings change?". geoptimize answers the question you can act on in a pull request: "is this page ready?". The two compose rather than compete.

CI contract

--json is the stable automation surface. A non-zero threshold is useful only after your team reviews the baseline and accepts the current methodology version.