diff --git a/.github/workflows/bot-serving-check.yml b/.github/workflows/bot-serving-check.yml
index 2a0d5eca54..607023608a 100644
--- a/.github/workflows/bot-serving-check.yml
+++ b/.github/workflows/bot-serving-check.yml
@@ -28,13 +28,13 @@ permissions:
 jobs:
   bot-serving:
     runs-on: ubuntu-latest
-    # 22 check() calls x (--retry 2 -> up to 3 attempts x --max-time 30) can
-    # reach ~33 min worst-case, plus two non-retried probes (llms.txt charset,
-    # trailing slash — 30s each); 38 leaves room to report a clean failure
-    # rather than dying to the job timeout, which reports nothing useful.
-    # Recompute this when adding checks: the ceiling is check() calls x 90s,
-    # plus margin.
-    timeout-minutes: 38
+    # 27 check() calls x (--retry 2 -> up to 3 attempts x --max-time 30) can
+    # reach ~41 min worst-case, plus four non-retried probes (llms.txt charset,
+    # trailing slash, og-image, .well-known redirect — 30s each); 46 leaves
+    # room to report a clean failure rather than dying to the job timeout,
+    # which reports nothing useful. Recompute this when adding checks: the
+    # ceiling is check() calls x 90s, plus margin.
+    timeout-minutes: 46
     steps:
       - name: Crawler UAs must get 200 + per-route titles
         run: |
@@ -50,16 +50,16 @@ jobs:
           fail=0
 
           check() {
-            local ua="$1" url="$2" expect="$3"
+            local ua="$1" url="$2" expect="$3" want="${4:-200}"
             local code
             # On curl failure REPLACE the code — a failing curl can still have
             # printed a partial -w code; appending would yield e.g. "200000".
             code=$(curl -sS --retry 2 --max-time 30 -A "$ua" -o body.html -w '%{http_code}' "$url") || code="000"
-            if [ "$code" != "200" ]; then
-              echo "::error::$url with UA '$ua' returned HTTP $code (expected 200)"
+            if [ "$code" != "$want" ]; then
+              echo "::error::$url with UA '$ua' returned HTTP $code (expected $want)"
               fail=1
             elif ! grep -qF "$expect" body.html; then
-              echo "::error::$url with UA '$ua' returned 200 but the body is missing: $expect"
+              echo "::error::$url with UA '$ua' returned $want but the body is missing: $expect"
               fail=1
             else
               echo "OK: $url ($ua)"
@@ -101,11 +101,42 @@ jobs:
             "Mozilla/5.0 (compatible; Amzn-User/1.0)" \
             "Mozilla/5.0 (compatible; Amazonbot/0.1; +https://developer.amazon.com/support/amazonbot)" \
             "meta-externalagent/1.1 (+https://developers.facebook.com/docs/sharing/webmasters/crawler)" \
-            "Grok/1.0"
+            "Grok/1.0" \
+            "Mozilla/5.0 (compatible; xAI-Bot/1.0)"
           do
             check "$ua" "$ORIGIN/scatter-basic" "<title>Basic Scatter Plot | anyplot.ai</title>"
           done
 
+          # A crawler asking for a URL that is no page gets a real 404 from the
+          # seo-proxy — the SPA shell would answer 200 (soft-404), and did for
+          # 161 stale migration URLs before the proxy learned to say no.
+          check "$GOOGLEBOT" "$ORIGIN/this-spec-does-not-exist" '"status":404' 404
+
+          # The machine files must be served directly, never proxied to the
+          # seo backend — including for a mapped crawler UA, which is the whole
+          # point of the `location =` bypasses. robots.txt and sitemap.xml
+          # join llms.txt below: the sitemap is proxied to the API for every
+          # client, and a broken proxy would hand a crawler the SPA shell.
+          check "$GOOGLEBOT" "$ORIGIN/robots.txt"  "User-agent: Bytespider"
+          check "$GOOGLEBOT" "$ORIGIN/sitemap.xml" "<urlset"
+
+          # The site card must be the FILE for a preview bot, not the proxy —
+          # a preview bot that lands on /seo-proxy/og-image.png shows nothing.
+          code=$(curl -sS --max-time 30 -A "$TWITTERBOT" -o /dev/null -w '%{http_code} %{content_type}' "$ORIGIN/og-image.png") || code="000"
+          case "$code" in
+            "200 image/png"*) echo "OK: og-image.png served as image to a preview bot" ;;
+            *) echo "::error::og-image.png for a preview bot: $code (expected 200 image/png)"; fail=1 ;;
+          esac
+
+          # A guessed /.well-known/llms.txt must land on the file, not on the
+          # SPA shell (which soft-404'd it with 200 until 2026-08-28).
+          wk_target=$(curl -sS --max-time 30 -o /dev/null -A "$CHATGPTUSER" \
+            -w '%{redirect_url}' "$ORIGIN/.well-known/llms.txt")
+          case "$wk_target" in
+            */llms.txt) echo "OK: .well-known/llms.txt -> $wk_target" ;;
+            *) echo "::error::.well-known/llms.txt did not redirect to the guide: '$wk_target'"; fail=1 ;;
+          esac
+
           # llms.txt must be served directly, never proxied to the seo backend —
           # including for a mapped crawler UA, which is the whole point of the
           # `location = /llms.txt` bypass.
@@ -145,7 +176,9 @@ jobs:
             *) echo "OK: trailing slash -> $slash_target" ;;
           esac
 
-          # Control: humans must still get the SPA shell
-          check "$HUMAN" "$ORIGIN/" '<div id="root">'
+          # Control: humans must still get the SPA shell — on the home page
+          # and on a deep route.
+          check "$HUMAN" "$ORIGIN/"              '<div id="root">'
+          check "$HUMAN" "$ORIGIN/scatter-basic" '<div id="root">'
 
           exit $fail
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6ec19a528..517a8c4267 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,26 @@ aggregate instead: an italic *Catalog* line at the end of the version section an
 
 ### Added
 
