docs(site): titles, descriptions and structured data for search and answer engines

[imran-siddique]

A crawl of every agentrust-io.com page on 2026-09-14 found three titles still leading with governance, nine descriptions over 160 characters, og:title that did not match the page title on 7 of 11 pages, a static catalog with no social tags, and five pages with no structured data. Search results truncate long descriptions, and answer engines read titles, descriptions and JSON-LD to decide what a page is. This fixes each and adds checks so they stay fixed.

Titles

• /community/: "Community, Partners and Governance" is now "Community: Partners, Sponsor and Contributors". The page's H1 is "The people and organisations behind AgenTrust".
• /demos/: "Model Weight Protection and Agent Governance Demos" (62 characters with the suffix) is now "Runnable Demos: Model Weights and Agent Actions" (59). The page's two sections are Model weights and Agent actions.
• /telemetry/: "Portable Governance Telemetry for AI Agents" is now "Telemetry and Evidence Events for Agent Runtimes" (60). The H1 changes from "Portable governance telemetry for AI-agent runtimes" to "Portable telemetry and evidence for AI-agent runtimes", and the JSON-LD description drops "governance".
• /marketplace/: "AgenTrust Marketplace: Build with the Verifiable Agent Ecosystem" (64, no suffix) is now "Marketplace: Integrations for Verifiable AI | AgenTrust" (55).

Descriptions, old length to new

• Home 191 to 153, /community/ 203 to 155, /demos/ 186 to 153, /extensions/ca2a/v0.1/ 189 to 159, /go/ 188 to 160, /quickstart/ 260 to 150, /registry/ 191 to 151, /telemetry/ 279 to 160, /verify/ 223 to 155, and /search/ (noindex) 167 to 138.
• Each keeps its limit statement where it had one: software mode on /quickstart/, key trust and witnesses on /registry/, nothing uploaded on /verify/, no special hardware on /demos/.
• og:description and twitter:description now repeat the meta description on every page. Several pages had three different texts for the same page.

Social titles. One rule: og:title and twitter:title are the title without " | AgenTrust". The homepage title has no suffix, so its og:title is now "AgenTrust: Open Specifications for Verifiable AI" instead of the hero line. tools/DISCOVERY.md states the rule.

Structured data

• /community/ (AboutPage), /demos/ and /marketplace/ (CollectionPage) and /extensions/ca2a/v0.1/ (TechArticle) get a page node with @id, url, name, description, isPartOf the site and publisher the organization, plus a BreadcrumbList.
• /go/, /quickstart/, /registry/, /telemetry/ and /verify/ keep their existing JSON-LD and gain a BreadcrumbList. /go/'s comes from tools/build-controls.py.
• The homepage's five TechArticle entries gain headline, and the organization's sameAs adds tests.agentrust-io.com and governance.agentrust-io.com, so it lists every AgenTrust site.
• /marketplace/catalog/ gets og and twitter tags from tools/build-discovery.py. It stays without JSON-LD, because check-discovery.py requires that page to carry no script.

Guard. tools/check-discovery.py now fails an indexable page when its description is over 160 characters, its title or description has an em or en dash, og:title or twitter:title differ from the title rule, og:description or twitter:description differ from the meta description, og:image lacks width, height or alt, or it has no JSON-LD (the catalog excepted).

Adoption contact. The /community/ "Contact Imran" button was a mailto link. Cloudflare Email Address Obfuscation rewrote it to /cdn-cgi/l/email-protection, which returns 404 to crawlers and answer engines that run no JavaScript. It is now "Start a discussion", linking https://github.com/orgs/agentrust-io/discussions (200).

Not in this PR. Email Address Obfuscation itself is a Cloudflare zone setting, switched off separately once this and the TRACE change deploy. The other strings it rewrites are example.com placeholders and the package version mcp-search@2.1.0, which read correctly once it is off. The hub still has no llms-full.txt; the other seven hosts generate theirs from MkDocs, and building one here means a new generator, so it is left for a separate change.

Checked

• build-header.py --check, build-controls.py --check, build-discovery.py --check, check-site.py (44 pages, 751 local links), check-discovery.py with the new assertions, check-dashes.js, marketplace.test.js, search/search.test.js, check-tdx-verifier.mjs, render-adoption.mjs --check and wcm/redirect.test.js pass.
• check-discovery.py exits 1 when /community/'s og:title is changed by hand, and again when its description is padded to 316 characters.
• Across the 11 indexable pages: descriptions over 160 went from 9 to 0, titles over 60 from 2 to 0, og:title or twitter:title not matching the title rule from 7 to 0, and pages without JSON-LD from 5 to 1 (the catalog). Every JSON-LD block on the site parses.
• The new titles and descriptions pass the house style linter.
• After the adoption contact change: build-header.py --check, check-site.py (44 pages, 751 local links), check-discovery.py, check-dashes.js and render-adoption.mjs --check pass, and no mailto link remains in the site's HTML.

Generated with Claude Code

https://claude.ai/code/session_013aK3gVWzNdcM3hZ2o2awK2