# Agent discovery

CoreX publishes a few machine-readable files for the surfaces it actually
serves. A file is not published for a protocol CoreX does not implement.

## What is public

| URL | What it is |
| --- | --- |
| `/robots.txt` | Crawl rules. `Content-Signal` sits in the `User-agent: *` group. |
| `/llms.txt` | Short index of the public site, the docs, the free tools, the REST API, and the MCP server. |
| `/llms-full.txt` | That index, then the text of the key public pages and the live docs. Both files are cached. |
| `/sitemap.xml` | Sitemap index. |
| `/openapi.json` | OpenAPI 3.1 for `GET` and `POST /api/v1`. |
| `/.well-known/api-catalog` | RFC 9727 linkset (`application/linkset+json`) pointing at `GET /api/v1` (a short JSON index), `/openapi.json`, and this API's docs. |
| `/.well-known/mcp.json` | MCP server card for `POST /mcp`. The same card is at `/.well-known/mcp/server-card.json`. |
| `/auth.md` | How an agent sends an API key, and the actions the REST API and MCP server expose. |
| `/agents.json` | The same note as JSON, generated from the OpenAPI document and the MCP tool list. |

There is no public blog. `/blog` is not a page.

A public marketing, docs, free-tool, or leaderboard URL accepts
`Accept: text/markdown` and also answers at `<url>.md` (the home page is
`/index.md`). The response is `text/markdown; charset=utf-8` with
`Vary: Accept`. The header does not redirect and does not apply to `/app`.
Docs already had `/docs/{page}.md`.

`Access-Control-Allow-Origin: *` is on those discovery files, on
`GET /api/v1` (the index only), and on markdown responses. It is not sent
with credentials, and it is not added to `/api/v1/*` (the keyed REST API),
to a 404 under `/.well-known/`, or to session and panel routes. The widget,
ingestion, and embed endpoints keep their own wildcard because a merchant
page calls them, except a path under those prefixes that matches no
route: that answer is JSON `not_found` and carries no CORS header.
`/openapi.json` is a file in `public/`, so the production web server sets
`Content-Type: application/vnd.oai.openapi+json`, the CORS header, and a
204 for `OPTIONS` before PHP sees the request. The same layer adds
`Strict-Transport-Security`, `X-Content-Type-Options`, `X-Frame-Options`
and `Referrer-Policy` only when the path is a real file, and it does not
gzip woff2, PNG, JPEG, GIF, WebP, AVIF, ICO or a file that is already
compressed. PHP responses stay as the app set them, so a booking or
feedback page can still be framed. `GET /free-tools/leaderboard` is an
edge-cached read.

Markdown for pricing, a category leaderboard, and State of the App Store
includes the page's facts (what the beta includes, the top of the ranking,
the month's launch figures), not only the title and a link list. The HTML
render still records Vite chunks, and the preload middleware writes them
into a `Link` header before the body is replaced. The markdown middleware
is the outermost one, so it drops `rel=preload` and `rel=modulepreload`
after that write. The same drop covers `/llms.txt` and `/llms-full.txt`.
A cache that stored the header would answer the next load with 103 Early Hints.

Docs are English. `/fr/docs` keeps `lang="en"`, does not advertise a French
`hreflang`, stays `noindex`, and sets `rel="canonical"` to the English
document. French pages link to `/docs`. On a French page that does have a
translation, JSON-LD `url`, `@id` and breadcrumb `item` use the same `/fr`
URL as the canonical. `/privacy.md` and `/terms.md` are the legal pages'
own copy, and a docs `Accept: text/markdown` response is the same bytes as
`/docs/{page}.md`. `OPTIONS /api/v1` and `OPTIONS /api/v1/*` answer 204
when the path exists and the `not_found` envelope when it does not.
`robots.txt` also disallows `/fr/free-tools/*/run`.

## What is not public

The API and the MCP server use an API key (`Authorization: Bearer` or
`X-CoreX-Token`). CoreX does not run an OAuth authorization server, so it
does not publish protected-resource or authorization-server metadata.

There is no Agent-to-Agent endpoint, so there is no
`/.well-known/agent-card.json`. poppy.json is not a protocol this app
speaks. DNS-AID is a DNS record; nothing in the application can publish it.

`Organization.sameAs` is only the URLs in `ORGANIZATION_SAME_AS`. The
default list is empty, and an empty list omits the key. Do not add a
profile URL that the product does not already link.

## Content-Security-Policy

Responses send `Content-Security-Policy-Report-Only` unless
`CSP_REPORT_ONLY=false`, which switches the same policy to the enforcing
header. `CSP_ENABLED=false` removes it. `X-Content-Type-Options: nosniff`
and `Referrer-Policy: strict-origin-when-cross-origin` are always set.

The policy allows the Vite build on this origin, inline JSON-LD and Inertia
data, PostHog, Cloudflare Web Analytics, Mailchimp, Google Analytics hosts
(nothing in the app injects a tag today), Shopify CDN images, the
self-hosted fonts, and the same-origin live-chat widget and embeds.
`CSP_EXTRA_SCRIPT_SRC` and the other `CSP_EXTRA_*` variables append hosts.
The report-only policy always names `POST /csp-report` (`report-uri` and
`report-to`). That endpoint rate-limits, logs the directive and the URL
path, and drops query strings. `CSP_REPORT_URI` (or `SENTRY_CSP_REPORT_URI`)
adds a second https collector. Leave the policy report-only until those
reports show it is not blocking a real asset.

## Deploy and rollback

No migration. `llms.txt` and `llms-full.txt` use new cache keys, so a deploy
does not need a cache flush. Rollback is a revert of this release. If an
enforcing content-security policy blanks a page, set `CSP_REPORT_ONLY=true`
(the default) and redeploy the config. Clearing `ROBOTS_CONTENT_SIGNAL`
removes the Content-Signal line. Clearing `ORGANIZATION_SAME_AS` removes
`sameAs`.