+- **LLM discoverability sync from kurrentschrift** — the sister project's
+  assistant-protocol findings (2026-08-28) carried over: assistants' fetch tools often allow
+  only URLs that already appeared verbatim in fetched content, so the machine guide and one
+  complete, callable example per surface now stand wherever an agent actually reads. The SPA
+  shell carries a `<link rel="alternate" href="/llms.txt">` and a `<noscript>` block with
+  absolute URLs (guide, `llms-full.txt`, one code endpoint, one render PNG, OpenAPI, MCP);
+  `/.well-known/llms.txt` redirects to the guide instead of soft-404ing with the shell, and
+  `api.anyplot.ai/llms.txt` redirects to the site file instead of 404ing; both `robots.txt`
+  files name `llms.txt` and the OpenAPI spec (two terse lines at the very top of the site
+  file, a fuller block beside `Sitemap:`, the API host's comment head); every bot page links
+  the guide from its footer nav, and every implementation page spells out its own code URL
+  and carries a visible JSON retrieval record beside the JSON-LD (HTML-to-Markdown converters
+  drop `<script>`, keep `<pre>`). The nginx map and `AI_AGENTS` gain `xai` (a `xAI-Bot` UA
+  fell through to the empty shell) and the bare `grok` token that was prerendered but never
+  counted. A new `asset_fetch` event on `bots.anyplot.ai` records which implementation's
+  code and which spec's detail assistants fetch through the API (cache misses — see
+  `docs/reference/plausible.md`). Guards: `app/src/routes/seoCoverage.test.ts` pins llms.txt
+  ↔ route registry ↔ robots.txt ↔ shell; `bot-serving-check` adds the `.well-known`
+  redirect, the robots/sitemap bypasses, the site card, a real 404 and a deep-route SPA
+  control. Doctrine: `docs/reference/seo.md` "Discoverability for assistants" (#10808).
 - **`llms-full.txt` — the whole catalogue in one fetch** — a new
   `GET /llms-full.txt` lists every spec on one line (id, title, hub URL, implemented
   libraries) under a header that documents the retrieval recipes that work for *every*
@@ -32,6 +52,17 @@ aggregate instead: an italic *Catalog* line at the end of the version section an
 
 ### Fixed
 
+- **Crawler reads on the bot site were mostly dropped by Plausible** — on the prerender path
+  (Cloud Run app → Cloudflare → API) `cf-connecting-ip` is the app container's Google egress
+  address, exactly the "hosting provider IP" Plausible discards, and `visitor_ip` preferred
+  it over the forwarded list where the crawler actually stands. kurrentschrift measured one
+  counted read in twenty with probe events (2026-08-28). `visitor_ip` now reads the leftmost
+  valid `x-forwarded-for` entry first and falls back to `cf-connecting-ip`; nginx's
+  `@seo_proxy` forwards the crawler in `X-Forwarded-For` explicitly (#10808).
+- **`robots.txt` carried an invalid `use=reference` Content-Signal token** — the
+  contentsignals.org vocabulary is exactly `search`, `ai-input` and `ai-train`; a strict
+  parser may discard the whole line over an unknown token, taking the three real signals with
+  it. Dropped from both groups; `seoCoverage.test.ts` pins the vocabulary (#10808).
 - **The generation retry cap counted a library's entire failure history, not the current
   run** — `impl-generate.yml` derives its "3 attempts" budget from hidden marker comments
   on the spec issue, and nothing ever deletes those markers. A `(spec, library)` pair that
diff --git a/api/analytics.py b/api/analytics.py
index 1f128daf71..35fd1bbef9 100644
--- a/api/analytics.py
+++ b/api/analytics.py
@@ -70,6 +70,13 @@
     ("grok-deepsearch", "grok", "user_directed"),
     ("grokbot", "grok", "user_directed"),
     ("xai-grok", "grok", "user_directed"),
+    # The bare tokens the nginx map already serves (`~*grok`, `~*xai`): xAI's
+    # fetcher was seen sending plain "Grok" (AI-access audit 2026-08-19) and
+    # "xAI-Bot" without the grok substring (kurrentschrift, 2026-08-28). Both
+    # were prerendered but never counted, because nothing above matched them.
+    # Last among the xAI patterns so the specific ones keep winning.
+    ("grok", "grok", "user_directed"),
+    ("xai", "grok", "user_directed"),
     ("youbot", "you", "index"),
     ("cohere-ai", "cohere", "user_directed"),
     # Classic search crawlers. Worth recording for the same reason the AI ones
@@ -307,6 +314,68 @@ def track_og_image(
     task.add_done_callback(_handle_task_exception)
 
 
+# The single-asset API reads an assistant makes after landing on a page: the
+# runnable source of one implementation and the detail of one spec. Nothing
+# else on the API is counted — the list endpoints, /plots/filter and the
+# machine files are catalogue navigation, not a request for one thing.
+# `/specs/map` shares the shape of a spec id and is excluded by name.
+_ASSET_ROUTES: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"^/specs/([a-z0-9]+(?:-[a-z0-9]+)*)/([a-z0-9]+(?:-[a-z0-9]+)*)/code$"), "code"),
+    (re.compile(r"^/specs/([a-z0-9]+(?:-[a-z0-9]+)*)$"), "spec"),
+)
+_NOT_A_SPEC = frozenset({"map"})
+
+
+def classify_asset(path: str) -> tuple[str, str, str | None] | None:
+    """(asset, spec_id, library_id) for a single-asset API path, else None.
+
+    `asset` is `code` (one implementation's runnable source) or `spec` (one
+    spec's detail); `library_id` is None for a spec read.
+    """
+    for pattern, asset in _ASSET_ROUTES:
+        m = pattern.match(path)
+        if m is None:
+            continue
+        spec_id = m.group(1)
+        if spec_id in _NOT_A_SPEC:
+            return None
+        return asset, spec_id, (m.group(2) if m.lastindex and m.lastindex >= 2 else None)
+    return None
+
+
+def track_asset_fetch(request: Request, *, asset: str, spec: str, library: str | None, status: int) -> None:
+    """Record an AI or search agent fetching one asset through the API (fire-and-forget).
+
+    Same site, same gate and same audience rule as `track_bot_fetch`: humans
+    and unclassified clients cost nothing beyond a substring scan, and the
+    event goes to BOT_DOMAIN. The props answer "which plots do assistants
+    actually pull the code of": `asset` (code · spec), `spec`, `library`.
+
+    One caveat the dashboard must know: these routes answer `public,
+    max-age=300`, so a read that Cloudflare serves from its edge never reaches
+    this process. The count is therefore the cache MISSES — the first fetch
+    per URL per edge TTL — which for sporadic assistant traffic is nearly all
+    of them, but not the same thing as every request.
+    """
+    detected = detect_ai_agent(request.headers.get("user-agent", ""))
+    if detected is None:
+        return
+    assistant, kind = detected
+    props: dict[str, str] = {"asset": asset, "spec": spec, "assistant": assistant, "kind": kind, "status": str(status)}
+    if library is not None:
+        props["library"] = library
+    url = f"https://api.anyplot.ai{request.url.path}"
+
+    task = asyncio.create_task(
+        _send_plausible_event(
+            request.headers.get("user-agent", ""), visitor_ip(request), "asset_fetch", url, props, domain=BOT_DOMAIN
+        )
+    )
+    _BACKGROUND_TASKS.add(task)
+    task.add_done_callback(_BACKGROUND_TASKS.discard)
+    task.add_done_callback(_handle_task_exception)
+
+
 def track_bot_fetch(request: Request, path: str, status: int) -> None:
     """Record an AI or search agent requesting a page (fire-and-forget).
 
diff --git a/api/main.py b/api/main.py
index 8121899b48..99900a922f 100644
--- a/api/main.py
+++ b/api/main.py
@@ -16,7 +16,7 @@
 from fastapi.middleware.cors import CORSMiddleware  # noqa: E402
 from starlette.middleware.gzip import GZipMiddleware  # noqa: E402
 
-from api.analytics import track_bot_fetch  # noqa: E402
+from api.analytics import classify_asset, track_asset_fetch, track_bot_fetch  # noqa: E402
 from api.cache import cache_key, set_cache  # noqa: E402
 from api.exceptions import (  # noqa: E402
     AnyplotException,
@@ -181,16 +181,27 @@ async def lifespan(app: FastAPI):
 # longer exists is a signal worth keeping, it just is not a page view.
 @app.middleware("http")
 async def record_bot_fetch(request: Request, call_next):
-    """Report AI/search agent page requests to the bot analytics site.
+    """Report AI/search agent page requests and single-asset API reads to the bot site.
 
     Requests, not reads: the status is recorded rather than filtered on, so a
-    404 is visible as a miss instead of counted as a page view.
+    404 is visible as a miss instead of counted as a page view. Page reads
+    (/seo-proxy) become `bot_fetch`; one implementation's code or one spec's
+    detail fetched through the API becomes `asset_fetch` — the list endpoints
+    and the machine files are not recorded.
     """
     response: Response = await call_next(request)
     path = request.url.path
     if path.startswith("/seo-proxy"):
         # The public URL, never this router's internal prefix
         track_bot_fetch(request, path.removeprefix("/seo-proxy") or "/", response.status_code)
+        return response
+    asset = classify_asset(path)
+    if asset is not None:
+        # `asset_type` is what was fetched (code · spec) — not the agent's
+        # `kind` (user_directed · index · …), which track_asset_fetch derives
+        # from the user agent itself.
+        asset_type, spec_id, library_id = asset
+        track_asset_fetch(request, asset=asset_type, spec=spec_id, library=library_id, status=response.status_code)
     return response
 
 
diff --git a/api/request_context.py b/api/request_context.py
index a77c154327..3935be7dbd 100644
--- a/api/request_context.py
+++ b/api/request_context.py
@@ -51,17 +51,26 @@ def visitor_ip(request: Request) -> str:
     Spoofing is not a concern in this direction: a forged value skews a
     geolocation bucket, where forging the rate-limit key locked people out.
 
-    Order: `cf-connecting-ip`, which Cloudflare overwrites on proxied traffic
-    and is therefore both real and unforgeable; then the leftmost non-empty
-    forwarded entry; then the socket peer.
+    Order: the leftmost valid `x-forwarded-for` entry FIRST, then
+    `cf-connecting-ip`, then the socket peer. It used to be the other way
+    round, and that lost nearly every crawler read: the prerendered pages
+    reach this host through the site's nginx (Cloud Run app → Cloudflare →
+    API), so on that hop `cf-connecting-ip` is the app container's Google
+    egress address — exactly the "hosting provider IP" Plausible drops — while
+    the crawler itself is only visible as the first forwarded entry, where the
+    site-side Cloudflare put it. kurrentschrift measured the effect with probe
+    events on 2026-08-28 (34.90.x / 35.204.x dropped, a home IP kept): one
+    counted read in twenty. For a direct client behind Cloudflare the leftmost
+    entry and `cf-connecting-ip` are the same address, so nothing changes
+    there.
     """
-    cf_ip = request.headers.get("cf-connecting-ip", "").strip()
-    if _is_ip(cf_ip):
-        return cf_ip
     for entry in request.headers.get("x-forwarded-for", "").split(","):
         candidate = entry.strip()
         if _is_ip(candidate):
             return candidate
+    cf_ip = request.headers.get("cf-connecting-ip", "").strip()
+    if _is_ip(cf_ip):
+        return cf_ip
     return request.client.host if request.client else ""
 
 
diff --git a/api/routers/seo.py b/api/routers/seo.py
index 4824dd6d3b..6b16d31fd5 100644
--- a/api/routers/seo.py
+++ b/api/routers/seo.py
@@ -224,6 +224,12 @@ async def _refresh_sitemap() -> str:
 
 # Site-wide footer nav on every bot page: crawlers that land deep on an impl
 # page can reach the hub surfaces without executing the SPA.
+#
+# The two machine files close the nav, as full URLs. Assistants' fetch tools
+# often allow only URLs that already appeared verbatim in fetched content, so
+# a guide that is linked from nothing an assistant lands on is findable only by
+# guessing the llms.txt convention (kurrentschrift finding 2026-08-28,
+# docs/reference/seo.md "Discoverability").
 _BOT_NAV_HTML = (
     "<nav>"
     '<a href="https://anyplot.ai/">anyplot.ai</a> · '
@@ -234,7 +240,9 @@ async def _refresh_sitemap() -> str:
     '<a href="https://anyplot.ai/palette">palette</a> · '
     '<a href="https://anyplot.ai/mcp">mcp</a> · '
     '<a href="https://anyplot.ai/stats">stats</a> · '
-    '<a href="https://anyplot.ai/about">about</a>'
+    '<a href="https://anyplot.ai/about">about</a> · '
+    '<a href="https://anyplot.ai/llms.txt">llms.txt</a> · '
+    '<a href="https://anyplot.ai/llms-full.txt">llms-full.txt</a>'
     "</nav>"
 )
 
@@ -622,6 +630,56 @@ def _spec_keywords(spec) -> list[str]:
     return keywords
 
 
+def _build_impl_retrieval(spec, impl, page_url: str, hub_url: str) -> str:
+    """The machine-readable retrieval record of an implementation page.
+
+    Two properties matter, both learned from assistants that fetched the
+    sister project's pages (kurrentschrift, 2026-08-28):
+
+    - Every URL is COMPLETE and callable. Assistants' fetch tools often allow
+      only URLs that already appeared verbatim in fetched content, so the
+      `{spec_id}/{library}` template llms.txt offers is not enough on the page
+      an assistant actually lands on — this one spells its own code URL out.
+    - It is a VISIBLE ``<pre><code class="language-json">`` block, beside the
+      JSON-LD in the head, because the HTML-to-Markdown converters assistants
+      read pages through drop ``<script>`` and keep ``<pre>``.
+
+    Same field set as the "Renders" list above it, plus the JSON surfaces —
+    the list says which file is which in words, this block says it in a shape
+    a program can read without parsing prose.
+    """
+    code_url = f"https://api.anyplot.ai/specs/{spec.id}/{impl.library_id}/code"
+    record: dict[str, object] = {
+        "spec_id": spec.id,
+        "language": impl.library.language,
+        "library": impl.library_id,
+        "page": page_url,
+        "hub": hub_url,
+        "code_json": code_url,
+        "spec_json": f"https://api.anyplot.ai/specs/{spec.id}",
+    }
+    for key, url in (
+        ("render_light_png", impl.preview_url_light),
+        ("render_dark_png", impl.preview_url_dark),
+        ("interactive_light_html", impl.preview_html_light),
+        ("interactive_dark_html", impl.preview_html_dark),
+    ):
+        if url:
+            record[key] = url
+    if impl.quality_score is not None:
+        record["quality_score"] = impl.quality_score
+    record["license"] = "MIT"
+    record["guide"] = "https://anyplot.ai/llms.txt"
+    code_url_esc = html.escape(code_url, quote=True)
+    return (
+        "<h2>Retrieve this implementation</h2>"
+        f'<p>Runnable source as JSON, for any HTTP client: <a href="{code_url_esc}">{code_url_esc}</a>. '
+        'Any spec id and library id listed in <a href="https://anyplot.ai/llms-full.txt">llms-full.txt</a> '
+        "fit the same URL shape; every URL below is complete and callable.</p>"
+        f'<pre><code class="language-json">{html.escape(json.dumps(record, indent=2, ensure_ascii=False))}</code></pre>'
+    )
+
+
 def _build_impl_html(spec, impl, code: str | None, image: str) -> str:
     """Full bot page for an implementation detail /{spec_id}/{language}/{library}.
 
