{"version":"2026-07-03","name":"Visa Atlas SEO/GEO visibility measurement contract","description":"Public measurement contract for separating Google organic growth, AI citation share, crawler access, source freshness, index quality and technical trust gates.","license":"CC BY 4.0","attribution":"Visa Atlas","trafficModel":{"planningTargetMonthlyVisits":500000,"planningWindow":"24 months","range":{"low":390000,"high":600000},"note":"This is a planning model, not a current traffic claim. The target depends on earned authority, original datasets, citation share, and clean index quality."},"count":9,"cohortCount":5,"statusCounts":{"instrumented":9,"partially-instrumented":0,"roadmap":0},"metrics":[{"id":"ai-citation-share","label":"AI citation share","category":"geo","status":"instrumented","target":"At least 40% of fixed benchmark answers cite visaatlas.org.","whyItMatters":"Answer engines can satisfy informational queries without a click; citation share measures whether Visa Atlas is becoming the named source.","evidenceSurfaces":["/citation-benchmark","/api/public/citation-benchmark","/answer-capsules","/api/public/answer-capsules","/research/canada-express-entry-category-tracker","/api/public/express-entry-categories","/ai-agents"],"commands":["npm run kpi:citation-share","npm run kpi:citation-share:perplexity","npm run kpi:citation-accuracy"],"cadence":"Monthly, plus after major data/report launches.","caveats":["Runs offline with user-provided API keys; the website never calls an LLM at runtime.","Citation detection looks for the configured brand domain in structured citations or answer text.","Accuracy grading is conservative answer-key triage; partial or failed rows require human review before publication."]},{"id":"crawler-access","label":"AI/search crawler access","category":"geo","status":"instrumented","target":"Known search and AI crawler user agents are allowed and visible in server logs when they crawl.","whyItMatters":"GA4 cannot see crawler fetches. Server logs are the only honest way to separate crawler access from referral traffic.","evidenceSurfaces":["/robots.txt","/research/crawler-ai-retrieval-access-audit-2026","/api/public/crawler-access","/ai-agents","/llms.txt","/llms-full.txt"],"commands":["npm run audit:botlog","npm run seo:botlog -- logs.txt","npm run seo:botlog -- logs.txt --json","npm run audit:visibility-metrics"],"cadence":"Monthly and after robots, middleware, CDN or hosting changes.","caveats":["Gemini training crawls can appear as Googlebot; Google-Extended is a robots token, not a user-agent.","User-agent strings can be spoofed, so log classification is directional rather than forensic proof.","The bot-log parser is regression-tested against the public crawler-access policy, but live counts require user-supplied server logs."]},{"id":"source-freshness","label":"Source freshness","category":"trust","status":"instrumented","target":"Zero stale or invalid dated source records in the public freshness report.","whyItMatters":"Freshness is the core wedge against stale immigration blogs and model training cutoffs.","evidenceSurfaces":["/freshness","/api/public/freshness","/methodology"],"commands":["npm run audit:stale","npm run audit:freshness"],"cadence":"Every build and before publishing major research or policy-change assets.","caveats":["A stale record does not prove the government fact is wrong; it means the Visa Atlas review date exceeded the public SLA.","High-risk legal and fee changes still require source verification before publication."]},{"id":"open-data-discoverability","label":"Open-data discoverability","category":"geo","status":"instrumented","target":"Every public data asset is listed in /data, /api/public, DataCatalog/Dataset JSON-LD, API Link headers and LLM discovery files.","whyItMatters":"The site wins by being the reusable source layer that journalists, researchers and answer engines can cite.","evidenceSurfaces":["/data","/api/public","/api","/api/openapi.json","/use-our-data","/research/topical-authority-internal-link-map-2026","/api/public/topical-authority-map","/research/seo-geo-audit-evidence-pack-2026","/api/public/seo-geo-audit-evidence","/research/seo-geo-execution-readiness-scorecard-2026","/api/public/execution-readiness","/research/search-demand-action-map-2026","/api/public/search-demand-actions","/research/crawler-ai-retrieval-access-audit-2026","/api/public/crawler-access","/answer-capsules","/api/public/answer-capsules","/research/publisher-citation-kits-2026","/api/public/publisher-citation-kits","/research/authority-distribution-plan-2026","/api/public/authority-distribution-plan","/research/external-data-repository-mirrors-2026","/api/public/external-repository-mirrors","/research/knowledge-graph-entity-seeding-2026","/api/public/knowledge-graph-entities","/research/expert-reviewer-entity-program-2026","/api/public/expert-reviewer-entities","/research/reviewedby-schema-rollout-2026","/api/public/reviewedby-schema-rollout","/research/high-risk-page-review-acquisition-2026","/api/public/high-risk-page-review-acquisition","/research/p0-reviewed-page-refresh-2026","/api/public/p0-reviewed-page-refresh"],"commands":["npm run audit:data-front-door","npm run audit:openapi","npm run audit:topical-authority-map","npm run audit:seo-geo-audit-evidence","npm run audit:execution-readiness","npm run audit:search-demand-actions","npm run audit:data-citation","npm run audit:answer-capsules","npm run audit:authority-distribution","npm run seo:authority-distribution -- authority-distribution-log.jsonl --json","npm run seo:publisher-citation-kits -- outreach-log.jsonl --json","npm run export:repository-mirrors","npm run seo:repository-mirrors -- repository-mirror-log.jsonl --json","npm run seo:knowledge-graph -- kg-entity-log.jsonl --json","npm run export:knowledge-graph -- kg-entity-log.jsonl","npm run seo:expert-reviewers -- reviewer-evidence-log.jsonl --json","npm run export:reviewedby-schema -- reviewer-evidence-log.jsonl","npm run seo:review-acquisition -- reviewer-acquisition-log.jsonl --json","npm run seo:p0-page-refresh -- p0-reviewed-page-refresh-log.jsonl --json"],"cadence":"Every build and whenever a public endpoint is added.","caveats":["Open data helps competitors only if they can match freshness and provenance; attribution turns reuse into entity signals.","A dataset is included only when its source chain and reuse terms are visible."]},{"id":"rendered-seo-surface","label":"Rendered SEO/GEO surface","category":"technical","status":"instrumented","target":"Representative built pages expose canonical URLs, Article/Dataset schema, citations, source dates and no misleading ClaimReview.","whyItMatters":"Source-template checks are not enough; crawlers and AI retrievers consume the static HTML and JSON produced by the build.","evidenceSurfaces":["/api/public","/data","/research/technical-seo-control-plane-2026","/api/public/technical-seo-controls","/research/topical-authority-internal-link-map-2026","/api/public/topical-authority-map","/research/seo-geo-audit-evidence-pack-2026","/api/public/seo-geo-audit-evidence","/research/seo-geo-execution-readiness-scorecard-2026","/api/public/execution-readiness","/research/search-demand-action-map-2026","/api/public/search-demand-actions","/citation-packs","/answer-capsules","/freshness","/widgets"],"commands":["npm run audit:seo-geo","npm run audit:technical-seo-controls","npm run audit:topical-authority-map","npm run audit:seo-geo-audit-evidence","npm run audit:execution-readiness","npm run audit:search-demand-actions","NEXT_PUBLIC_SITE_URL=https://visaatlas.org npm run build","npm run audit:rendered-seo"],"cadence":"Every production build.","caveats":["The release gate is local by default; run it with --include-liveness when network source checks are required.","The rendered audit checks representative artifacts; broad source audits cover the rest of the templates.","The audit is a regression gate, not a ranking guarantee."]},{"id":"index-quality","label":"Index quality and thin-page control","category":"seo","status":"instrumented","target":"No known thin page classes indexed without unique sourced value.","whyItMatters":"The 500k/month target depends on a clean index; thin permutations can suppress genuinely useful pages.","evidenceSurfaces":["/sitemap.xml","/compare","/professions","/from/indian/to/uk"],"commands":["npm run audit:thin","npm run audit:noindex","npm run audit:longtail-provenance"],"cadence":"Every build and before adding new programmatic page cohorts.","caveats":["A noindex guard is a trust-preserving choice when unique sourced value is not available.","Re-expansion should be earned by adding verified corridor, profession or comparison data."]},{"id":"competitor-wedge-proof","label":"Competitor wedge proof","category":"trust","status":"instrumented","target":"The public positioning claim is backed by a reusable sampled benchmark with explicit caveats.","whyItMatters":"A Big4-style review should be able to inspect the competitor/wedge claim without relying on private strategy notes.","evidenceSurfaces":["/research/immigration-source-transparency-benchmark-2026","/api/public/source-transparency-benchmark","/research/competitor-query-battlecards-2026","/api/public/competitor-query-battlecards","/answer-capsules","/api/public/answer-capsules","/mcp","/methodology"],"commands":["npm run audit:source-transparency","npm run audit:competitor-query-battlecards","npm run audit:mcp","npm run audit:trust-surface"],"cadence":"Quarterly, or whenever major competitor surfaces materially change.","caveats":["The benchmark is a public-surface sample, not a full forensic audit of competitors.","Not-observed means the feature was not visible in sampled public pages."]},{"id":"gsc-cohort-reporting","label":"GSC cohort reporting","category":"seo","status":"instrumented","target":"Track clicks, impressions, CTR and average position by page cohort: calculators, data, research, core route reference pages, corridors, professions and comparisons.","whyItMatters":"A site can grow impressions while losing CTR. Cohort reporting separates ranking, clickability and index-quality effects.","evidenceSurfaces":["/research","/research/ai-retrieval-readiness-scorecard-2026","/api/public/ai-retrieval-readiness","/research/ai-retrieval-task-index-2026","/api/public/ai-retrieval-task-index","/research/seo-geo-page-action-map-2026","/api/public/seo-geo-page-action-map","/research/quarterly-market-share-evidence-summary-2026","/api/public/quarterly-market-share-summary","/research/battlecard-search-experiments-2026","/api/public/battlecard-search-experiments","/research/competitor-query-battlecards-2026","/api/public/competitor-query-battlecards","/research/publisher-citation-kits-2026","/api/public/publisher-citation-kits","/research/authority-distribution-plan-2026","/api/public/authority-distribution-plan","/research/external-data-repository-mirrors-2026","/api/public/external-repository-mirrors","/research/knowledge-graph-entity-seeding-2026","/api/public/knowledge-graph-entities","/research/expert-reviewer-entity-program-2026","/api/public/expert-reviewer-entities","/research/reviewedby-schema-rollout-2026","/api/public/reviewedby-schema-rollout","/research/high-risk-page-review-acquisition-2026","/api/public/high-risk-page-review-acquisition","/research/p0-reviewed-page-refresh-2026","/api/public/p0-reviewed-page-refresh","/data","/calculators","/compare","/professions","/visibility-metrics"],"commands":["npm run seo:gsc-cohorts -- gsc-pages.csv --json --period-start=YYYY-MM-DD --period-end=YYYY-MM-DD --property-label=gsc-domain-redacted --search-type=web","npm run audit:ai-retrieval-readiness","npm run audit:seo-geo-page-action-map","npm run audit:gsc-opportunities","npm run seo:gsc-opportunities -- gsc-queries.csv --json --period-start=YYYY-MM-DD --period-end=YYYY-MM-DD --property-label=gsc-domain-redacted --search-type=web","npm run seo:gsc-battlecard-experiments -- gsc-queries.csv --json --period-start=YYYY-MM-DD --period-end=YYYY-MM-DD --property-label=gsc-domain-redacted --search-type=web","npm run seo:gsc-experiment-outcomes -- gsc-experiment-outcomes.jsonl --json","npm run seo:surface-snapshots -- snapshots.jsonl --json","npm run seo:market-share-summary -- surface-summary.json --json","npm run seo:market-share-proof -- market-share-proof.json --json","npm run seo:repository-mirrors -- repository-mirror-log.jsonl --json","npm run seo:knowledge-graph -- kg-entity-log.jsonl --json","npm run seo:expert-reviewers -- reviewer-evidence-log.jsonl --json","npm run export:reviewedby-schema -- reviewer-evidence-log.jsonl","npm run seo:review-acquisition -- reviewer-acquisition-log.jsonl --json","npm run seo:p0-page-refresh -- p0-reviewed-page-refresh-log.jsonl --json"],"cadence":"Monthly from a Search Console Pages export, and after major page-cohort launches.","caveats":["Runs locally on a user-supplied Search Console export with a declared period, redacted property label and search type; no private analytics are exposed in this public contract.","The public cohort taxonomy is now fully wired to the 48-prompt retrieval scorecard and 118-page SEO/GEO action map; live traffic proof still requires a reviewed private export.","Battlecard outcome claims require reviewed aggregate rows with matched baseline/comparison scope, redacted query rows and local-only raw export storage.","Stable-rank CTR should be analysed separately from rank movement.","Query-level opportunity backlogs are local working files and should not be committed."]},{"id":"ai-referral-attribution","label":"AI referral attribution","category":"geo","status":"instrumented","target":"Separate AI crawler access, AI answer citations and AI referral sessions instead of treating them as one metric.","whyItMatters":"AI visibility can improve before referral clicks arrive, and clicks can fall when answer engines cite the site directly. AI referral sessions are browser visits from AI products, not crawler hits.","evidenceSurfaces":["/citation-benchmark","/research/canada-express-entry-category-tracker","/ai-agents","/api/public/visibility-metrics"],"commands":["npm run seo:ai-referrals -- analytics-referrers.csv --json --period-start=YYYY-MM-DD --period-end=YYYY-MM-DD --property-label=ga4-redacted --bot-filtered","npm run kpi:citation-share","npm run seo:botlog -- logs.txt --json"],"cadence":"Monthly.","caveats":["Runs locally on a user-supplied analytics/referrer export with a declared period, redacted property label and bot-filter confirmation; private sessions are not published in this public dataset.","Crawler logs and citation-share logs are complementary, not interchangeable.","Answer engines may cite Visa Atlas without sending a referral click."]}],"cohorts":[{"id":"calculators-tools","label":"Calculators and tools","purpose":"High-intent user tasks where a click remains valuable because the answer is profile-specific.","representativePaths":["/calculators","/calculators/canada-crs","/calculators/germany-chancenkarte","/widgets"],"primaryKpis":["ai-citation-share","rendered-seo-surface","gsc-cohort-reporting"]},{"id":"data-reference","label":"Data reference pages","purpose":"Citable fee, salary, processing, cost and freshness surfaces that answer engines can lift safely.","representativePaths":["/data","/answer-capsules","/fees","/salary-thresholds","/processing-times","/cost-to-complete","/freshness"],"primaryKpis":["source-freshness","open-data-discoverability","rendered-seo-surface","gsc-cohort-reporting"]},{"id":"research-reports","label":"Original research and benchmarks","purpose":"Press, citation and backlink assets computed from the verified data layer.","representativePaths":["/research","/research/skilled-migration-cost-index-2026","/research/immigration-rule-changes-2026","/research/canada-express-entry-category-tracker","/research/immigration-source-transparency-benchmark-2026","/research/quarterly-market-share-evidence-summary-2026"],"primaryKpis":["open-data-discoverability","competitor-wedge-proof","gsc-cohort-reporting"]},{"id":"long-tail-navigation","label":"Long-tail route, corridor, profession and comparison pages","purpose":"Indexable long-tail demand only where each page carries unique source-backed value.","representativePaths":["/compare","/compare/uk/vs/us","/professions/software-engineer/in/germany","/from/indian/to/uk"],"primaryKpis":["index-quality","rendered-seo-surface","gsc-cohort-reporting"]},{"id":"core-route-reference","label":"Core visa, country and policy reference pages","purpose":"Primary evergreen immigration routes and policy pages where search demand is broad and source accuracy matters.","representativePaths":["/visas","/visas/uk/skilled-worker","/policy-updates","/orgs/home-office","/english-tests"],"primaryKpis":["source-freshness","rendered-seo-surface","gsc-cohort-reporting"]}]}