GEO remediation: correct llms.txt, restore the docs link graph, enrich schema - #672
Merged
Conversation
llms.txt never mentioned Snowflake, BigQuery or Databricks, omitted the WAREHOUSE engine family, and listed only /docs/ instead of the twelve rendered chapter URLs - so AI crawlers grounding on it answered warehouse questions wrongly and could not reach the chapters. All twelve docs pages linked the hub as href="index.html", which Cloudflare 307-redirects to the directory. On the eleven sub-directory pages those were self-redirects, leaving /docs/ with no inbound internal links. Also enrich the JSON-LD graph (Organization sameAs/description/foundingDate, SoftwareApplication featureList and install metadata, a WebPage node, datePublished on every TechArticle), render a Last updated date on each docs page, add question-form headings with self-contained answers, tabulate the engine matrix and review-plan settings, and add a homepage Common questions section. No FAQPage schema - Google retired FAQ rich results in May 2026.
The four guards protecting website/ live in the frontend suite — the CSP script hash, cross-chapter nav/footer consistency, security.txt expiry, and the docs anchor contract. The frontend job's paths-filter only matched frontend/**, so a PR touching website/ alone skipped the job and shipped past every guard, including the one added to catch exactly that drift.
Contributor
Contributor
Coverage Report for Frontend Coverage (frontend)
File CoverageNo changed files found. |
Contributor
Backend Test Results5 592 tests 5 592 ✅ 17m 36s ⏱️ Results for commit 79dbb8a. |
Contributor
Backend Code Coverage
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Acts on a GEO (Generative Engine Optimization) audit of https://accessflow.bablsoft.com/ — 65/100. Two of the findings are drift against rules already in
CLAUDE.md, not new advice.Score before
<table>across 13 pagesWhat it is.pattern in docs; no Q&A, no glossary, no citable statisticssameAs, nodatePublished, no rendered date anywherePlatform split: Google AI Overviews ~62 · AI Mode ~58 · Bing Copilot ~60 · ChatGPT ~35 · Perplexity ~30. The ChatGPT/Perplexity gap is entirely off-site (they cite Wikipedia 47.9% / Reddit 46.7%) and is out of scope here — no code change moves it.
The two defects
llms.txtmisstated the product. It is the file AI crawlers ground on, and it never mentioned Snowflake, BigQuery or Databricks — 12 homepage mentions each — omitted theWAREHOUSEfamily entirely, and listed only/docs/instead of the twelve rendered chapter URLs, so a crawler reading it could not reach the chapters at all. An AI system answering "does AccessFlow support Snowflake?" from this file got it wrong.The docs link graph was broken. All 12 docs pages linked the hub as
href="index.html". Cloudflare 307-redirects…/index.htmlto the directory (verified live:/docs/configuration/ai/index.html→ 307), so on the 11 sub-directory pages these were self-referential redirect hops — and/docs/had zero inbound internal links from any chapter.CLAUDE.mdalready bans this ("never../index.html, which costs a 307 redirect hop"); the docs sidebar ToC gets it right with absolute paths, so this was drift.What changed
llms.txtwarehouse enginesWAREHOUSEfamilyllms.txtdocs links/docs/)href="index.html"<table>elementsOrganization.sameAsSchema:
OrganizationgainedsameAs/description/foundingDate;SoftwareApplicationgainedfeatureList,softwareRequirements,downloadUrl,installUrl,softwareHelp,isAccessibleForFree,datePublished; a newWebPagenode dates the homepage itself; everyTechArticlegaineddatePublished+articleSection.New content: a homepage
Common questionssection (6 Q&As, wired into nav + footer on all 13 pages), an 18-engine matrix in the connectors chapter (engine / family / query language / row-security / install), and a review-plan settings table.Deliberate non-goals
FAQPageschema. Google retired FAQ rich results for all sites in May 2026 — the Q&A ships as content only. NoHowToeither (deprecated 2023).sameAslists only the two URLs that return 200 (GitHub org + repo). No invented LinkedIn/X/Wikidata entries — those become realsameAstargets once the profiles exist.aggregateRating— there are no real ratings to cite./docs/faq/page would have needed wiring intodocs.ts,LEGACY_DOCS_ANCHORS,sitemap.xmland the hub nav, and would start with no ranking history. ~44% of AI citations come from the first 30% of a page, so the homepage was the better host.Second commit: the guards did not cover this
79dbb8a7is a one-line paths-filter fix. The four guards protectingwebsite/live in the frontend suite — CSP script hash, cross-chapter nav/footer consistency,security.txtexpiry, and the docs anchor contract — but the frontend job only matchedfrontend/**. A website-only PR skipped the job and shipped past every one of them, including the guard added in #670 to catch exactly this kind of drift. This PR would itself have gone unverified.Verification
frontend/src/config/__tests__/— 55/55 pass, including all four website guards. Plus, across all 13 pages: 0 staleindex.htmllinks, every JSON-LD block parses, every file tag-balanced, every meta description ≤160 rendered chars, rendered<time>/ JSON-LDdateModified/sitemap.xml<lastmod>all consistent, and the CSP inline-script hash byte-identical in both files and matching_headers.Needs a human after deploy
curl -sSI https://accessflow.bablsoft.com/docs/configuration/ai/→ 200, and nothing on the site should link the…/index.htmlform that returns 307. Only verifiable post-deploy.One unresolved discrepancy (not fixed here)
The homepage roadmap lists automated sensitive-data discovery under Planned, while
CLAUDE.mddocuments it as a shipped module (AF-623) with a full env-var reference. I kept it out ofllms.txtrather than overstate the product. One of the two sources needs correcting — that is a content decision, not an SEO one.