@@ -675,6 +733,7 @@ def _build_impl_html(spec, impl, code: str | None, image: str) -> str:
             if code
             else ""
         )
+        + _build_impl_retrieval(spec, impl, page_url, hub_url)
         + f'<p>Part of <a href="{html.escape(hub_url, quote=True)}">{title_esc}</a> on anyplot.ai.</p>'
         + (f"<h2>Other implementations</h2><ul>{''.join(sibling_links)}</ul>" if sibling_links else "")
     )
@@ -723,8 +782,41 @@ async def get_robots():
     parsers stop at the first matching rule, so the specific exclusions must
     precede the blanket allow — the same ordering rule `app/public/robots.txt`
     documents. Specificity-compliant crawlers reach the same answer either way.
+
+    The comment head names the machine guide and the OpenAPI spec: this host
+    is the one llms.txt advertises, so an agent that reaches it first — via
+    the README, a search result, a citation — must be able to get to the
+    guide without guessing the convention (kurrentschrift finding
+    2026-08-28). The Content-Signal line is the site's: one open policy,
+    stated on every host it covers (contentsignals.org vocabulary only).
+    """
+    return Response(content=_API_ROBOTS_TXT, media_type="text/plain")
+
+
+_API_ROBOTS_TXT = (
+    "# api.anyplot.ai — the open read API of anyplot.ai (JSON, no auth).\n"
+    "# Machine guide with every retrieval recipe and full example URLs:\n"
+    "# https://anyplot.ai/llms.txt — catalogue index: https://anyplot.ai/llms-full.txt\n"
+    "# OpenAPI: https://api.anyplot.ai/openapi.json — MCP: https://api.anyplot.ai/mcp/\n"
+    "User-agent: *\n"
+    "Content-Signal: search=yes,ai-input=yes,ai-train=yes\n"
+    "Disallow: /debug\n"
+    "Disallow: /proxy\n"
+    "Allow: /\n"
+)
+
+
+@router.get("/llms.txt", include_in_schema=False)
+async def get_llms_txt() -> RedirectResponse:
+    """Redirect to the site's machine guide.
+
+    The guide lives on the site host (app/public/llms.txt, one source of
+    truth), but agents that land on this host — the README, both robots.txt
+    files and llms-full.txt name it — guess /llms.txt here too. A redirect
+    beats the 404 this answered until 2026-08-28, and beats a served copy that
+    would drift.
     """
-    return Response(content="User-agent: *\nDisallow: /debug\nDisallow: /proxy\nAllow: /\n", media_type="text/plain")
+    return RedirectResponse("https://anyplot.ai/llms.txt", status_code=302)
 
 
 @router.get("/sitemap.xml")
diff --git a/app/index.html b/app/index.html
index 5e457d408a..921cd504b8 100644
--- a/app/index.html
+++ b/app/index.html
@@ -41,6 +41,14 @@
       })();
     </script>
 
+    <!-- Machine-facing fallback in the SHELL itself: agents whose user agent
+         is not in the nginx $is_bot map get this file on every route, and most
+         of them read the raw HTML without executing JS. This link and the
+         <noscript> block in the body put the machine guide and one complete,
+         callable example URL into every first response — invisible in the
+         rendered app. Doctrine: docs/reference/seo.md ("Discoverability"). -->
+    <link rel="alternate" type="text/plain" href="/llms.txt" title="llms.txt — machine guide" />
+
     <!-- Open Graph -->
     <meta property="og:type" content="website" />
     <meta property="og:url" content="https://anyplot.ai/" />
@@ -146,14 +154,31 @@
            Until now "here" was a completely empty page — Grok's fetcher read
            exactly that and reported the site as having no content (AI-access
            audit 2026-08-19). Point such clients at the surfaces that work for
-           everyone. -->
+           everyone.
+
+           Absolute URLs on purpose, and one COMPLETE example per surface:
+           assistants' fetch tools often allow only URLs that already appeared
+           verbatim in fetched content, so a relative link or a URL template
+           with placeholders leaves the API unreachable (kurrentschrift
+           finding 2026-08-28, docs/reference/seo.md "Discoverability"). Keep
+           the example pair in step with llms.txt. -->
       <h1>anyplot.ai — the open plot catalogue</h1>
       <p>
-        This page needs JavaScript. Machine-readable access works without it:
-        <a href="/llms.txt">llms.txt</a> (how to query the catalogue),
-        <a href="/llms-full.txt">llms-full.txt</a> (every spec, one per line),
-        the <a href="https://api.anyplot.ai/openapi.json">JSON API</a>, and the
-        <a href="https://github.com/MarkusNeusinger/anyplot">GitHub repository</a>.
+        This page needs JavaScript. Machine-readable access works without it.
+        The machine guide with every retrieval recipe is
+        <a href="https://anyplot.ai/llms.txt">https://anyplot.ai/llms.txt</a>; the whole
+        catalogue, one line per spec, is
+        <a href="https://anyplot.ai/llms-full.txt">https://anyplot.ai/llms-full.txt</a>.
+        The open JSON API returns the runnable source of any implementation, e.g.
+        <a href="https://api.anyplot.ai/specs/bar-error/seaborn/code">https://api.anyplot.ai/specs/bar-error/seaborn/code</a>
+        — the spec id and the library id are free parameters (any pair listed in llms-full.txt) —
+        and every rendered plot is a plain PNG, e.g.
+        <a href="https://storage.googleapis.com/anyplot-images/plots/bar-error/python/seaborn/plot-light.png">https://storage.googleapis.com/anyplot-images/plots/bar-error/python/seaborn/plot-light.png</a>.
+        API documentation: <a href="https://api.anyplot.ai/openapi.json">https://api.anyplot.ai/openapi.json</a> ·
+        MCP endpoint: <a href="https://api.anyplot.ai/mcp/">https://api.anyplot.ai/mcp/</a> ·
+        source: <a href="https://github.com/MarkusNeusinger/anyplot">https://github.com/MarkusNeusinger/anyplot</a>.
+        Crawlers and assistants with known user agents receive a prerendered full-text
+        version of every page at the same URL.
       </p>
     </noscript>
     <script type="module" src="/src/main.tsx"></script>
diff --git a/app/nginx.conf b/app/nginx.conf
index c95212b642..001e0352e4 100644
--- a/app/nginx.conf
+++ b/app/nginx.conf
@@ -84,6 +84,10 @@ map $http_user_agent $is_bot {
     # "insufficient relevant content" (AI-access audit 2026-08-19). No common
     # browser UA contains the substring.
     ~*grok 1;
+    # xAI's company token, for fetcher UAs that carry "xAI" but not "grok"
+    # (verified 2026-08-28: a UA "xAI-Bot" fell through ~*grok to the empty
+    # shell). No common browser UA contains the substring.
+    ~*xai 1;
     ~*youbot 1;
     ~*cohere-ai 1;
     ~*diffbot 1;
@@ -223,6 +227,16 @@ server {
         # it generates is emitted as http://, downgrading the crawler's next
         # hop. The other proxied locations already set it.
         proxy_set_header X-Forwarded-Proto https;
+        # The CRAWLER's address must reach the API: it reports each read to
+        # the bot Plausible site with the visitor IP, and Plausible drops
+        # events whose forwarded IP is a hosting-provider address. On this
+        # hop cf-connecting-ip at the API is this container's Google egress
+        # IP, so the crawler is only ever visible in X-Forwarded-For —
+        # Cloudflare put it first at the edge; $proxy_add_x_forwarded_for
+        # appends our hop instead of replacing the list (kurrentschrift
+        # measured 1 counted read in 20 without this, 2026-08-28;
+        # api/request_context.py::visitor_ip reads the list leftmost-first).
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_ssl_server_name on;
         proxy_ssl_verify on;
         # api.anyplot.ai serves a 4-deep Let's Encrypt chain (leaf -> YE1 ->
@@ -244,6 +258,14 @@ server {
         try_files $uri =404;
     }
 
+    # llms.txt has no registered .well-known name, but agents guess this path
+    # (docs/reference/seo.md "Discoverability") — answer with the file's
+    # canonical location instead of the SPA shell, which soft-404'd it with
+    # 200 + the home page until 2026-08-28.
+    location = /.well-known/llms.txt {
+        return 302 /llms.txt;
+    }
+
     # llms-full.txt is generated from the DB (one line per spec), so unlike
     # llms.txt it cannot be a static file — proxy it to the API's
     # /llms-full.txt endpoint for EVERY client, mapped crawler UA or not.
diff --git a/app/public/llms.txt b/app/public/llms.txt
index 3f720509e5..20dc7e623f 100644
--- a/app/public/llms.txt
+++ b/app/public/llms.txt
@@ -44,6 +44,7 @@ and the spec itself at `.../plots/{spec_id}/specification.md`.
 - [Plot gallery](https://anyplot.ai/plots): every rendered implementation, filterable by library, language and tags
 - [Specifications](https://anyplot.ai/specs): the library-agnostic plot specs the implementations are generated from
 - [Libraries](https://anyplot.ai/libraries): the fifteen supported plotting libraries across four languages
+- [Network map](https://anyplot.ai/map): every spec as a node, grouped by visual similarity — the catalogue's neighbourhoods (interactive; the data behind it is `GET https://api.anyplot.ai/specs/map`)
 - [Sitemap](https://anyplot.ai/sitemap.xml): every spec hub and implementation page
 
 ## Docs
diff --git a/app/public/robots.txt b/app/public/robots.txt
index 657a9163f6..9d45369602 100644
--- a/app/public/robots.txt
+++ b/app/public/robots.txt
@@ -1,3 +1,6 @@
+# llms.txt (machine guide): https://anyplot.ai/llms.txt
+# OpenAPI: https://api.anyplot.ai/openapi.json
+#
 # Crawler policy — everything here is open, to humans and machines alike.
 #
 # The catalogue is MIT-licensed and published to be reused: every plot page
@@ -37,7 +40,10 @@
 #      first-match parser lets /debug and /interactive through (verified with
 #      Python's urllib.robotparser, which is exactly such a parser).
 #
-# Content signals per contentsignals.org:
+# Content signals per contentsignals.org (these three tokens are the whole
+# vocabulary; nothing else is valid on the line — a `use=reference` token
+# used to ride along here, and a strict parser may discard the entire line
+# over an unknown token, taking the three real signals with it):
 #   search:   indexing and returning links/excerpts — yes
 #   ai-input: retrieval for AI answers, grounding, citation — yes
 #   ai-train: training or fine-tuning models — yes
@@ -50,16 +56,22 @@
 # Control does the actual enforcing. If its behaviour changes, this group can
 # go — nothing in the licence or the policy above argues against it.
 User-agent: Bytespider
-Content-Signal: search=yes,ai-input=yes,ai-train=yes,use=reference
+Content-Signal: search=yes,ai-input=yes,ai-train=yes
 Disallow: /
 
 # Everyone else: search engines, AI assistants and their training crawlers,
 # social and link previews, feed readers. /debug and /interactive are app
 # internals rather than catalogue content and are not worth crawling.
 User-agent: *
-Content-Signal: search=yes,ai-input=yes,ai-train=yes,use=reference
+Content-Signal: search=yes,ai-input=yes,ai-train=yes
 Disallow: /debug
 Disallow: /interactive
 Allow: /
 
 Sitemap: https://anyplot.ai/sitemap.xml
+
+# Machine guide for AI assistants — every retrieval recipe with a full example
+# URL (runnable source via the JSON API, render PNGs, OpenAPI, the MCP
+# endpoint), and the whole catalogue as one line per spec:
+# https://anyplot.ai/llms.txt
+# https://anyplot.ai/llms-full.txt
diff --git a/app/src/routes/seoCoverage.test.ts b/app/src/routes/seoCoverage.test.ts
new file mode 100644
index 0000000000..77fc043b0e
--- /dev/null
+++ b/app/src/routes/seoCoverage.test.ts
@@ -0,0 +1,106 @@
+// Drift guard for the machine-facing surface: the route registry in paths.ts,
+// public/llms.txt, public/robots.txt and the SPA shell (index.html) must
+// describe the SAME site and point at each other. Each of these has drifted
+// silently before — a route missing from llms.txt, a guide findable only by
+// guessing the convention, a shell that told a JS-less agent nothing — because
+// nothing coupled them. This test is that coupling; the API side of the same
+// contract (the API host's robots.txt, /llms.txt redirect, the bot-page nav)
+// lives in tests/unit/api/test_routers.py.
+//
+// The files are read through Vite's `?raw` imports rather than node:fs so the
+// test needs no Node typings — vitest resolves them exactly as the build does.
+
+import { describe, expect, it } from 'vitest';
+
+import shell from '../../index.html?raw';
+import llmsTxt from '../../public/llms.txt?raw';
+import robotsTxt from '../../public/robots.txt?raw';
+import { paths } from './paths';
+
+const ORIGIN = 'https://anyplot.ai';
+const API = 'https://api.anyplot.ai';
+
+// The public content routes are the top-level string values of paths, minus
+// the ones that are deliberately absent from the machine guide: '/' is the
+// document's own subject, /debug is an app internal (robots.txt disallows it),
+// and the search deep link is a view of /plots, not a page.
+const publicPaths = Object.values(paths)
+  .flatMap(v => (typeof v === 'string' ? [v] : []))
+  .filter(p => p !== paths.home && p !== paths.debug && !p.includes('?'));
+
+// One complete, callable example per surface. Assistants' fetch tools often
+// allow only URLs that already appeared verbatim in fetched content, so the
+// same example pair must stand in the guide AND in the shell — a template with
+// placeholders satisfies neither (kurrentschrift finding 2026-08-28).
+const EXAMPLE_CODE_URL = `${API}/specs/bar-error/seaborn/code`;
+const EXAMPLE_RENDER_URL =
+  'https://storage.googleapis.com/anyplot-images/plots/bar-error/python/seaborn/plot-light.png';
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+describe('seo coverage', () => {
+  it('llms.txt links every public content route', () => {
+    // Word-boundary match, not substring: a link to /plots must not be
+    // satisfied by /plots?focus=search, nor /specs by /specs/…. The literal
+    // parts are regex-escaped — the dots in the origin would otherwise match
+    // any character and quietly weaken the guard.
+    for (const p of publicPaths) {
+      expect(llmsTxt, `llms.txt lacks ${p}`).toMatch(
+        new RegExp(`${escapeRe(ORIGIN + p)}(?![\\w./?-])`)
+      );
+    }
+  });
+
+  it('llms.txt carries the complete example pair and the machine surfaces', () => {
+    expect(llmsTxt).toContain(EXAMPLE_CODE_URL);
+    expect(llmsTxt).toContain(EXAMPLE_RENDER_URL);
+    expect(llmsTxt).toContain(`${ORIGIN}/llms-full.txt`);
+    expect(llmsTxt).toContain(`${API}/openapi.json`);
+    expect(llmsTxt).toContain(`${API}/mcp/`);
+  });
+
+  it('robots.txt announces the sitemap and the machine guide, head and foot', () => {
+    // Two terse lines at the very top for readers that only take the file
+    // head seriously, the fuller block beside `Sitemap:` for everyone else.
+    const lines = robotsTxt.split('\n');
+    expect(lines[0]).toBe(`# llms.txt (machine guide): ${ORIGIN}/llms.txt`);
+    expect(lines[1]).toBe(`# OpenAPI: ${API}/openapi.json`);
+    expect(robotsTxt).toContain(`Sitemap: ${ORIGIN}/sitemap.xml`);
+    expect(robotsTxt).toContain(`${ORIGIN}/llms-full.txt`);
+  });
+
+  it('robots.txt uses only the three contentsignals.org tokens, in every group', () => {
+    // `use=reference` used to ride along; it is not a signal, and a strict
+    // parser may discard the whole line over an unknown token — taking the
+    // three real ones with it.
+    const signals = robotsTxt.split('\n').filter(l => l.startsWith('Content-Signal:'));
+    const groups = robotsTxt.split('\n').filter(l => l.startsWith('User-agent:'));
+    expect(signals).toHaveLength(groups.length);
+    for (const s of signals) expect(s).toBe('Content-Signal: search=yes,ai-input=yes,ai-train=yes');
+  });
+
+  it('the SPA shell itself carries the machine fallback', () => {
+    // Agents NOT in the nginx $is_bot map get the shell on every route, and
+    // most read raw HTML without executing JS. The shell must therefore name
+    // the machine guide and one complete, callable example per surface — in
+    // the head link and the <noscript> block — as ABSOLUTE URLs.
+    expect(shell).toContain('rel="alternate" type="text/plain" href="/llms.txt"');
+    // The block itself lives in the body — a head comment mentions the tag
+    // name too, so anchor the search after <body> rather than on the first
+    // occurrence of the string.
+    const bodyStart = shell.indexOf('<body>');
+    const open = shell.indexOf('<noscript>', bodyStart);
+    const close = shell.indexOf('</noscript>', open);
+    expect(open, 'no <noscript> block in the body').toBeGreaterThan(bodyStart);
+    const noscript = shell.slice(open, close);
+    expect(noscript).toContain(`href="${ORIGIN}/llms.txt"`);
+    expect(noscript).toContain(`href="${ORIGIN}/llms-full.txt"`);
+    expect(noscript).toContain(`href="${EXAMPLE_CODE_URL}"`);
+    expect(noscript).toContain(`href="${EXAMPLE_RENDER_URL}"`);
+    expect(noscript).toContain(`href="${API}/openapi.json"`);
+    expect(noscript).toContain(`href="${API}/mcp/"`);
+    // No relative machine links may creep back into the fallback — a relative
+    // href never appeared "verbatim in fetched content" as a full URL.
+    expect(noscript).not.toMatch(/href="\//);
+  });
+});
diff --git a/docs/reference/plausible.md b/docs/reference/plausible.md
index fef539a819..0a597a5bb7 100644
--- a/docs/reference/plausible.md
+++ b/docs/reference/plausible.md
@@ -241,6 +241,7 @@ events arrive server-side through the Events API, which is why it shows
 | Event | Properties | Source | Description |
 |-------|-----------|--------|-------------|
 | `bot_fetch` | `assistant`, `kind`, `path`, `status` | `api/main.py` (middleware) | An AI assistant or search crawler requested a catalogue page. Always recorded on `bots.anyplot.ai`. |
+| `asset_fetch` | `asset`, `spec`, `library`?, `assistant`, `kind`, `status` | `api/main.py` (middleware) | An AI assistant or search crawler fetched ONE thing through the API: an implementation's runnable source (`asset=code`, `GET /specs/{spec}/{library}/code`) or a spec's detail (`asset=spec`, `GET /specs/{spec}`). Lists, the map, the filter and the machine files are not recorded. Always on `bots.anyplot.ai`. See the cache caveat below. |
 | `og_image_view` | `page`, `platform`, `spec`?, `language`?, `library`?, `filter_*`?, plus `assistant` + `kind` when machine-fetched | `api/routers/og_images.py` | A preview image was fetched. **Split by audience**, see below. |
 
 #### og:image is split by who fetched it
@@ -281,17 +282,45 @@ rate-limit bucket. The rightmost entry is our own infrastructure, so reusing it
 here would discard every event. `api/request_context.py` documents why the two
 must stay separate.
 
-Register the three properties on the **`bots.anyplot.ai`** site, not on
-`anyplot.ai` — property registration is per site, and without it the events
-still arrive but cannot be broken down, which is the whole point of collecting
-them:
+The same trap has a second face on the crawler path. A prerendered page reaches
+the API through the site's nginx (Cloud Run app → Cloudflare → API), so on that
+hop `cf-connecting-ip` is the **app container's Google egress address** — a
+hosting-provider IP, dropped — while the crawler itself is only visible as the
+first `x-forwarded-for` entry, where the site-side Cloudflare put it.
+kurrentschrift measured the effect with probe events on 2026-08-28 (`34.90.x`
+and `35.204.x` dropped, a home IP kept): one counted read in twenty. Since
+2026-08-28 `visitor_ip` therefore reads the forwarded list **first** and falls
+back to `cf-connecting-ip`, and nginx's `@seo_proxy` forwards the crawler in
+`X-Forwarded-For` explicitly. For a direct client behind Cloudflare both
+headers name the same address, so nothing changes there. If `bot_fetch` counts
+ever look implausibly low again, this is the first thing to re-verify: the
+daily `bot-serving-check` fires ~25 crawler requests from a GitHub runner at
+06:23 UTC and should be visible on the bot site as that many events.
+
+Register the properties on the **`bots.anyplot.ai`** site, not on `anyplot.ai`
+— property registration is per site, and without it the events still arrive
+but cannot be broken down, which is the whole point of collecting them.
+`asset_fetch` also needs a **goal** (Custom event) of that name before the
+dashboard can break it down:
 
 | Property | Description | Used by |
 |----------|-------------|---------|
-| `assistant` | Vendor (`claude`, `chatgpt`, `gemini`, `mistral`, `perplexity`, `meta`, `amazon`, `duckduckgo`, `grok`, `google`, `bing`, …) | `bot_fetch` |
-| `kind` | Why it fetched — see the table below | `bot_fetch` |
+| `assistant` | Vendor (`claude`, `chatgpt`, `gemini`, `mistral`, `perplexity`, `meta`, `amazon`, `duckduckgo`, `grok`, `google`, `bing`, …) | `bot_fetch`, `asset_fetch` |
+| `kind` | Why it fetched — see the table below | `bot_fetch`, `asset_fetch` |
 | `path` | Public path that was requested, e.g. `/box-basic/python/matplotlib` | `bot_fetch` |
-| `status` | Response status as a string (`200`, `404`, …) | `bot_fetch` |
+| `status` | Response status as a string (`200`, `404`, …) | `bot_fetch`, `asset_fetch` |
+| `asset` | What was fetched through the API: `code` (one implementation's runnable source) or `spec` (one spec's detail) | `asset_fetch` |
+| `spec` | The spec id, e.g. `box-basic` | `asset_fetch` |
+| `library` | The library id for a `code` read, e.g. `seaborn`; absent on a `spec` read | `asset_fetch` |
+
+`asset_fetch` counts **cache misses**, not requests: the two routes answer
+`public, max-age=300` and are also what the SPA fetches, so Cloudflare serves
+repeat reads from its edge and those never reach the middleware. For sporadic
+assistant traffic — one assistant, one plot, minutes apart — nearly every read
+is a miss, so the number is close; it is not exact. The alternative (dropping
+the edge cache for routes the SPA needs on every spec page) was not worth the
+precision. Filter on `asset`, then break down by `spec` for "which plots do
+assistants pull the code of", and by `library` within `asset=code`.
 
 Filter on `status` before reading anything else. The event records the
 *request*, not a successful read: an assistant asking for a URL that no longer
diff --git a/docs/reference/seo.md b/docs/reference/seo.md
index f150765e6f..9436843497 100644
--- a/docs/reference/seo.md
+++ b/docs/reference/seo.md
@@ -98,7 +98,7 @@ asked about a plot page could describe nothing at all.
 | DuckDuckGo AI | `duckassistbot` |
 | Amazon (retrieval) | `amzn-searchbot`, `amzn-user` |
 | Meta AI search | `meta-webindexer` |
-| xAI / Grok · You.com · Cohere | `grokbot`, `xai-grok`, `grok-deepsearch`, `youbot`, `cohere-ai` — community-reported tokens, no vendor documentation; best-effort |
+| xAI / Grok · You.com · Cohere | `grok` (subsumes grokbot, xai-grok, grok-deepsearch and the bare `Grok` token), `xai` (an `xAI-Bot` UA without the grok substring fell through to the shell, 2026-08-28), `youbot`, `cohere-ai` — community-reported tokens, no vendor documentation; best-effort |
 
 Three vendor splits are easy to get backwards, so they are spelled out:
 
@@ -343,12 +343,23 @@ group verbatim; read the file for the rest:
 
 ```txt
 User-agent: Bytespider
-Content-Signal: search=yes,ai-input=yes,ai-train=yes,use=reference
+Content-Signal: search=yes,ai-input=yes,ai-train=yes
 Disallow: /
 ```
 
-Three properties of that file are deliberate and should survive any cleanup:
+The file opens with two terse comment lines naming `llms.txt` and the OpenAPI
+spec, and closes with a fuller block beside `Sitemap:` that also names
+`llms-full.txt` — see [Discoverability for assistants](#discoverability-for-assistants)
+for why a guide that nothing points to is findable only by guessing.
 
+Four properties of that file are deliberate and should survive any cleanup:
+
+- The `Content-Signal` line carries exactly the three
+  [contentsignals.org](https://contentsignals.org) tokens — `search`,
+  `ai-input`, `ai-train` — and nothing else. A `use=reference` token used to
+  ride along; it is not a signal, and a strict parser may discard the whole
+  line over an unknown token, taking the three real ones with it (dropped
+  2026-08-28, after kurrentschrift verified the vocabulary).
 - The `Content-Signal` line is repeated in **every** group. A crawler reads only
   the group that matches it, so a signal declared once under `User-agent: *`
   never reaches a named agent.
@@ -364,7 +375,12 @@ Three properties of that file are deliberate and should survive any cleanup:
 Dynamic endpoint at `GET /robots.txt`:
 
 ```txt
+# api.anyplot.ai — the open read API of anyplot.ai (JSON, no auth).
+# Machine guide with every retrieval recipe and full example URLs:
+# https://anyplot.ai/llms.txt — catalogue index: https://anyplot.ai/llms-full.txt
+# OpenAPI: https://api.anyplot.ai/openapi.json — MCP: https://api.anyplot.ai/mcp/
 User-agent: *
+Content-Signal: search=yes,ai-input=yes,ai-train=yes
 Disallow: /debug
 Disallow: /proxy
 Allow: /
@@ -377,6 +393,14 @@ host `llms.txt` advertises as the machine interface to the catalogue
 (AI-access audit 2026-08-19). Only `/debug` (internal diagnostics) and
 `/proxy` (a parameterised fetch proxy) stay excluded. `Disallow` lines come
 before the `Allow: /` catch-all for the first-match parsers described above.
+The comment head names the guide because this is the host an agent may reach
+first — through the README, a citation, a search result — and the
+`Content-Signal` line states the site's one policy on every host it covers.
+
+The API host also answers `GET /llms.txt` with a `302` to
+`https://anyplot.ai/llms.txt`: agents guess the convention on the host the
+README and both robots.txt files name, and a redirect beats a 404 and beats a
+served copy that would drift.
 
 ### AI crawler policy
 
@@ -452,6 +476,49 @@ onto the seo-proxy path, and `.github/workflows/bot-serving-check.yml` guards it
 daily against the Cloud Run origin (origin, not edge — so it reports on the
 nginx map no matter what the zone policy is, and will never catch edge drift).
 
+## Discoverability for assistants
+
+Two session protocols of external assistants against the sister project
+kurrentschrift (2026-08-28) showed the machine-facing chain failing at its
+first link: an assistant's fetch tool often allows only URLs that **already
+appeared verbatim in fetched content or a search result**. A URL the assistant
+composes itself, a path elided with `…` in a README, a relative link, or the
+bare `/llms.txt` convention are not enough — and the API host is in no search
+index. So the guide and one complete, callable example per surface stand
+wherever an agent actually reads, ranked by reach:
+
+1. **The SPA shell** (`app/index.html`), served on every route to every client
+   the nginx map does not recognise: a `<link rel="alternate" type="text/plain"
+   href="/llms.txt">` in the head and a `<noscript>` block with the **absolute**
+   URLs of `llms.txt`, `llms-full.txt`, one implementation's code endpoint
+   (`https://api.anyplot.ai/specs/bar-error/seaborn/code`, with the note that
+   spec id and library id are free parameters), one render PNG, `openapi.json`
+   and the MCP endpoint. Invisible in the rendered app; a JS-off human gets a
+   useful paragraph. Hidden indexable text beyond `<noscript>` was rejected
+   (cloaking risk).
+2. **Guessed paths resolve**: `/.well-known/llms.txt` on the site answers `302
+   /llms.txt` (nginx; it used to soft-404 with the SPA shell), and `/llms.txt`
+   on the API host redirects to the site file (`api/routers/seo.py`).
+3. **Both `robots.txt` files name the guide** — two terse lines at the very top
+   of the site file for readers that only take the file head seriously, a
+   fuller block beside `Sitemap:`, and the API host's comment head.
+4. **Every bot page links the guide** as a full URL in its footer nav, and every
+   implementation page spells out its own code URL in prose and carries a
+   visible `<pre><code class="language-json">` retrieval record (page, hub,
+   `code_json`, `spec_json`, renders, interactive versions, quality score)
+   beside the JSON-LD — the HTML-to-Markdown converters assistants read pages
+   through drop `<script>` and keep `<pre>`.
+
+The nginx `$is_bot` map, the `AI_AGENTS` taxonomy and the robots.txt file
+shape are shared verbatim with kurrentschrift (owner decision 2026-08-28): a
+change on one site is copied to the other in the same session.
+
+Guards: `app/src/routes/seoCoverage.test.ts` pins llms.txt ↔ route registry ↔
+robots.txt ↔ shell (including the example pair, which must be the same in the
+guide and the shell); `tests/unit/api/test_routers.py` pins the API host's
+robots.txt, the `/llms.txt` redirect, the nav links and the implementation
+record; `bot-serving-check.yml` probes the `.well-known` redirect daily.
+
 ## Sitemap
 
 Dynamic XML sitemap for search engine indexing.
@@ -632,10 +699,12 @@ curl -o test.png https://api.anyplot.ai/og/scatter-basic.png
 
 | File | Purpose |
 |------|---------|
-| `app/nginx.conf` | Bot detection, SPA routing, sitemap proxy |
-| `app/public/robots.txt` | Frontend robots.txt (content signals, AI crawler policy, blocks /debug) |
+| `app/nginx.conf` | Bot detection, SPA routing, sitemap proxy, `.well-known/llms.txt` redirect |
+| `app/public/robots.txt` | Frontend robots.txt (content signals, AI crawler policy, blocks /debug, names the machine guide) |
 | `app/public/llms.txt` | Agent-facing site summary; served directly, never via the seo-proxy |
-| `api/routers/seo.py` | SEO proxy endpoints, robots.txt, sitemap generation |
+| `app/index.html` | SPA shell; its head link and `<noscript>` block are the machine fallback for unmapped agents |
+| `app/src/routes/seoCoverage.test.ts` | Drift guard: llms.txt ↔ route registry ↔ robots.txt ↔ shell |
+| `api/routers/seo.py` | SEO proxy endpoints, robots.txt, `/llms.txt` redirect, sitemap generation |
 | `api/routers/og_images.py` | Branded og:image endpoints |
 | `core/images.py` | Image processing, branding functions |
 | `.github/workflows/bot-serving-check.yml` | Daily synthetic check of the bot → seo-proxy path |
diff --git a/tests/unit/api/test_analytics.py b/tests/unit/api/test_analytics.py
index 2ffbfa7813..f009f53a6f 100644
--- a/tests/unit/api/test_analytics.py
+++ b/tests/unit/api/test_analytics.py
@@ -11,8 +11,10 @@
     DOMAIN,
     PLATFORM_PATTERNS,
     _detect_whatsapp_variant,
+    classify_asset,
     detect_ai_agent,
     detect_platform,
+    track_asset_fetch,
     track_bot_fetch,
     track_og_image,
 )
@@ -340,6 +342,11 @@ class TestDetectAiAgent:
             ("Mozilla/5.0 (compatible; Googlebot/2.1)", ("google", "search")),
             ("Mozilla/5.0 (compatible; Google-InspectionTool/1.0)", ("google", "inspection")),
             ("Mozilla/5.0 (compatible; bingbot/2.0)", ("bing", "search")),
+            # The bare xAI tokens the nginx map serves: plain "Grok" (seen
+            # 2026-08-19) and "xAI-Bot" without the grok substring (2026-08-28)
+            # were prerendered but not counted until these patterns existed.
+            ("Grok/1.0", ("grok", "user_directed")),
+            ("Mozilla/5.0 (compatible; xAI-Bot/1.0)", ("grok", "user_directed")),
         ],
     )
     def test_classifies(self, user_agent: str, expected: tuple[str, str]) -> None:
@@ -565,6 +572,16 @@ def _request(headers: dict[str, str]) -> MagicMock:
             ({"x-forwarded-for": "unknown, 84.75.12.9"}, "84.75.12.9"),
             ({"cf-connecting-ip": "garbage", "x-forwarded-for": "84.75.12.9"}, "84.75.12.9"),
             ({"x-forwarded-for": "2a02:1210::1, 10.0.0.1"}, "2a02:1210::1"),
+            # The crawler path (Cloud Run app -> Cloudflare -> API): the site's
+            # Cloudflare put the crawler first in x-forwarded-for, and
+            # cf-connecting-ip is the app container's Google egress address —
+            # the "hosting provider IP" Plausible drops. The forwarded list
+            # must win, or one crawler read in twenty gets counted.
+            ({"cf-connecting-ip": "34.90.1.1", "x-forwarded-for": "84.75.12.9, 172.68.0.1, 34.90.1.1"}, "84.75.12.9"),
+            # A direct client behind Cloudflare: both headers name the visitor
+            ({"cf-connecting-ip": "84.75.12.9", "x-forwarded-for": "84.75.12.9"}, "84.75.12.9"),
+            # cf-connecting-ip is still the fallback when nothing is forwarded
+            ({"cf-connecting-ip": "84.75.12.9"}, "84.75.12.9"),
             # nothing usable anywhere: fall back to the socket peer
             ({"x-forwarded-for": "nonsense"}, "127.0.0.1"),
             ({}, "127.0.0.1"),
@@ -576,6 +593,104 @@ def test_skips_tokens_that_are_not_addresses(self, headers: dict[str, str], expe
         assert visitor_ip(self._request(headers)) == expected
 
 
+class TestClassifyAsset:
+    """Which API paths are a request for ONE thing, and what thing."""
+
+    @pytest.mark.parametrize(
+        ("path", "expected"),
+        [
+            ("/specs/bar-basic/seaborn/code", ("code", "bar-basic", "seaborn")),
+            ("/specs/scatter-3d/mui-x-charts/code", ("code", "scatter-3d", "mui-x-charts")),
+            ("/specs/bar-basic", ("spec", "bar-basic", None)),
+            # navigation, not an asset
+            ("/specs", None),
+            ("/specs/map", None),
+            ("/specs/bar-basic/images", None),
+            ("/plots/filter", None),
+            ("/seo-proxy/bar-basic", None),
+            ("/llms-full.txt", None),
+            # not a spec id shape: nothing reaches the classifier with a query
+            # string, but a malformed segment must not become a dashboard key
+            ("/specs/Bar_Basic", None),
+            ("/specs/bar-basic/seaborn/code/", None),
+        ],
+    )
+    def test_classifies(self, path: str, expected: tuple[str, str, str | None] | None) -> None:
+        assert classify_asset(path) == expected
+
+
+class TestTrackAssetFetch:
+    """Which plots do assistants actually pull the code of."""
+
+    @staticmethod
+    def _request(user_agent: str, path: str) -> MagicMock:
+        request = MagicMock()
+        request.headers = {"user-agent": user_agent, "x-forwarded-for": "84.75.12.9"}
+        request.url.path = path
+        request.client.host = "127.0.0.1"
+        return request
+
+    @pytest.mark.asyncio
+    async def test_records_the_asset_against_the_bot_site(self) -> None:
+        with patch("api.analytics.httpx.AsyncClient") as mock_client_class:
+            mock_client = AsyncMock()
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+
+            request = self._request("Mozilla/5.0 (compatible; Claude-User/1.0)", "/specs/bar-basic/seaborn/code")
+            track_asset_fetch(request, asset="code", spec="bar-basic", library="seaborn", status=200)
+            await asyncio.sleep(0)
+
+            payload = mock_client.post.call_args[1]["json"]
+            assert payload["name"] == "asset_fetch"
+            assert payload["domain"] == BOT_DOMAIN
+            assert payload["url"] == "https://api.anyplot.ai/specs/bar-basic/seaborn/code"
+            assert payload["props"] == {
+                "asset": "code",
+                "spec": "bar-basic",
+                "library": "seaborn",
+                "assistant": "claude",
+                "kind": "user_directed",
+                "status": "200",
+            }
+            # The crawler's own address, never a hosting-provider one
+            assert mock_client.post.call_args[1]["headers"]["X-Forwarded-For"] == "84.75.12.9"
+
+    @pytest.mark.asyncio
+    async def test_a_spec_read_carries_no_library(self) -> None:
+        with patch("api.analytics.httpx.AsyncClient") as mock_client_class:
+            mock_client = AsyncMock()
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+
+            track_asset_fetch(
+                self._request("Mozilla/5.0 (compatible; GPTBot/1.4)", "/specs/bar-basic"),
+                asset="spec",
+                spec="bar-basic",
+                library=None,
+                status=200,
+            )
+            await asyncio.sleep(0)
+
+            props = mock_client.post.call_args[1]["json"]["props"]
+            assert "library" not in props
+            assert props["assistant"] == "chatgpt"
+            assert props["kind"] == "training"
+
+    @pytest.mark.asyncio
+    async def test_sends_nothing_for_a_browser(self) -> None:
+        """The SPA fetches the same routes; a human's read is not an assistant's."""
+        with patch("api.analytics.httpx.AsyncClient") as mock_client_class:
+            mock_client = AsyncMock()
+            mock_client_class.return_value.__aenter__.return_value = mock_client
+
+            request = self._request(
+                "Mozilla/5.0 (X11; Linux) Chrome/126.0 Safari/537.36", "/specs/bar-basic/seaborn/code"
+            )
+            track_asset_fetch(request, asset="code", spec="bar-basic", library="seaborn", status=200)
+            await asyncio.sleep(0)
+
+            mock_client.post.assert_not_called()
+
+
 class TestBotFetchRecordsTheStatus:
     """A miss is a signal, but it is not a page read — so record it, don't hide it."""
 
