=== Globetrotters AI Presence ===
Contributors: globetrotters
Tags: ai, llms, schema, json-ld, discovery
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.5.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Serve your Official AI Presence at your site's apex — AI discovery files and server-rendered JSON-LD, pulled automatically from Globetrotters.

== Description ==

The Globetrotters AI Presence plugin installs your Official AI Presence on a
WordPress site **without filesystem access**. It hooks WordPress's own router to
serve the AI discovery file set at your apex, injects server-rendered JSON-LD into
`wp_head`, and pulls everything from Globetrotters so nothing has to be uploaded by
hand.

**What it serves at your apex:**

* `/llms.txt` and `/ai.json` — the AI-readiness discovery pair.
* `/.well-known/mcp.json` and `/.well-known/agent-card.json` — agent discovery
  manifests (pointing at the Globetrotters-hosted MCP endpoint).
* `/.well-known/globetrotters-apex-version.json` — the version/drift marker.
* `/schema.json` — standalone JSON-LD, also injected inline into your pages'
  `<head>`.
* Your IndexNow verification key, when Globetrotters has issued one — served at
  the address search engines look for it, so new and updated presence content can
  be announced from your own domain.
* `/ai-sitemap.xml` — a sitemap of the files above, generated from what this site
  is serving right now and advertised in your robots.txt. Deliberately not
  `/sitemap.xml`: that address belongs to your site's own sitemap.

Heavy files (`llms-full.txt`, `content.md`) are linked back to Globetrotters rather
than served locally, keeping the footprint minimal.

**Install profile.** Globetrotters also publishes your full presence on its own
subdomain, but nothing on the public web points at it, so AI assistants reach it
only if they already know the address. The recommended **Apex and subdomain**
profile fixes that automatically: this site keeps serving the discovery files
exactly as before, and additionally points at that subdomain from the head of
your pages. Nothing visible is added and your design is untouched. The address
is read from your own presence content and re-checked on every refresh, so it
keeps working when your managed hostname is switched on or off. Choose **Apex
only** to add nothing at all.

The plugin also lists the AI crawlers Globetrotters tracks, and a `Sitemap:`
directive, in WordPress's virtual `robots.txt` — without changing what any
crawler may access on your site — and keeps everything fresh with a scheduled
refresh (with graceful stale-serve if Globetrotters is briefly unreachable, or
answers with something that is not your content).

**Agent traffic reporting (optional).** Because the discovery files are served
from your own site, requests for them never reach Globetrotters and would
otherwise be invisible. Paste the ingest token and endpoint URL from Studio and
the plugin records each request locally and sends batches every 15 minutes. No
cookies, no visitor identifiers — just which AI agent fetched which file, when.

Updates are published by Globetrotters rather than through the WordPress.org
directory, and arrive in your normal Plugins screen; each package is
checksum-verified before it installs.

== Installation ==

1. Upload and activate the plugin.
2. Go to **Settings → AI Presence**.
3. Enter the URL of your Globetrotters website.
4. Save. The plugin fetches your artefacts and starts serving them at your apex.

== Frequently Asked Questions ==

= Does this need FTP or filesystem access? =

No. The plugin serves the files through WordPress itself, so it works on managed
hosts that don't give you docroot access.

= Where does the content come from? =

From your already-public Globetrotters presence. The plugin pulls it and re-serves
it at your apex, so it stays in sync automatically.

= Which install profile should I choose? =

**Apex and subdomain**, unless you have a reason not to. Both halves of your AI
presence then exist and are connected: this site serves the discovery files at
your apex, and your pages point at the Globetrotters-hosted subdomain carrying
the full content. The only thing it adds is a few `<link>` tags in the page
head — invisible to visitors, and no change to your theme or layout. Choose
**Apex only** if you would rather your pages carry no outbound pointers.

= Will this add anything visible to my site? =

