=== 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.2.1
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>`.

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

The plugin also appends AI-bot allowances and a `Sitemap:` directive to
WordPress's virtual `robots.txt`, and keeps everything fresh with a scheduled
refresh (with graceful stale-serve if Globetrotters is briefly unreachable).

**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.

== 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.

= 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.

= 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.

== Changelog ==

= 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.
