# Discovery route matrix This file is the source of truth for llm-cli-gateway.dev machine-readable discovery routes. Unknown paths must return 404. If a production probe sees the homepage for a machine route, diagnose the active Cloudflare Pages fallback first: `site/_redirects`, `site/_routes.json`, generated Pages config, Pages SPA/catch-all settings, and deployment logs. The current checkout has no tracked `_redirects` or `_routes.json`; any live homepage fallback for missing JSON paths is therefore expected to come from the Pages project configuration or from a deploy artifact outside these files. | Path | Purpose | Canonical source | Alias type | Validation mode | Content-Type | Cache-Control | Sitemap | Generator/check | | ------------------------------------------------- | -------------------------------- | ---------------------------------------------------------- | --------------------------------------- | --------------------- | ------------------------------------------------- | -------------------------------------- | ------- | ------------------------------------------------------ | | `/.well-known/agent.json` | Agent metadata | same file | canonical | no-follow | `application/json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/agent.json` | Compatibility agent metadata | `/.well-known/agent.json` | generated-copy | generated-equivalence | `application/json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:generate -- --check` | | `/.well-known/mcp/server-card.json` | MCP server card | authored card metadata plus runtime MCP `tools/list` names | canonical metadata, generated tool list | generated-tools | `application/json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:generate -- --check` | | `/.well-known/mcp.json` | Compatibility MCP descriptor | `/.well-known/mcp/server-card.json` | generated-copy | generated-equivalence | `application/json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:generate -- --check` | | `/.well-known/api-catalog` | RFC 9727-style linkset catalog | generated catalog source | canonical | no-follow | `application/linkset+json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:generate -- --check` | | `/.well-known/ai-catalog.json` | Compatibility AI catalog | `/.well-known/api-catalog` generated source | generated-copy | generated-equivalence | `application/json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:generate -- --check` | | `/.well-known/integrations.json` | Integration declaration | same file | canonical | no-follow | `application/json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/llms.txt` | Compact retrieval router | same file | canonical | no-follow | `text/plain; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/docs` | Developer documentation entry | same file | canonical | no-follow | `text/html; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/api` | HTTP MCP API reference | same file | canonical | no-follow | `text/html; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/developers` | Developer portal | same file | canonical | no-follow | `text/html; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/about` | Project trust page | same file | canonical | no-follow | `text/html; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/contact` | Support and issue routing | same file | canonical | no-follow | `text/html; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/privacy` | Self-hosted privacy note | same file | canonical | no-follow | `text/html; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/openapi.json` | OpenAPI HTTP MCP description | authored spec plus version synchronizer | canonical | version-and-route | `application/vnd.oai.openapi+json; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:version:check` + `npm run site:validate` | | `/install.md` | Short install spec | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/agents.md` | Full agent guide | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/tools.md` | Runtime-derived tool index | runtime MCP `tools/list` fixture | generated-copy | generated-equivalence | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:generate -- --check` | | `/guides/coding-agent-gateway-technical-guide.md` | Coding-agent orchestration guide | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/guides/personal-agent-config-kit.md` | Single-developer Kit guide | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/workflows/cross-model-review.md` | Deterministic workflow demo | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/DISCOVERY.md` | Discovery route matrix | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/sitemap.md` | Human-readable sitemap | same file | canonical | no-follow | `text/markdown; charset=utf-8` | `public, max-age=300, must-revalidate` | yes | `npm run site:validate` | | `/sitemap.xml` | Search-engine sitemap | same file | canonical | no-follow | `application/xml; charset=utf-8` | `public, max-age=300, must-revalidate` | no | `npm run site:validate` | Catalogs and docs may link only to same-deploy existing files or stable external URLs. `scripts/validate-site-discovery.mjs` resolves catalog and markdown links and fails on missing internal targets or homepage HTML fallback. The generated API catalog intentionally includes `http://127.0.0.1:3333/mcp` as an `item`: it documents the gateway's default local HTTP MCP listener after a user starts `llm-cli-gateway --transport=http`. It is not a route on `llm-cli-gateway.dev`, not a hosted public endpoint, and is not link-followed by site discovery validation.