No. The plugin only adds `<link>` tags to the page head, which browsers never
render. It deliberately does not insert a visible link into your footer: a
plugin has no reliable place to put one, so it would land outside your theme's
layout. If you want a visible link — which is the kind an AI crawler follows,
unlike a head tag — Studio's **Apex install** panel gives you ready-made HTML
with your real address filled in, to paste where it belongs in your theme.

= Does the plugin change what crawlers can access on my site? =

Not unless you ask it to. The plugin lists the AI crawlers Globetrotters tracks
in your robots.txt, but a crawler your robots.txt already names keeps the rules
you gave it, and every other listed crawler follows exactly the rules your site
sets for all crawlers — WordPress's block on `/wp-admin/` included. Under
**Settings → AI Presence** you can choose to give the listed AI crawlers access
to everything, and to state that your content may be used to train AI models;
both are off by default. Giving them access to everything does not replace a
`Content-Signal` line your robots.txt already has. If your site is set to
discourage search engines, the plugin leaves robots.txt alone entirely.

= Where does the subdomain address come from? =

It is read from the presence content the plugin already downloads, not typed in.
That matters because the address changes: it is `yourslug.globetrotters.ai` until
your own `ai.yourdomain.com` hostname is switched on, and reverts if it is ever
detached. Because it is re-derived on every refresh, the link follows those
changes on its own. Until it has been determined, no link is added at all — the
plugin never guesses a hostname.

= Where do I get the ingest token? =

In Studio, open **AI Presence → Content**, then the **Apex install** panel, and
use **Issue ingest token** on the "Report agent traffic from your server" step.
The endpoint URL is shown next to the token, and the token itself is shown
exactly once — copy both before closing the dialog. The **Open Studio** button on
the settings screen links straight to that step. Your domain has to be verified
first; if it isn't, the step offers a verification link instead.

= Why don't I see any AI-agent traffic in Studio? =

Agent traffic reporting is off until you paste an ingest token and endpoint URL
under **Settings → AI Presence**. After that, expect a delay of roughly 30 to 45
minutes before requests appear: the plugin batches them every 15 minutes, and
Globetrotters waits for each time bucket to settle before writing it. Note that
the status block on the settings screen can only tell you that batches are being
accepted — the endpoint answers the same way to a token that is no longer valid,
so if the numbers never appear in Studio, re-issue the token.

= My site is behind Cloudflare or a CDN. Do I need to change anything? =

Turn on **Trusted proxy** under **Settings → AI Presence**. Reporting sends the
IP the request arrived from, and that is what lets Globetrotters confirm a hit
really came from a known AI crawler. Behind a proxy with the setting off, every
hit reports the proxy's own address instead and none of them can be confirmed,
so your traffic shows up unverified. Only turn it on when it is actually true:
on a site reachable directly, the headers it starts trusting can be set by
anyone.

= Does reporting track my visitors? =

No. Only requests for the six AI discovery files are recorded, and only what the
request itself carried: the file, the time, the User-Agent, and the IP. There
are no cookies and no visitor identifiers, the homepage and normal pages are
never touched, and Globetrotters discards the IP once it has resolved a country.

= How does the plugin get its updates? =

Not from the WordPress.org directory. Updates are published by Globetrotters
and appear in your normal **Plugins** screen and update notifications like any
other plugin — WordPress checks `globetrotters.ai` for this plugin because the
plugin declares it. Each downloaded package is checked against the checksum in
that update listing before it is installed, and a package that does not match is
refused. Auto-updates can be turned on for it in the Plugins screen, same as
usual.

== Changelog ==

= 0.5.0 =
* The AI crawler list your robots.txt names now matches the one Globetrotters
  itself publishes and grades sites against: 20 named crawlers instead of 11,
  covering OpenAI, Anthropic, Google, Microsoft, Apple, Meta, Amazon,
  Perplexity, DuckDuckGo, Common Crawl, ByteDance and Cohere.
