# TailMux SEO/GEO measurement plan

## Purpose

Measure whether TailMux becomes easier to find, understand, cite, and install
without adding invasive client tracking or inventing a baseline.

**Baseline:** not available in the repository. Establish it after production
deployment using the systems below; record dates, properties, filters, and
exported values rather than estimates.

## Existing instrumentation

| Signal | Current implementation | Limitation |
|---|---|---|
| Page views | OpenPanel screen_view on client-side route changes | Crawlers and plain text endpoints do not execute client JavaScript. |
| First-touch attribution | query-stripped referrer, landing path, and UTM fields in OpenPanel | Does not classify every AI answer-engine referrer automatically. |
| Download intent | download_clicked event | Event payload must remain PII-free. |
| Commercial funnel | checkout_started, checkout_completed, checkout_failed | Client/user event, not crawler data. |
| Account/device actions | signup_completed, portal_opened, seats_checkout_started, device_deactivated | Not an SEO signal by itself. |
| Error visibility | Sentry wiring | Does not replace HTTP/crawler logs. |
| Server/CDN requests | Cloudflare and Bun server logs are operationally available, but no structured crawler event exists in source | Must be queried/configured outside OpenPanel. |

## Metrics and definitions

| Metric | Definition | Source | Baseline / target | Review |
|---|---|---|---|---|
| Organic sessions | sessions with an organic-search referrer | OpenPanel plus Search Console/Bing | establish 28-day baseline; target is directionally up after indexation | weekly |
| Non-branded landing sessions | organic entrances to broad guide, macOS, Linux, and workflow pages excluding homepage-only brand traffic | OpenPanel + Search Console query/page report | establish baseline; target is more non-branded entries with qualified navigation | weekly |
| Branded landing sessions | organic entrances associated with TailMux/tailmux.app queries | Search Console/Bing query report | establish baseline; monitor entity disambiguation | weekly |
| Documentation entrances | sessions whose first path is a docs route | OpenPanel landing_path | establish baseline; target is growing qualified docs entry share | monthly |
| Guide entrances | sessions whose first path is a guide route | OpenPanel landing_path | establish baseline; target is growing non-branded share | monthly |
| Download intent | download_clicked divided by indexable marketing/docs sessions | OpenPanel | establish baseline; diagnose page-level changes, not a fixed universal target | monthly |
| Pricing interest | visits to /pricing and checkout_started rate | OpenPanel | establish baseline | monthly |
| Onboarding success | activation/first-profile event only if a privacy-safe server-side signal becomes available | product telemetry, if explicitly approved | no baseline yet | monthly |
| Markdown requests | 2xx requests to .md endpoints | Cloudflare/Bun logs | establish crawler/user baseline; target is valid machine use, not raw volume | monthly |
| LLM file requests | 2xx requests to /llms.txt and /llms-full.txt | Cloudflare/Bun logs | establish baseline by user agent | monthly |
| AI retrieval referrals | referrers from chatgpt.com, perplexity.ai, copilot.microsoft.com, gemini.google.com, claude.ai when present | OpenPanel attribution + server/CDN logs | establish baseline; interpret cautiously because referrer policies vary | monthly |
| Search crawler health | 2xx/3xx/4xx/5xx by verified crawler and key resource | Cloudflare/Bun logs, Search Console, Bing | zero avoidable 4xx/5xx on canonical HTML, sitemap, robots, LLM, Markdown | weekly |
| Sitemap health | sitemap fetches and parsing/indexing errors | Search Console/Bing + logs | no parse errors | weekly after deploy |
| Crawl freshness | time between meaningful content deployment and crawler fetch | logs + webmaster tools | record first re-crawl; no fabricated SLA | monthly |
| Internal 404s | 404 responses with internal referrer and broken path | CDN/server logs | zero known broken internal links | weekly |

## Required server/CDN log fields

Use Cloudflare logs or the production Bun server logs to capture:

- timestamp;
- request path without query string;
- response status;
- request method;
- user-agent;
- normalized crawler classification;
- cache status where available;
- referrer origin only, with query strings excluded;
- response time and bytes where available.

Do not log auth tokens, full query strings, license keys, IP addresses in product
analytics, or Markdown/body content. A minimal structured crawler event for
known bots is sufficient and should be sampled only from public routes.

## Crawler and AI resource dashboard

Create one CDN/log dashboard with these saved filters:

1. public canonical HTML paths, status not in 200/304/301/302/307;
2. sitemap.xml, robots.txt, llms.txt, llms-full.txt, and Markdown routes;
3. Googlebot, Bingbot, Applebot, OAI-SearchBot, ChatGPT-User,
   Claude-SearchBot, Claude-User, PerplexityBot, and Google-Extended policy
   validation traffic where identifiable;
4. GPTBot and ClaudeBot to verify the stated training policy is respected;
5. Cloudflare bot/WAF blocks, managed challenges, rate-limit hits, and 5xx;
6. external referrers whose host contains chatgpt, perplexity, copilot, gemini,
   or claude.

## Search Console and Bing reporting

After deployment:

- submit the canonical sitemap to Google Search Console and Bing Webmaster
  Tools;
- verify the exact property for https://tailmux.app;
- inspect the homepage, broad guide, macOS guide, Linux guide, limits
  reference, and a Markdown alternate;
- export query/page reports for the branded and non-branded clusters in
  docs/seo-geo-query-map.md;
- record impressions, clicks, CTR, average position, crawl errors, excluded
  pages, and canonical decisions with the export date.

## Review cadence

| Cadence | Owner action |
|---|---|
| First 72 hours after deploy | Confirm endpoints, canonicals, robots, sitemap, noindex Markdown, and Cloudflare/WAF behavior. |
| Weekly for 8 weeks | Review crawler errors, sitemap health, non-branded impressions, page indexability, and broken links. |
| Monthly | Compare branded/non-branded entrances, documentation/guide entrances, download intent, and AI-referral evidence. |
| Quarterly | Refresh query map, technical claims, official Tailscale references, structured data, release/product identity, and off-site profiles. |

## Interpretation rules

- A crawler request is not proof of ranking or citation.
- A missing AI referrer is not proof of zero AI visibility; referrer policies
  may suppress it.
- Do not compare periods with materially different deployment, launch, or paid
  campaign activity without annotating the change.
- Use page/query evidence before rewriting a page for a keyword. Preserve the
  page’s intent boundary unless data demonstrates a true mismatch.
