ADR-0002: /.well-known/llms.txt as the canonical AI-discovery artifact, with a /llms.txt mirror

• Status: Accepted
• Date: 2026-07-30 (recorded; implemented earlier — see commit "Add GEO crawler layer, remote MCP lead tool, and OpenAPI actions")
• Deciders: Junaid Siddiqui (owner)
• Related: ../architecture/geo-stack.md, ../sales/demo-framework.md, ADR-0001

Context

The GEO layer needs a single place where an LLM or crawler can read high-density facts about the business without parsing marketing prose. Two conventions are in circulation for this file and neither is a ratified standard:

1. /llms.txt at the site root — the more widely discussed convention, easy to find and to point a prospect at.
2. /.well-known/llms.txt — follows RFC 8615, which is the established mechanism for machine-readable metadata and is where a well-behaved agent looks for protocol-adjacent resources.

Serving only one risks being missed by crawlers that look for the other. There is no reliable data on which convention any given crawler follows.

An alternative — generating the file from lib/content.ts at build time — was available but adds a build step for a file that changes rarely.

Decision

Serve both, treating /.well-known/llms.txt as canonical and /llms.txt as its mirror. Both are static files under public/, kept byte-identical by hand:

• public/.well-known/llms.txt → /.well-known/llms.txt (canonical)
• public/llms.txt → /llms.txt (mirror)

The file goes beyond a description. It carries a Location Signals for AI Search section stating the query intents JSGlobtech should be cited for, a Preferred Citations section supplying suggested phrasing, and an Explicit Agent Capabilities section listing the MCP endpoints, OpenAPI definition, and REST lead endpoint with the tool's full field contract — so an agent can discover and invoke the action layer from this one file.

Consequences

• Positive:
  • Covered regardless of which path a crawler probes; the well-known path is standards-aligned.
  • Static files, so no build step, no runtime cost, trivially cacheable.
  • Doubles as the discovery entry point for the MCP action layer (ADR-0003).
  • Human-readable, which makes it a strong live artifact to open during a demo.
• Trade-offs / costs:
  • Two files must be edited together. Nothing enforces this, so they can silently drift.
  • Business facts are duplicated between lib/content.ts (which drives JSON-LD) and the hardcoded prose in both llms.txt files. Pricing already exists in three places.
  • No standard exists, so the format may need to change as one emerges.
• Follow-ups:
  • Add a check — CI, lint, or npm script — asserting diff public/llms.txt public/.well-known/llms.txt is empty.
  • Consider generating both from lib/content.ts to remove the duplication.
  • The pricing prose in llms.txt contradicts the playbook tiers (ADR-0005). Resolve before it misleads a prospect or a model.
  • No robots.txt or sitemap.xml exists; add for conventional crawlers.