How Publishers Make Blue Jetty Discoverable to AI

Your app map gives an AI assistant useful context: what the app does, which experiences fit a request, and which publisher-approved link should take the user there. Discovery is how the assistant reaches that context from your website or from Blue Jetty.

No single discovery mechanism is assumed to work across all AI retrieval systems. Blue Jetty uses redundant, consistent signals so different clients can reach the same authoritative app context through the surfaces they support.

A tool may follow ordinary page links, inspect response headers, read structured metadata, or retrieve a known URL directly. The sections below explain how each path exposes that context and which changes complete Blue Jetty's setup.

Publishers choose the changes to their websites. Blue Jetty separates the requirements for a complete setup from strongly recommended delivery options and optional extra coverage. Your coding agent receives app-specific instructions and reports what we actually detected.

HTTP Link headers: discovery in the response

An HTTP Link header advertises the app context before a client needs to interpret the page. Your web server or CDN can add it independently of the application frontend. HTTP link serialization is defined by RFC 8288.

For example, a publisher using first-party delivery could expose:

Link: <https://publisher.example/.well-known/bluejetty/apps/app_example/packet.md>; rel="alternate"; type="text/markdown"

The JSON packet header also carries describedby, and the generated header separately advertises llms.txt with that relation. The header gives clients a destination and its format without requiring HTML extraction or JavaScript execution. Blue Jetty generates references to both Markdown and JSON, plus the discovery descriptor. Preserve existing Link values such as resource preloads, and check the final homepage GET and HEAD responses after CDN processing.

For Blue Jetty's complete setup, HTTP Link headers are required when executable JavaScript is detected and strongly recommended for all sites. This is Blue Jetty's completion policy: clients may also discover JavaScript pages through the other paths described here. Our check conservatively includes server-rendered pages that hydrate with JavaScript, while distinguishing JSON-LD and other non-executable data blocks.

This removes a rendering dependency from this discovery path. Clients still decide which link relationships they inspect, so combining headers with other references remains useful.

First-party packet delivery: strongly recommended, especially with a CDN

A fixed reverse proxy lets an assistant request your app context on your domain while Blue Jetty serves the underlying record:

publisher.example/.well-known/bluejetty/apps/app_example/packet.md
    → publisher CDN / reverse proxy
    → bluejettyai.com/v1/apps/app_example/packet.md

This is particularly convenient when your team already operates a CDN. The same edge configuration can expose the packet routes and attach the HTTP discovery headers. Use a fixed upstream for the exact app, preserve the origin's response status and media type, and keep credentials out of public discovery files.

First-party delivery is strongly recommended, not required. Direct Blue Jetty packet URLs remain a valid simpler setup. Self-hosting is supported but not recommended unless a specific enterprise requirement justifies publisher-managed synchronization and withdrawal handling. These are delivery alternatives; your team chooses one.

Keep cache behavior aligned with updates and withdrawal. Start with the origin's no-store or revalidation policy. A cached first-party response may not reach Blue Jetty, so origin-side crawler activity cannot represent every CDN-served request.

A predictable discovery descriptor

The small document at /.well-known/bluejetty.json identifies the app, explains the purpose of its context, and links to both packet formats. This is the Blue Jetty convention currently used by onboarding, with an unregistered URI suffix. It stays on the publisher domain even when the packets use direct Blue Jetty hosting.

Blue Jetty is pursuing registration for the distinct suffix bluejetty, corresponding to /.well-known/bluejetty without .json. The registration request is pending review. Neither path should be described as IANA-approved at this stage; follow the generated onboarding URLs for the current implementation.

A client that knows this convention can request the descriptor directly. Its format references tell the client where to retrieve the app context next. The general well-known URI framework is described in RFC 8615; each client still needs support for the particular convention it uses.

Blue Jetty validates that the descriptor refers to the correct app and delivery source. Keep it as a stable pointer, without copying changing packet contents or inventing freshness timestamps. Download the app-specific publisher instructions for the current discovery schema and exact URLs.

llms.txt: explain why the context is worth retrieving

An entry in your root /llms.txt can give an assistant the purpose as well as the destination: app capabilities, relevant experiences, offers and preferred destinations. Advertise both JSON and Markdown so clients can choose the representation they support.

The llms.txt proposal describes an AI-oriented information surface. Blue Jetty uses it as one discovery path alongside HTTP and HTML links. Keep the description factual and specific to the context your app actually publishes. Preserve unrelated entries when adding your app.

HTML head references and readable body links

New installation snippets put two link rel="describedby" references in the initial HTML head: one to the publisher's /llms.txt with type="text/plain", and one directly to the JSON packet with type="application/json". The registered describedby relationship identifies descriptive source material without prescribing its format or establishing its authority. Keep the generated rel="alternate" references for the Markdown format and discovery descriptor; version 4 requires both describedby references and a fresh check for earlier installations. We encourage keeping the generated head references even when HTTP headers provide the same routing information. For a static page without executable JavaScript, the expected head references can satisfy homepage discovery without HTTP headers.

A normal body link gives content-extraction tools another route. We strongly recommend an optional, unbranded “Official App Information for AI Assistants” link to the JSON packet with rel="describedby" in the initial homepage body. Place it in a quiet resource or footer row with normal contrast and keyboard access. No logo or powered-by credit is required. Both head/header describedby references remain mandatory. For publishers who decline a visible resource link, recommend the required head/header references first: they are machine-consumable without rendering page text. Do not use transparent text, background-matched text, hidden links or crawler-specific content. Keep any optional body link readable and keyboard-accessible. Head and HTTP Link references provide nonvisual discovery without concealed page content.

Rendering behavior varies by client. Google's documentation explains its own crawling and JavaScript rendering stages and the benefits of making content available through server-side or pre-rendered HTML. Other retrieval tools should be tested on their own behavior. See Google's JavaScript SEO guidance.

The discovery surfaces Blue Jetty hosts

Public Blue Jetty apps with current publisher/platform authorization and published app data can be reached through public app pages, exact-identity lookup, search, JSON/Markdown packets, entity feeds and sitemaps. The API reference describes these read surfaces; llms.txt helps clients locate them. Public app sitemaps include packet references and update metadata. Private samples stay outside public discovery.

These hosted paths complement the references on your official website. Sitemaps can help search engines discover URLs and meaningful updates; search engines determine when to crawl them. Google's sitemap guidance explains that submission is a hint and that last-modified dates should reflect significant changes.

What is required, and what should we add?

More independent paths are useful when they remain consistent and maintainable. Ask your engineer or coding agent to recommend the complete setup, explain what each change adds, and implement the publisher-approved choices. A missing optional recommendation should be reported clearly without being labeled a failed requirement.

Blue Jetty checks the configured paths and shows their results. Crawler activity shows requests observed at Blue Jetty's origin, giving your team evidence of retrieval separately from setup completion. The onboarding and maintenance guide covers verification, confirmation emails and scheduled monitoring.

Start with the publisher discovery instructions, then give your coding agent the app-specific Markdown available from your account. Your app and existing link provider continue to deliver the experience after the user follows the publisher-approved destination.