Improve AI-agent discoverability and trust signals from is-agentic scan

[sakul-learning]

Context

Automated scan: https://is-agentic.com/scan/terraconstructs.dev (Aug 22, 2026) reports a 70/100 agent-readiness score. This issue consolidates the actionable website/discoverability findings. Validate each item against the deployed site before treating it as a defect.

Findings and proposed work

Essential

• Support markdown content negotiation. Requests with Accept: text/markdown reportedly receive HTML and the response has Vary: Accept-Encoding but not Accept. Implement a Markdown representation (or explicitly determine that it is out of scope) and ensure variant responses use Vary: Accept, Accept-Encoding so CDN caches do not mix HTML and Markdown.
• Add agent-facing guidance. Publish llms.txt (or an equivalent documented agent-instructions page) with a concise “when to use TerraConstructs” section, primary product/documentation links, and predictable URLs for developer resources. The scan could not discover relevant developer resources for a terraconstructs query.
• Improve brand/domain discoverability. Confirm the canonical apex/domain is consistently used in page titles, headings, metadata, and external profiles/listings; reduce any redirect chain that obscures it. The scan’s brand search did not return terraconstructs.dev.
• Add trust-anchor pages. Publish substantive /about, /contact, and /privacy pages. Include only accurate, approved business/contact information; do not invent an address or contact channel merely to satisfy a scanner.

Recommended quality improvements

• Return a useful Markdown/plain-text recovery message on genuine 404s, linking to the sitemap, llms.txt, or docs index.
• Preserve a meaningful server-rendered content hierarchy (H1 plus structured H2/H3 sections) without JavaScript.
• Complete JSON-LD: the scan found an organization type but reported missing name and description; add appropriate url and, where accurate and desired, contactPoint and address fields.
• Improve content-to-markup efficiency (scan measured 4.24%, just below its 5% guideline) by removing unused inline assets/hydration markup where practical.

Acceptance checks

• curl -I -H "Accept: text/markdown" https://terraconstructs.dev/ demonstrates the intended representation and includes Vary: Accept when representations vary.
• https://terraconstructs.dev/llms.txt, the trust-anchor pages, sitemap, and a deliberately missing path are checked against the deployed site.
• Inspect raw HTML (without client-side JavaScript) for a semantic heading hierarchy and complete, valid JSON-LD.
• Re-run the external scan and capture the before/after result or document intentional exclusions.