diff --git a/tests/unit/api/test_routers.py b/tests/unit/api/test_routers.py
index 1f04dff3fa..b42333106b 100644
--- a/tests/unit/api/test_routers.py
+++ b/tests/unit/api/test_routers.py
@@ -634,6 +634,38 @@ def test_robots_txt(self, client: TestClient) -> None:
         # Specific exclusions must precede the catch-all: a first-match parser
         # stops at Allow: / and would never reach them.
         assert content.index("Disallow: /debug") < content.index("Allow: /")
+        # The site's open policy, stated on this host too — and only the three
+        # contentsignals.org tokens, never the invalid `use=reference` that
+        # used to ride along on the site file.
+        assert "Content-Signal: search=yes,ai-input=yes,ai-train=yes\n" in content
+        assert "use=reference" not in content
+        # The guide is only findable by guessing the convention unless the
+        # files an agent actually fetches point to it.
+        assert "https://anyplot.ai/llms.txt" in content
+        assert "https://anyplot.ai/llms-full.txt" in content
+        assert "https://api.anyplot.ai/openapi.json" in content
+
+    def test_llms_txt_on_the_api_host_redirects_to_the_site_file(self, client: TestClient) -> None:
+        """Agents guess /llms.txt on the host the README and robots.txt name.
+
+        A redirect to the one source of truth beats the 404 this used to be,
+        and beats a served copy that would drift.
+        """
+        response = client.get("/llms.txt", follow_redirects=False)
+        assert response.status_code == 302
+        assert response.headers["location"] == "https://anyplot.ai/llms.txt"
+
+    def test_bot_nav_links_the_machine_files_as_full_urls(self, client: TestClient) -> None:
+        """Every bot page must let an assistant reach the guide from where it landed.
+
+        Fetch tools often allow only URLs that already appeared verbatim in
+        fetched content — a guide linked from nothing is findable only by
+        guessing.
+        """
+        with patch(DB_CONFIG_PATCH, return_value=False):
+            response = client.get("/seo-proxy/")
+        assert '<a href="https://anyplot.ai/llms.txt">llms.txt</a>' in response.text
+        assert '<a href="https://anyplot.ai/llms-full.txt">llms-full.txt</a>' in response.text
 
     def test_llms_full_txt_without_db(self, client: TestClient) -> None:
         """llms-full.txt degrades to the header (retrieval recipes) without a DB."""
