[eseidel]

Brings docs.shorebird.dev's AI catalog in line with the AI Catalog spec.

• host.identifier removed from /.well-known/ai-catalog.json. It was did:web:shorebird.dev, but https://shorebird.dev/.well-known/did.json returns 404, so the DID resolves to nothing. identifier is optional.
• The catalog is linked with rel="ai-catalog" (type="application/ai-catalog+json") in both the Link response header (functions/_middleware.ts) and the <link> in Head.astro, as the spec's Link Relation Discovery section defines (the spec requests IANA registration of ai-catalog; it is not in the IANA registry yet). It used service-desc, which RFC 8631 reserves for API descriptions; the OpenAPI document keeps that relation. isitagentready.com's ARD check looks for rel="ai-catalog" and currently passes only through the well-known fallback.
• specVersion is "1.0" (the spec requires Major.Minor), and _headers serves the catalog as application/ai-catalog+json.

Screenshots

No visible change. Only response headers, a <head> link and a JSON file change.

Landing

As soon as approved.

🤖 Generated with Claude Code

[eseidel]

Adversarial review (by a separate agent that didn't write the change)

1. Medium: wrong link relation. The AI Catalog spec (Agent-Card/ai-catalog, "Link Relation Discovery") registers rel="ai-catalog" with type application/ai-catalog+json. isitagentready.com's ARD check looks for <link rel="ai-catalog"> and logs "No catalog links found" on docs.shorebird.dev today. That check passes only through the well-known fallback. Switching from service-desc to describedby swaps one relation the spec doesn't use for another. Dropping service-desc is right (RFC 8631 reserves it for API descriptions). Fix: use rel="ai-catalog". website#426 copies the same describedby.
2. Low: host identity. Host Info defines displayName (required) plus optional identifier, documentationUrl and logoUrl. domain and description aren't spec members, so "domain still names the host" depends on a field conforming consumers ignore. identifier may be a plain domain name ("shorebird.dev"), which needs no did.json. Removing the dead did:web is correct either way, since did.json returns 404 on both hosts.
3. Low (already on main): format conformance. specVersion is "0.1.0", but the spec requires Major.Minor and its examples use "1.0". _headers serves the catalog as application/json rather than application/ai-catalog+json.

Checked and fine: nothing else in the repo references the old relation. api-catalog's service-desc correctly points at the OpenAPI document, the robots.txt line is only a comment, and no tests or scripts check these headers.

[eseidel]

Responses to the adversarial review:

1. Fixed in 1b0059e. The Link header and the <link> both use rel="ai-catalog" with type="application/ai-catalog+json". I checked this against the spec's Link Relation Discovery section and its IANA registration. I dropped the describedby cspell word, since nothing uses it now. website#426 has the same issue, and I'm tracking that on the website side.
2. Answered, no change. The point of this PR was to remove the unverifiable did:web identifier, and identifier is optional. A bare domain wouldn't fix the real gap the review found anyway: domain and description aren't spec members, while displayName (the one required member) is present. If the scanner ever wants identifier, "shorebird.dev" is a one-line follow-up. domain: shorebird.dev names the operator (Shorebird), not the serving host, so it's deliberately the same on both sites.
3. Fixed in 1b0059e: specVersion is now "1.0", and _headers serves the catalog as application/ai-catalog+json; charset=utf-8. The middleware skips /.well-known/*, so _headers is the only thing setting that Content-Type.

[AbhishekDoshi26]

2 findings, both nits.

1. public/_headers:35: the catalog is served as application/ai-catalog+json; charset=utf-8, but the spec's media type registration lists "Optional parameters: N/A" (UTF-8 JSON per RFC 8259, which defines no charset parameter). Serve exactly Content-Type: application/ai-catalog+json, as the description says.

2. PR description: "as the spec's Link Relation Discovery section registers" overstates it. That section defines the relation; registration is a separate IANA request, and ai-catalog isn't in the IANA link-relations registry yet (checked link-relations-1.csv). Suggest "as the spec's Link Relation Discovery section defines (the spec requests IANA registration of ai-catalog; it is not in the IANA registry yet)".

Checked and correct: against Agent-Card/ai-catalog specification/ai-catalog.md at 9316f00, the relation is ai-catalog, specVersion "1.0" is Major.Minor, HostInfo's identifier is optional, every entry has identifier, type and url. https://shorebird.dev/.well-known/did.json is 404. The middleware's Link array is still well-formed and the OpenAPI document keeps service-desc. A clean npm run build puts the new <link rel="ai-catalog"> on every non-redirect page with no service-desc left in HTML, and no stale references remain in the repo.

I'll push the header fix and update the description.

[AbhishekDoshi26]

No findings.

Round 2, full diff at b1075d1 plus the description. Both round-1 nits are fixed: _headers serves exactly application/ai-catalog+json (the spec lists no parameters), and the description says the Link Relation Discovery section defines ai-catalog and that IANA hasn't registered it yet (no row in link-relations-1.csv). Re-checked against specification/ai-catalog.md at 9316f00: relation, media type, specVersion "1.0", optional HostInfo identifier, required entry members. shorebird.dev/.well-known/did.json is still 404. A clean build puts the new <link> on all 74 non-redirect pages with no service-desc left in HTML; the middleware Link list is valid RFC 8288 and the OpenAPI document keeps service-desc. No stale references remain.