* Listing those crawlers no longer changes what they may access on your site.
  Earlier versions gave each listed crawler its own "allow everything" entry,
  and a crawler with an entry of its own ignores your site's general rules —
  so each was released from WordPress's standard block on `/wp-admin/`, and
  from a site-wide block on a staging site. Now a crawler your robots.txt
  already names keeps exactly the rules you gave it, and every other one
  follows the same rules as all other crawlers on your site. Your robots.txt
  is read the way Google reads it, so a line such as `Content-Signal` or
  `Crawl-delay` placed between two `User-agent` lines does not change which
  rules those crawlers follow.
* Each listed crawler carries a `Content-Signal` line stating that your
  content may be used for search and for answering questions. Nothing is said
  about AI training unless you choose to — and if your robots.txt already has
  its own `Content-Signal` line, that one is used instead, including when you
  give the listed crawlers access to everything.
* Two new options under **Settings → AI Presence**, both off by default
  because each is a decision about your whole site: give the listed AI
  crawlers access to everything, including the paths closed to other
  crawlers; and tell them your content may be used to train AI models.
* If a refresh receives a web page where a discovery file should be — a
  maintenance page, a login screen or a proxy error that still answers "OK" —
  the refresh is now refused and your site keeps serving the files it already
  had. Previously the page was saved in place of the file and the refresh
  reported success.
* A value in your presence content containing HTML-like text such as
  `<!--<script>` could make browsers read the rest of your homepage as part of
  the structured data in its head, hiding the page. Those characters are now
  written in an escaped form that structured-data readers decode straight
  back, so nothing in the content can affect how your page is displayed.
* Your robots.txt now points search engines at a sitemap **on your own domain**
  instead of at Globetrotters. The old line named another host, which search
  engines ignore, so the discovery files had no sitemap entry anywhere that
  counted.
* The plugin serves that sitemap itself, at `/ai-sitemap.xml`. It lists your
  homepage and every discovery file this site actually serves, so it can never
  point at an address that isn't there. Your existing sitemap is untouched:
  nothing is served at `/sitemap.xml`, WordPress's own `/wp-sitemap.xml` is
  left alone, and an SEO plugin keeps whichever address it uses — robots.txt
  simply lists both.
* Plugin updates now reach your site. Every earlier version answered
  WordPress's update check in a form WordPress silently discards, so no update
  was ever offered in wp-admin. Install this version by hand once; updates
  after it arrive normally.
* Clearing the Globetrotters website URL now stops publishing straight away:
  the discovery files, the homepage structured data and the search-engine
  verification file are all removed until you connect again. Pointing the
  plugin at a different website URL likewise clears the previous one's files,
  and the new ones are served as soon as the first refresh completes.
  Previously the last files kept being served indefinitely.
* Agent traffic reporting only ever sends to an `https://` endpoint and never
  follows a redirect, so your ingest token and the visitor addresses it
  reports cannot travel unencrypted, or to another address.
* Trusted proxies are now a list. Tick **This site sits behind Cloudflare**,
  or enter the addresses of your own proxies or load balancers: the visitor
  address is read from forwarding headers only on requests that actually come
  from one of them. Previously a single checkbox trusted those headers from
  anyone, so on a site still reachable directly, a visitor could pass for a
  known AI crawler. A ticked checkbox now reads as the Cloudflare option — if
  your proxy is something else, add its addresses.
* Reporting bookkeeping and refreshes no longer overwrite each other: a busy
  moment can no longer lose count of dropped requests, or undo a refresh that
  finished at the same time.

= 0.4.0 =
* Your site can now prove to search engines that it is yours, so Globetrotters
  can tell them the moment your presence content changes instead of waiting to
  be crawled. The plugin serves the verification file search engines look for,
  at the one address where it counts — your apex. Nothing to install, configure
  or upload: the key arrives with your normal refresh, and if Globetrotters has
  not issued one for your site the address simply isn't served.
* If a key is later changed or withdrawn, your site stops serving the old one on
  its next refresh rather than keeping a copy that no longer verifies anything.
* Requests for the verification file are not counted in Presence Analytics —
  those numbers stay a measure of AI agents fetching your discovery files.