@@ -747,9 +779,47 @@ def test_seo_proxy_home_records_root(self, client: TestClient) -> None:
 
     def test_robots_and_sitemap_are_not_page_reads(self, client: TestClient) -> None:
         """Both live on this router but are machine files, not catalogue pages."""
-        with patch("api.main.track_bot_fetch") as track:
+        with patch("api.main.track_bot_fetch") as track, patch("api.main.track_asset_fetch") as asset:
             client.get("/robots.txt", headers={"User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)"})
             client.get("/sitemap.xml", headers={"User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)"})
+            client.get(
+                "/llms.txt", headers={"User-Agent": "Mozilla/5.0 (compatible; Googlebot/2.1)"}, follow_redirects=False
+            )
+        track.assert_not_called()
+        asset.assert_not_called()
+
+    def test_an_assistant_reading_one_implementation_s_code_is_an_asset_fetch(self, client: TestClient) -> None:
+        """The API read that follows a page read: which plot's code did it pull."""
+        with patch(DB_CONFIG_PATCH, return_value=False), patch("api.main.track_asset_fetch") as track:
+            response = client.get(
+                "/specs/bar-basic/seaborn/code", headers={"User-Agent": "Mozilla/5.0 (compatible; Claude-User/1.0)"}
+            )
+        track.assert_called_once()
+        assert track.call_args.kwargs == {
+            "asset": "code",
+            "spec": "bar-basic",
+            "library": "seaborn",
+            "status": response.status_code,
+        }
+
+    def test_an_assistant_reading_one_spec_is_an_asset_fetch(self, client: TestClient) -> None:
+        with patch(DB_CONFIG_PATCH, return_value=False), patch("api.main.track_asset_fetch") as track:
+            response = client.get(
+                "/specs/bar-basic", headers={"User-Agent": "Mozilla/5.0 (compatible; Claude-User/1.0)"}
+            )
+        track.assert_called_once()
+        assert track.call_args.kwargs == {
+            "asset": "spec",
+            "spec": "bar-basic",
+            "library": None,
+            "status": response.status_code,
+        }
+
+    def test_catalogue_navigation_is_not_an_asset_fetch(self, client: TestClient) -> None:
+        """Lists, the map and the filter are navigation, not a request for one thing."""
+        with patch(DB_CONFIG_PATCH, return_value=False), patch("api.main.track_asset_fetch") as track:
+            for path in ("/specs", "/specs/map", "/plots/filter?plot=bar", "/libraries", "/llms-full.txt"):
+                client.get(path, headers={"User-Agent": "Mozilla/5.0 (compatible; Claude-User/1.0)"})
         track.assert_not_called()
 
     def test_seo_home_canonical_ignores_filter_params(self, client: TestClient) -> None:
