ai-visibility-readiness
The AI Visibility Readiness (AVR) Framework v1.1.0 — a transparent, tiered audit methodology for measuring whether a website is ready for traditional search AND for AI-powered search (Google AI Mode, AI Overviews, Perplexity, ChatGPT, Claude, Gemini, Microsoft Copilot).
Authored by Chudi Nnorukam. Implemented by citability.dev. Demonstrated on chudi.dev as the canonical case study.
The check list lives in CHECKS.md, generated directly from
the audit code. It is the only place the list is written down. Every other
page, including https://chudi.dev/framework, links to it rather than
restating it. Narrative methodology lives in FRAMEWORK.md.
What AVR measures
See CHECKS.md for every check, its slug, and its evidence
label. That file is generated by scripts/generate_checks_md.py from two code
sources, so it cannot disagree with what actually runs.
Every check is labelled [CHECKED] (a deterministic HTTP/HTML probe with
primary-source evidence) or [ESTIMATED] (a polled AI engine response subject
to sampling variance). The framework never fakes a combined "AI Visibility
Score" by averaging signals that measure different things.
Sections are identified by string id (section_fact_block_density), not by
number. The old numeric scheme was dropped in favour of string ids after two
different sections were both documented as "Section 5"; numbers that live only
in prose collide silently, ids declared in code cannot.
Fact-Block Density, Agent Readiness, and Citation Decay Rate are the additions
that no other AI visibility tool (Semrush, BrightEdge, Conductor, Otterly,
Profound, Peec AI, LLMrefs, Knowatoa) tracked as of 2026-05-22.
Why v1.1.0 exists
Five things changed in May 2026 that broke v1.0:
- Google I/O 2026 disclosed that AI Mode has surpassed one billion monthly users with queries thrice as long as traditional ones and follow-up queries increasing 40% monthly in the U.S. [Source: SearchEngineJournal SEO Pulse, May 2026]
- Ahrefs measured a 58% CTR reduction on queries with AI Overviews across 300,000 keywords (December 2025 data). Position-one CTR for AIO-triggering keywords fell from 0.073% to 0.016%. [Source: Ahrefs blog]
- Over 16% of searches are multimodal (voice, images, video input). [Source: SearchEngineJournal]
- Google's AI guide reversed the llms.txt recommendation: "Google's AI guide states llms.txt isn't needed for AI Search." John Mueller: "markdown pages are useful for documentation but not for most websites." Lighthouse 13.3 now flags
llms.txt as an ERROR by default. [Source: SearchEngineJournal]
- March 2026 Core Update raised E-E-A-T cross-platform corroboration as the load-bearing trust signal: "the more places a person's name appears in connection with a subject area, the stronger the E-E-A-T signal for content they author on your domain." [Source: Evertune, April 8 2026]
AVR v1.0 treated Google AI surfaces as secondary, recommended llms.txt as a §2 requirement, and audited E-E-A-T at surface level. All three positions are now wrong. v1.1.0 fixes them.
Quick start
git clone https://github.com/ChudiNnorukam/ai-visibility-readiness.git
cd ai-visibility-readiness
pip install -r scripts/requirements.txt
# Free 5-section audit (1+2+6+7+8). No API spend.
python3 scripts/run_audit.py YOUR_URL --skip-lighthouse --full-v11
# Full 8-section audit with live AI polling.
python3 scripts/run_audit.py YOUR_URL --skip-lighthouse --live-test --full-v11 \
--brand "Your Brand" \
--owner "Owner Name" \
--topics "topic1" "topic2" \
--concepts "your unique concepts" \
--products "your products"
Outputs land in sample-audits/audit_<domain>_<timestamp>.md plus per-section .json files.
section_webmcp_agent_readiness — Agent Readiness (WebMCP + A2A AgentCard)
Checks three things:
/.well-known/webmcp manifest exists, validates as JSON, declares ≥1 tool with required fields (name, description). Spec: WebMCP W3C draft, shipping in Chrome 146 Canary behind chrome://flags "WebMCP for testing"./.well-known/agent.json AgentCard (A2A protocol) exists, validates, declares skills. Optional for non-agent sites; absence is not penalized.- Wire-protocol probe — each endpoint declared in the manifest resolves to a non-404 response on
OPTIONS or HEAD. Tool invocation is not tested (would risk side effects).
Verdict: AGENT-READY requires W1 PASS + (W2 PASS OR optional). AGENT-PARTIAL is W1 OR W2 alone. AGENT-NOT-READY is neither.
section_fact_block_density — Fact-Block Density + Content Extractability
Reports a section result as points out of 100 across five weighted checks (a per-page section result, not an AVR axis):
| Check | Weight | What it measures |
|---|
| F1: First-sentence-of-H2 standalone-answer compliance | 30 | Does each H2 open with a sentence that stands alone? (Patel's rule) |
| F2: First-200-tokens direct-answer | 20 | Does the page opening directly answer the core query? |
| F3: 40-60 word direct-answer band per H2 | 20 | Are H2 opening paragraphs in the AI-extractable length band? |
| F4: H2/H3 question-format rate | 20 | Are headings phrased as questions users type? |
| F5: FAQ section present | 10 | Is there an FAQ near the article tail? |
Verdict: EXTRACTABLE ≥75 + ≥4/5 checks. PARTIALLY-EXTRACTABLE 40-74 + ≥2/5. NOT-EXTRACTABLE otherwise.
section_citation_decay — Citation Decay Rate (the moat metric)
Consumes the Bing AI Performance Report CSV exported from bing.com/webmasters → AI Performance Report → Export CSV. Computes:
- Citation Decay Rate: per-window aggregate decline percentage (early 2 weeks avg vs late 2 weeks avg)
- Citation half-life: days from peak week to a sustained 4-week below-50% window. Returns null if undecayed. (Tune ratified 2026-05-22 to suppress false positives on growing data.)
- Decay slope: linear regression slope of citations/day
- Displacement event count: week-over-week drops > 1.5σ of weekly delta
- Citation Retention Rate: latest 30 days / earliest 30 days
First-to-market metric (checked 2026-05-22 across 8 competitor public surfaces).
Case-study evidence
Updated 2026-05-23 after the 5-page Fact-Block remediation arc + card-title demotion arc completed. All 5 audited chudi.dev URLs reach EXTRACTABLE; citability.dev maintains AGENT-READY 3/3 with meaningful W3 endpoint resolution. The CI workflow at .github/workflows/avr-fact-block-audit.yml (in chudi-blog) now hard-fails any post-deploy regression below EXTRACTABLE on any of the 5 URLs.
| Site | §2.7 Agent Readiness | §7 Fact-Block | §8 Citation Decay |
|---|
| chudi.dev | AGENT-READY 3/3 | 100/100 EXTRACTABLE (was 40) | GROWING (retention 1.65) |
| chudi.dev/framework | AGENT-READY 3/3 | 100/100 EXTRACTABLE (was 51) | (uses Bing data) |
| chudi.dev/about | (not audited) | 88/100 EXTRACTABLE (was 72) | (uses Bing data) |
| chudi.dev/blog | (not audited) | 100/100 EXTRACTABLE (was 20) | (uses Bing data) |
| chudi.dev/topics | (not audited) | 80/100 EXTRACTABLE (was 0) | (uses Bing data) |
| citability.dev | AGENT-READY 3/3 (meaningful endpoints) | 50/100 PARTIALLY-EXTRACTABLE | GROWING |
All verdicts checked on production 2026-05-22 to 2026-05-23. Full reports in sample-audits/audit_chudi.dev_20260523_070001.md and sample-audits/audit_citability.dev_20260523_070001.md. The card-title demotion commit (chudi-blog 46668ff9) was the unlock for chudi.dev root — it moved 6 statement <h2>/<h3> card titles to <p role="heading" aria-level=N> so the audit's heading extraction no longer counts dynamic card text against the F4 question-rate denominator. Visual styling and screen-reader ARIA semantics preserved.
CI hard-fail status
chudi-blog ships a GitHub Action at .github/workflows/avr-fact-block-audit.yml (added 2026-05-23) that triggers on deployment_status: success with environment: Production, clones ai-visibility-readiness, audits the 5 chudi.dev URLs in the table above, posts an avr-fact-block-density commit status check, and EXITS NON-ZERO if any URL drops below EXTRACTABLE. Flipped from fail-soft to hard-fail on chudi-blog commit c548df2d after all 5 URLs reached EXTRACTABLE. Any deploy that regresses below the baseline will surface in the GitHub commit timeline + the workflow run summary.
Tests
pytest tests/ -v
tests/test_section_citation_decay.py exercises the §8 algorithm with 12 hermetic scenarios covering verdict band transitions + unit-level half-life behavior + ancillary metrics. tests/test_section5_off_site_authority.py exercises §2.6 Phase 1 (Wikipedia + Wikidata + sameAs).
Methodology pin
The v1.1.0 release described in this README shipped 2026-05-22. Re-check cadence:
monthly for WebMCP / A2A (spec is moving); quarterly for Fact-Block, Multimodal,
Topic Cluster (content-quality signals stable); one-shot for llms.txt
reclassification (v1.0 → v1.1.0 inversion is settled).
Known issue: two version lineages share the number v1.1.0
FRAMEWORK.md records its own lineage: v1.0.0 (2026-03-31), v1.1.0 (2026-04-05,
removed the llms.txt check), v1.2.0 (2026-04-21, added Wilson intervals and the
overlays). This README's v1.1.0 shipped 2026-05-22, which is later than that
v1.2.0 but carries a lower number, because the numbering was restarted rather
than continued.
Both numbers are therefore ambiguous on their own, and neither is a reliable way
to say what a given audit ran. Until the lineages are reconciled into one
sequence, cite CHECKS.md and a commit SHA, not a version
number. CHECKS.md is generated from code and cannot drift; the version numbers
already have.
Repo layout
scripts/
run_audit.py # main entry point; --full-v11 flag
seo_foundation.py # numbered checks 1.x
ai_readiness.py # numbered checks 2.x
citation_auto.py # section_citation_monitoring (live; needs OPENAI_API_KEY)
visibility_auto.py # section_ai_visibility (live)
calibration.py # section_calibration_receipt
section5_off_site_authority.py # section_off_site_authority (separate from main flow)
section_webmcp_agent_readiness.py # section_webmcp_agent_readiness
section_fact_block_density.py # section_fact_block_density
section_citation_decay.py # section_citation_decay
report_generator.py # Markdown report renderer
tests/
test_section_citation_decay.py # 12 hermetic scenarios
test_section5_off_site_authority.py # §2.6 Phase 1 mock-based
sample-audits/
audit_<domain>_<timestamp>.md # report deliverable
audit_<domain>_<timestamp>_*.json # per-section structured data
License + contact
Contact: [email protected]. Methodology canonical reference: chudi.dev/framework. Audit deliverable demo: citability.dev.
