Skip to content

Add agent discovery link catalog#58

Merged
AnnatarHe merged 1 commit intomasterfrom
codex/add-link-headers-for-agents
Apr 19, 2026
Merged

Add agent discovery link catalog#58
AnnatarHe merged 1 commit intomasterfrom
codex/add-link-headers-for-agents

Conversation

@AnnatarHe
Copy link
Copy Markdown
Member

@AnnatarHe AnnatarHe commented Apr 19, 2026

Summary

  • Add a static RFC 9727 Linkset catalog at /.well-known/api-catalog
  • Advertise the RSS feed as a machine-readable entrypoint for agent discovery
  • Include /posts as the service documentation target

Testing

  • pnpm astro check
  • pnpm build

@AnnatarHe AnnatarHe temporarily deployed to codex/add-link-headers-for-agents - asynctalk-website PR #58 April 19, 2026 02:51 — with Render Destroyed
@AnnatarHe AnnatarHe merged commit f983c98 into master Apr 19, 2026
1 check passed
@AnnatarHe AnnatarHe deleted the codex/add-link-headers-for-agents branch April 19, 2026 02:51
@claude
Copy link
Copy Markdown

claude Bot commented Apr 19, 2026

Code Review — Add agent discovery link catalog

Overview

This PR adds a static RFC 9727 Linkset document at /.well-known/api-catalog to advertise the RSS feed as a machine-readable entrypoint for agent/AI discovery. Small change (19 lines), self-contained.

What's good

  • Correct file placement in public/.well-known/ so Astro copies it verbatim to build output.
  • Valid JSON-formatted Linkset structure matching the RFC 9727 spec.
  • Domain value (https://AsyncTalk.com) is consistent with the site field in astro.config.mjs.
  • service-doc pointing at /posts is a reasonable human-readable entrypoint.

Potential issues

1. Missing Content-Type: application/linkset+json header (medium)

RFC 9727 §3.1 requires the Linkset document to be served with Content-Type: application/linkset+json. Because this file has no extension, most CDNs/hosts will fall back to application/octet-stream or text/plain, which means conformant agents that check the content type will reject it.

There is no netlify.toml, vercel.json, or public/_headers file in the repo, so there is currently no mechanism to set this header.

Suggested fix — add a public/_headers file (works on Netlify/Cloudflare Pages) or equivalent for your host:

/.well-known/api-catalog
  Content-Type: application/linkset+json

2. anchor URL points to the catalog itself — consider the API origin (minor)

RFC 9727 §3 recommends the anchor identify the API origin (https://AsyncTalk.com) rather than the catalog URL itself. Using the catalog URL as its own anchor is valid but may confuse some agent implementations.

// Current
"anchor": "https://AsyncTalk.com/.well-known/api-catalog"

// More conventional
"anchor": "https://AsyncTalk.com"

Minor suggestions

  • The type for service-doc is text/html, which is correct for /posts. If a machine-readable API description (OpenAPI, etc.) ever exists, that would be a better target.
  • Consider whether https://AsyncTalk.com/rss.xml should also be advertised via an <link> tag in the site <head> for browser feed auto-discovery — not blocking, just complementary.

Summary

The Linkset JSON is well-formed and the change achieves its goal. The main actionable follow-up is configuring the Content-Type header — without it, RFC-conformant discovery clients may not recognize the file, defeating the purpose of the addition.

chatgpt-codex-connector[bot]
chatgpt-codex-connector Bot reviewed Apr 19, 2026
View reviewed changes
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d3d78a0434

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread public/.well-known/api-catalog
@@ -0,0 +1,19 @@
{
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot Apr 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Serve api-catalog with application/linkset+json

RFC 9727 requires /.well-known/api-catalog to support the application/linkset+json media type, but this commit adds an extensionless static file with no accompanying header configuration in the repo (I checked for common _headers/hosting header config files and found none). On typical static hosting, this path is served as a generic type (often application/octet-stream or text/plain), which can break clients that request Accept: application/linkset+json for catalog discovery.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chatgpt-codex-connector chatgpt-codex-connector[bot] chatgpt-codex-connector[bot] left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@AnnatarHe