@@ -943,6 +1013,14 @@ def test_seo_spec_implementation_with_preview_url(self, db_client, mock_spec) ->
             assert "api.anyplot.ai/og/scatter-basic/python/matplotlib.png" in response.text
             # Enriched body carries the implementation source for crawlers
             assert "<pre><code>import matplotlib.pyplot as plt</code></pre>" in response.text
+            # ...and its own retrieval record: the complete, callable code URL
+            # in prose AND in a visible JSON block (HTML-to-Markdown converters
+            # drop <script>, so the JSON-LD alone never reaches an assistant).
+            code_url = "https://api.anyplot.ai/specs/scatter-basic/matplotlib/code"
+            assert f'<a href="{code_url}">{code_url}</a>' in response.text
+            assert '<pre><code class="language-json">' in response.text
+            assert f"&quot;code_json&quot;: &quot;{code_url}&quot;" in response.text
+            assert "&quot;spec_json&quot;: &quot;https://api.anyplot.ai/specs/scatter-basic&quot;" in response.text
 
     def test_seo_spec_implementation_not_found(self, db_client) -> None:
         """SEO spec implementation should return 404 when spec not found."""
@@ -1051,8 +1129,12 @@ def test_seo_spec_implementation_fallback_image(self, db_client, mock_spec) -> N
             response = client.get("/seo-proxy/scatter-basic/python/seaborn")
             assert response.status_code == 200
             assert "api.anyplot.ai/og/home.png" in response.text  # Default image via API
