> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trybluesky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Frequently Asked Questions

> Answers to the most common questions about Bluesky's Agent Edge Network — detection, serving, SEO safety, and shadow mode.

Whether you're evaluating Bluesky for the first time or troubleshooting a specific behaviour, the questions below cover the most common things customers ask. If you're just getting started, the [Edge Network overview](/guides/edge-network-overview) walks through the full install.

<AccordionGroup>
  <Accordion title="No hits appear in Agent Analytics — what should I check?">
    Work through these in order:

    1. **Is `AEN_EDGE_TOKEN` set as a Vercel environment variable?** A local `.env` file is not enough. If the token is blank, the middleware returns `NextResponse.next()` on the very first line and does nothing — no detection, no telemetry.
    2. **Is the middleware actually deployed?** Confirm `middleware.ts` is at the root of your Next.js app and shows up as an Edge Function in your Vercel project's **Functions** tab.
    3. **Did you trigger a real browsing AI?** Visiting your own site in a browser won't generate a hit. You need to ask **ChatGPT** or **Perplexity** (with browsing enabled) a question that causes their crawler to fetch a URL on your domain.

    Note on verification: the drop-in middleware records telemetry for any matched answer-engine agent, but only **verified** hits are ever served the optimized variant. A bot that matches by user-agent string alone — but whose source IP isn't inside the vendor's published CIDR ranges — is classified as `UA_ONLY` and is always passed through to your normal page.
  </Accordion>

  <Accordion title="A page isn't being served the optimized version — why?">
    In the drop-in middleware, every one of these must be true before the variant is served:

    1. **The bot must be verified.** The middleware verifies the request's source IP against the vendor's published CIDR ranges (`IP_VERIFIED`). A `UA_ONLY` match is never served the variant.
    2. **The bot's purpose class must be `USER_TRIGGERED` or `RETRIEVAL`.** Other purpose classes pass through, even when the bot is verified.
    3. **`SERVE_MODE` must be `"default"`.** The middleware ships in `"shadow"`, which logs requests but always serves your normal page. Change the constant in `middleware.ts` to `"default"` and redeploy.
    4. **An artifact must exist for the URL.** If Bluesky hasn't generated one yet, the middleware degrades to your normal page — it never fabricates a response.

    Separately, classic search bots (Googlebot / Bingbot / Applebot) are always passed through by the cloaking firewall, no matter what — see the SEO question below.
  </Accordion>

  <Accordion title="Is this safe for SEO?">
    Yes — and this is enforced in code, not left to configuration. The serve rule contains an explicit **cloaking firewall**: if an incoming bot is flagged `isSearchIndex` in the Bluesky botset, the middleware immediately returns your normal page without branching. **Googlebot, Bingbot, and Applebot always get your normal page**, full stop. The control plane also strips `SEARCH_INDEX` from a site's enabled purposes defensively, so it can never be turned on.

    This matters especially because Google's AI Overviews run on Googlebot and the same search index as Google Search. Serving Googlebot a different version would be cloaking Google Search itself — a clear policy violation. Bluesky never does this.

    For the non-search answer-engine agents that Bluesky does serve (such as `OAI-SearchBot`, `Claude-SearchBot`, and `PerplexityBot`), the artifact is a pure extraction-and-restructure of your existing page — the same substance, reformatted into answer-first markdown and JSON-LD. A strict-parity grounding guardrail rejects any artifact that introduces content the source page didn't contain, so nothing is added or invented.

    See the [cloaking firewall guide](/guides/cloaking-firewall) for the full rule.
  </Accordion>

  <Accordion title="Can I use Bluesky without Vercel or Next.js?">
    The shipped drop-in today is a **Next.js edge middleware** that runs on the Vercel Edge runtime. If your stack is different, a **Cloudflare Worker adapter** and a zero-code **CNAME reverse-proxy** option are in development. Reach out via in-app chat to discuss your stack or ask about early access.
  </Accordion>

  <Accordion title="What does the edge token do, and is it the same as my account API key?">
    The **edge token** (`AEN_EDGE_TOKEN`) is a separate, site-scoped credential, distinct from your Bluesky account credentials. It has the format `aen_...`, is scoped to exactly one domain, and can be rotated at any time — re-provisioning the site mints a fresh token without affecting the rest of your account.

    Its job is to authenticate the middleware's calls to the Bluesky control plane (`Authorization: Bearer <edgeToken>`): fetching the botset, fetching artifacts, and posting telemetry hits. Because it's site-scoped and revocable, the blast radius of a leaked token is limited to that one site's edge configuration.

    The token is returned in full **only once**, at provision time, so copy it straight into Vercel's environment variable store rather than committing it to your repository. If you lose it, re-provision the site to mint a new one.
  </Accordion>

  <Accordion title="What is shadow mode and why should I start there?">
    Shadow mode (`SERVE_MODE = "shadow"`) is the default in the downloadable `middleware.ts`. In this mode the middleware runs the full detection and verification pipeline on every request and logs what it *would* have served, but always delivers your normal page to every visitor — human or bot.

    Starting in shadow mode lets you confirm that:

    * The middleware is deployed and receiving requests.
    * `AEN_EDGE_TOKEN` is set and the control plane is reachable.
    * Verified AI crawler hits are appearing in Agent Analytics.
    * The artifacts Bluesky has generated look right — the Agent Analytics artifacts list shows each optimized page with its status and citability score.

    Once you're satisfied, flip the constant to `"default"` and redeploy to start serving the variant. The `middleware.ts` constant only accepts `"shadow"` or `"default"`; richer serve modes such as canary rollouts are configured from the Bluesky platform (`off` / `shadow` / `canary:<pct>` / `default`).
  </Accordion>

  <Accordion title="Which AI agents does Bluesky detect?">
    Bluesky maintains a **botset** — a list of known AI agents with their user-agent tokens, published IP CIDR ranges, and a purpose classification. The middleware fetches it from the control plane and caches it on the edge for up to one hour.

    Tracked agents include:

    * **OpenAI**: `ChatGPT-User` (`USER_TRIGGERED`), `OAI-SearchBot` (`RETRIEVAL`), `GPTBot` (`TRAINING`)
    * **Anthropic**: `Claude-User` (`USER_TRIGGERED`), `Claude-SearchBot` (`RETRIEVAL`), `ClaudeBot` (`TRAINING`)
    * **Perplexity**: `Perplexity-User` (`USER_TRIGGERED`), `PerplexityBot` (`RETRIEVAL`)
    * **Mistral**: `MistralAI-User` (`USER_TRIGGERED`)
    * **Classic search** (firewall-protected, never served): `Googlebot`, `Bingbot`, `Applebot`

    Detection matches the request's user-agent token against the botset, then verifies the source IP against the vendor's published CIDR ranges. A match on user-agent alone yields `UA_ONLY`, which is never served the variant; IP confirmation yields `IP_VERIFIED`. The core also defines a higher `SIGNED` tier backed by Web Bot Auth (RFC 9421 HTTP Message Signatures, Ed25519); the shipped drop-in verifies by IP range.

    Bluesky maintains the botset centrally, so you don't need to track vendor crawler tokens or IP ranges yourself.
  </Accordion>

  <Accordion title="What's the difference between USER_TRIGGERED and RETRIEVAL purpose classes?">
    Every bot in the botset carries a **purpose class** describing why it's crawling:

    * **`USER_TRIGGERED`** — A human is actively waiting. When a ChatGPT user asks a question with browsing enabled, `ChatGPT-User` fetches your page in real time to inform the answer.
    * **`RETRIEVAL`** — The crawler is building or refreshing an index for future queries. `OAI-SearchBot` and `PerplexityBot` fall here.

    Both classes are enabled for variant serving by default. Other classes are **not** served:

    * **`TRAINING`** crawlers (e.g. `GPTBot`, `ClaudeBot`, `CCBot`) pass through to your normal page.
    * **`SEARCH_INDEX`** bots (`Googlebot` / `Bingbot` / `Applebot`) always pass through via the cloaking firewall.

    You control which purposes are eligible per site (`SEARCH_INDEX` can never be enabled).
  </Accordion>

  <Accordion title="Does Bluesky slow down my site?">
    No — for human visitors there is no perceptible latency. The overwhelming majority of your traffic is human, and if no bot user-agent is matched the middleware calls `NextResponse.next()` and steps aside immediately.

    For a verified AI crawler request the middleware does a little extra work: it fetches the pre-generated artifact from the control plane. This is completely separate from any human session. The botset is cached on the edge for up to one hour, so that lookup does not hit the control plane on every request.

    <Note>
      Bluesky never puts an LLM call on the request path. Artifacts are generated offline — pure extraction-and-restructure of your existing page — and cached, so serving one is just a fetch, never a model round-trip.
    </Note>
  </Accordion>

  <Accordion title="How do I update an optimized artifact after editing a page?">
    Artifacts are built from a snapshot of your page content, so editing your page does not automatically rebuild them.

    To refresh one:

    1. Open **Agent Analytics** in the Bluesky app.
    2. Find the page you've edited.
    3. Use the **Regenerate** action, which flags the artifact stale so the engine rebuilds it from your page's current content.

    Because the drop-in middleware fetches artifacts per request from the control plane (it keeps no local edge cache), the rebuilt version is served to the next qualifying crawler with no redeploy on your side. While a page is queued for regeneration its status shows as `stale` and the edge passes crawlers through to your normal page until the engine rebuilds it back to `fresh` — you can watch that status flip (and the updated citability score) in the artifacts list. See the [Agent Analytics guide](/guides/agent-analytics) for the served → cited loop.
  </Accordion>
</AccordionGroup>