= 0.3.0 =
* Added the **Apex and subdomain** install profile, and made it the recommended
  choice. Your site keeps serving the discovery files at your apex exactly as
  before, and now also points at the Globetrotters-hosted subdomain carrying
  your full presence — which nothing on the public web linked to until now, so
  AI assistants could only reach it if they already knew the address. The
  pointer is added to the head of your pages only: no visible change to your
  design, nothing for your theme to accommodate. Choose it under
  **Settings → AI Presence**; **Apex only** stays the default and behaves
  exactly as it always has.
* Robustness fixes to how the discovery files are refreshed and served. Nothing
  changes in what the plugin does when everything is working; these all concern
  what happens when something upstream is not.
* If every discovery file comes back empty in one refresh, the refresh is now
  refused and your site keeps serving the files it already had. That pattern
  means a broken source or a proxy answering with no content, not a real
  publish — previously the empty files were cached and your apex went blank
  until the next good refresh.
* If the refreshed files cannot be saved, the refresh is now reported as
  failed instead of succeeding silently. Your previous files keep serving and
  the reason appears under **Settings → AI Presence**, which until now could
  show a healthy, up-to-date install that was in fact still serving the older
  files.
* The discovery files now answer `GET` and `HEAD` requests only. Other request
  methods are passed on to WordPress, so they no longer inflate the request
  counts in your Presence Analytics.
* Each discovery file is now served at its own single URL only. Requests with
  extra leading slashes — which could reach the file under any number of
  made-up addresses, including ones naming a site that is not yours — are
  passed on to WordPress instead.

= 0.2.2 =
* Fixed a WordPress notice ("translations were triggered too early") that the
  plugin could write to your debug log on WordPress 6.7 and later. It appeared
  only on the single page load where the plugin first set up its scheduled
  tasks — a fresh install, or the first load after you turn on agent traffic
  reporting. Nothing was broken by it, and scheduled refreshes and reporting
  still start on that same page load.
* Internal compatibility work for the WordPress.org plugin review: stricter
  handling of the reporting table's name in database queries, and removal of a
  translation loader the plugin never needed. Nothing changes in what the
  plugin does.

= 0.2.1 =
* The AI discovery files are now served with `Access-Control-Allow-Origin: *`.
  They are public, read-only files that anyone can already fetch, and without
  this header an AI assistant running inside a browser is blocked from reading
  them. Only the discovery files this plugin serves are affected; nothing else
  on your site changes.

= 0.2.0 =
* Added agent traffic reporting. Requests to the AI discovery files terminate on
  your own site and are invisible to Globetrotters, so the plugin now records
  each one locally and sends batches to the Globetrotters ingest endpoint every
  15 minutes. Paste the ingest token and endpoint URL (issued together in the
  Apex install panel in Studio) under **Settings → AI Presence**; until you do,
  nothing is recorded and nothing is sent.
* The AI discovery files are now served `no-store` (both `Cache-Control` and
  `Surrogate-Control`). Without this a CDN or managed-host edge cache would serve
  them without ever reaching PHP, and the reported counts would be low by an
  unknowable amount.
* Added a "trusted proxy" setting for sites behind Cloudflare, a CDN or a load
  balancer. It is off by default and should only be turned on when it is true.
* Buffered requests are capped at 5000 or 512KB; anything dropped past that is
  counted and reported, so a gap shows up as a gap rather than as quiet traffic.
* A site with enough agent traffic to fill that buffer inside one 15-minute
  window now sends early rather than waiting for the next scheduled send, so
  busy sites report in full instead of losing the overflow.

= 0.1.1 =
* Fixed the content hash to match the backend `canonical_hash` byte-for-byte
  (raw inner digest + byte-lexicographic ordering). Side effect: the first
  refresh after updating recomputes the stored hash with the new algorithm, so
  a single refresh reports the bundle as changed even when the content is
  byte-identical (same behaviour as a fresh install); it settles from the next
  refresh on.

= 0.1.0 =
* Initial release: apex file serving, `wp_head` JSON-LD injection, `robots.txt`
  filter, scheduled refresh with stale-serve fallback, and an admin status page.