-            # No stored code -> no <pre> block, page still renders
-            assert "<pre>" not in response.text
+            # No stored code -> no source block, page still renders — and the
+            # retrieval record (its own <pre>, class language-json) stays, so
+            # an assistant can still reach the code endpoint from the page.
+            assert "<pre><code>" not in response.text
+            assert '<pre><code class="language-json">' in response.text
+            assert "https://api.anyplot.ai/specs/scatter-basic/seaborn/code" in response.text
 
     def test_seo_about(self, client: TestClient) -> None:
         """SEO about page must carry the pipeline story, not just og:tags."""
diff --git a/tests/unit/api/test_seo_helpers.py b/tests/unit/api/test_seo_helpers.py
index 3e6d070555..494937a599 100644
--- a/tests/unit/api/test_seo_helpers.py
+++ b/tests/unit/api/test_seo_helpers.py
@@ -439,7 +439,11 @@ def test_jsonld_without_render_keeps_card_image(self) -> None:
 
     def test_no_code_no_pre_block(self) -> None:
         page = self._page(code=None)
-        assert "<pre>" not in page
+        # No source block — the retrieval record has its own <pre> (class
+        # language-json) and must stay, so an assistant can still reach the
+        # code endpoint from a page whose source is not stored.
+        assert "<pre><code>" not in page
+        assert '<pre><code class="language-json">' in page
         # page is still enriched otherwise
         assert '<a href="https://anyplot.ai/scatter-basic">' in page
 
@@ -658,6 +662,7 @@ def _impl(self, interactive: bool = True) -> MagicMock:
         impl.preview_html_light = f"{self.BASE}/plot-light.html" if interactive else None
         impl.preview_html_dark = f"{self.BASE}/plot-dark.html" if interactive else None
         impl.updated = None  # serialized into JSON-LD — must not be a MagicMock
+        impl.quality_score = None  # serialized into the retrieval record — same rule
         return impl
 
     def test_names_both_themes_explicitly(self) -> None: