name	check-discovery-consistency
description	Audit the agent-discovery surface for internal consistency — .well-known documents, agent-skills sha256 hashes, WebMCP tools, and the discovery links in _document.tsx / _headers / vercel.json. Use after editing any discovery metadata, or when asked to validate the .well-known surface.

Check Discovery Consistency

This site publishes a rich agent-discovery surface. The files must stay internally consistent — AGENTS.md → Discovery Metadata treats this as a recurring obligation. This skill is a read-and-verify audit; it reports drift and proposes fixes, it does not blindly rewrite.

What to verify

agent-skills integrity (public/.well-known/agent-skills/):
- For every *.md, compute shasum -a 256 <file> and compare to the matching skills[].sha256 in index.json (matched by the entry's url basename).
- Every index.json entry must point to a file that exists; every *.md should have an entry.
Cross-document coherence (public/.well-known/):
- api-catalog, agent-card.json, mcp.json, mcp/server-card.json, ai-plugin.json, OAuth/OIDC metadata (openid-configuration, oauth-authorization-server, oauth-protected-resource), and jwks.json should reference consistent URLs, names, and endpoints (all under the homepage origin in package.json).
Discovery links agree across surfaces:
- The <link> discovery tags in src/pages/_document.tsx (the surface honored on GitHub Pages) must match the Link header entries in public/_headers and vercel.json. Note: GitHub Pages ignores _headers/vercel.json, so _document.tsx is authoritative for production.
WebMCP tools:
- Tools registered in src/shared/utils/webmcpTools.ts / src/pages/_app.tsx should match what webmcp-tools.md and mcp.json advertise.

How to work

Use shasum -a 256 and jq to compare hashes and JSON fields; read the .md and .tsx sources directly.
Report findings as a table: file, expected, actual, fix. Recompute and show the correct sha256 values for any drifted agent-skills entry.
After applying fixes, re-run the hash check to confirm convergence.

Check Discovery Consistency

What to verify

agent-skills integrity (public/.well-known/agent-skills/):

For every *.md, compute shasum -a 256 <file> and compare to the matching skills[].sha256 in index.json (matched by the entry's url basename).
Every index.json entry must point to a file that exists; every *.md should have an entry.

Cross-document coherence (public/.well-known/):

api-catalog, agent-card.json, mcp.json, mcp/server-card.json, ai-plugin.json, OAuth/OIDC metadata (openid-configuration, oauth-authorization-server, oauth-protected-resource), and jwks.json should reference consistent URLs, names, and endpoints (all under the homepage origin in package.json).

Discovery links agree across surfaces:

The <link> discovery tags in src/pages/_document.tsx (the surface honored on GitHub Pages) must match the Link header entries in public/_headers and vercel.json. Note: GitHub Pages ignores _headers/vercel.json, so _document.tsx is authoritative for production.

WebMCP tools:

Tools registered in src/shared/utils/webmcpTools.ts / src/pages/_app.tsx should match what webmcp-tools.md and mcp.json advertise.

How to work

Use shasum -a 256 and jq to compare hashes and JSON fields; read the .md and .tsx sources directly.

Report findings as a table: file, expected, actual, fix. Recompute and show the correct sha256 values for any drifted agent-skills entry.

After applying fixes, re-run the hash check to confirm convergence.

check-discovery-consistency