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

# Optimized Page Artifacts

> How Bluesky generates AEO-optimized page artifacts, what they contain, and how they are served to verified AI agents.

When an AI answer engine crawls your site, the markup-heavy HTML it receives is often harder to interpret than a clean, structured representation of the same content. Bluesky solves this by generating an **optimized artifact** for each of your pages — a machine-readable version of your content that answer engines can parse and cite. This guide explains what those artifacts are, how they're built, and how they're served.

## What an optimized artifact is

An optimized artifact is a purpose-built representation of a single page, produced by pure extraction and restructuring of your existing page. It is composed of three parts:

<CardGroup cols={3}>
  <Card title="Answer-first markdown" icon="file-lines">
    Your page's content reformatted so the most direct answer appears near the top — the page title as an H1, a lead answer block, then each of your headings followed by its nearest paragraph.
  </Card>

  <Card title="JSON-LD structured data" icon="code">
    Deterministic `Article` schema.org markup, plus a `FAQPage` block when your page's own headings are phrased as questions answered by the following paragraph.
  </Card>

  <Card title="Clean-HTML mirror" icon="file-code">
    A stripped-down HTML rendering of the same extracted content, stored alongside the markdown.
  </Card>
</CardGroup>

The drop-in edge middleware returns the **markdown** representation to a verified agent. The JSON-LD and clean-HTML mirror are generated and stored as part of the artifact.

<Warning>
  The artifact carries the **same substance as your source page** — nothing more. Bluesky's generator does pure extraction and restructure with **no LLM generation on the content**, and enforces a strict parity guardrail (see below) that refuses to publish an artifact containing anything the source page did not say.
</Warning>

## How artifacts are generated

Bluesky generates artifacts **offline**, in the background, from your existing published pages. There is no large language model on the request path — when a verified AI agent arrives at your site and the edge middleware fetches an artifact, it is retrieving a pre-built document from Bluesky's control plane, not triggering a live generation step.

<Note>
  Because generation is offline and pre-cached, artifact delivery adds no model latency to the request path.
</Note>

<Steps>
  <Step title="Your published page is read">
    Bluesky fetches the live URL. Scripts, styles, navigation, headers, footers, asides, and forms are dropped so only the semantic content remains.
  </Step>

  <Step title="Content is extracted and restructured">
    The page title, meta description, section headings, and substantial paragraphs are pulled out and composed into answer-first markdown, an `Article`/`FAQPage` JSON-LD block, and a clean-HTML mirror — all sourced from the page itself.
  </Step>

  <Step title="Parity is enforced">
    A grounding guardrail compares the generated tokens against the source. If the markdown introduces any content word the source didn't contain, the artifact is rejected and never served.
  </Step>

  <Step title="Artifact is stored and cached">
    A passing artifact is upserted as an `EdgeArtifact` row and pushed into the edge KV cache, assigned a citability score, and becomes available to serve.
  </Step>
</Steps>

## Strict parity: no fabrication

The single most important property of an artifact is that it never asserts anything your page didn't. Two gates enforce this before an artifact is ever marked servable:

<AccordionGroup>
  <Accordion title="Grounding guardrail">
    The generator tokenizes both the source text (title, description, headings, paragraphs, and full main text) and the generated markdown, then checks for any content token present in the artifact but absent from the source. For pure extraction this set is empty. A non-empty result marks the artifact as an error — it is not stored as fresh and is not served. This one check defends against both hallucination and cloaking.
  </Accordion>

  <Accordion title="Minimum content">
    If the restructured markdown has too few content tokens, the page has no usable content and the artifact is marked as an error rather than served. Thin pages simply pass through to the human page.
  </Accordion>
</AccordionGroup>

<Note>
  Only artifacts with `status: fresh` are ever served. Anything marked as an error or stale results in a transparent passthrough to your normal page.
</Note>

## Citability score

Each fresh artifact is assigned a **citability score** between 0 and 1 (shown as a percentage in Agent Analytics). It is a heuristic signal of how citable the artifact is, computed from the extracted structure — not a live model call. The factors it rewards:

| Factor                                        | Contribution |
| --------------------------------------------- | ------------ |
| Page has a title                              | +0.20        |
| Meta description present (answer-first lead)  | +0.15        |
| Section headings present (chunkable sections) | +0.20        |
| Last-modified date present (freshness signal) | +0.10        |
| `FAQPage` JSON-LD generated                   | +0.15        |
| Sufficient content density in the markdown    | +0.20        |

The score is capped at 1.0. It is an extension of the GEO score, surfaced so you can gauge an artifact's strength at a glance.

## Which URLs get served the artifact

The edge middleware only serves an optimized artifact for URLs that have a **fresh artifact on file**. If a verified AI agent requests a URL that hasn't been generated (or whose artifact is stale/error), the artifact endpoint returns a 404 and the middleware passes the request through transparently — the agent receives your normal page, no error is returned, and the visitor experience is unaffected.

<Note>
  Passthrough is silent and safe. A missing artifact never degrades the experience for any visitor — human or agent.
</Note>

## How the middleware fetches an artifact

When a verified answer-engine request is eligible and the serve mode is `default`, the middleware computes a **SHA-256 hash of the full request URL** and uses it to look up the artifact from Bluesky's edge API:

```
GET /api/v1/edge/artifact?u=<sha256-of-full-url>
```

The request is authenticated with your edge token (`Authorization: Bearer <edgeToken>`). If the API returns a fresh artifact, the middleware responds with the markdown body and these headers:

| Header          | Value                          |
| --------------- | ------------------------------ |
| `content-type`  | `text/markdown; charset=utf-8` |
| `x-aen-served`  | `variant`                      |
| `cache-control` | `no-store`                     |

<Note>
  Serving only happens in `default` mode for verified, eligible agents. In `shadow` mode the middleware logs what it would serve but always returns the human page. See [Serve modes](/guides/serve-modes) for the full vocabulary (`off` / `shadow` / `canary:<pct>` / `default`).
</Note>

## Regenerating an artifact

After you update a page's content, regenerate its artifact so the served markdown and its citability score reflect your latest content.

<Steps>
  <Step title="Open Agent Analytics">
    In the Bluesky app, go to **Agent Analytics** and select the domain you want to inspect.
  </Step>

  <Step title="Find the page">
    Each generated page is listed with its URL, freshness status, and citability score.
  </Step>

  <Step title="Regenerate">
    Use the **Regenerate** action next to the page to queue a fresh artifact. This flags the current artifact for regeneration; on its next generation run Bluesky re-fetches the page, re-runs the parity check, and updates the stored artifact.
  </Step>
</Steps>

<Tip>
  A regenerate re-runs the full pipeline, including the strict-parity gate — if the updated page no longer yields groundable content, the artifact is marked as an error and passthrough resumes automatically.
</Tip>

## Related

<CardGroup cols={2}>
  <Card title="Serve modes" icon="toggle-on" href="/guides/serve-modes">
    off / shadow / canary / default — how you control when the variant is served.
  </Card>

  <Card title="Agent Analytics" icon="chart-line" href="/guides/agent-analytics">
    See what was served versus cited, broken down by purpose and trust.
  </Card>
</CardGroup>