# Agent discovery

> For AI agents: a documentation index is available at https://makespdf.com/llms.txt — every docs page also has a markdown twin (append .md to the page URL), including this one: https://makespdf.com/docs/discovery.md

Every machine-readable surface in one place, so an agent runtime, a crawler, or
an auditor can find us without a human linking us in. Start at
`https://makespdf.com/llms.txt` for the narrative guide, or at
`https://makespdf.com/.well-known/agents.json` for the link graph.

## Skill file

The canonical template-authoring skill lives at exactly one URL:
[https://makespdf.com/skills/pdf-template-author.md](https://makespdf.com/skills/pdf-template-author.md).
The conventional short path `https://makespdf.com/skill.md` is a 302 redirect to it —
never a second copy — so the two can never drift apart.

```bash
curl -sI https://makespdf.com/skill.md
# → 302 Location: /skills/pdf-template-author.md

curl -s https://makespdf.com/skills/pdf-template-author.md | head -c 200
```

Five companions live beside it (`/skills/pdf-auth.md`, `/skills/pdf-api.md`,
`/skills/pdf-recipes.md`, `/skills/pdf-fonts.md`,
`/skills/pdf-integration.md`). Fetch them on demand; the main skill file says
when each one applies.

## Manifests

### /.well-known/agents.json

One JSON link graph: skill (+ pointer), OpenAPI, MCP, x402 paid endpoints,
llms.txt, and the trust file. No community standard has won this slot yet, so
the shape is small and living — treat the URLs as the contract and extra fields
as advisory.

```bash
curl -s https://makespdf.com/.well-known/agents.json | jq '{skill, openapi, mcp, x402}'
```

### OpenAPI

OpenAPI 3.1 with x402 payment annotations at
[https://makespdf.com/openapi.json](https://makespdf.com/openapi.json), aliased at
`https://makespdf.com/api/v1/openapi.json` for runtimes that probe the versioned path. The
two always-paid endpoints (`/api/v1/markdown` at $0.01, `/api/v1/render` at
$0.02) carry `x-payment-info` plus a `402` response; free endpoints carry
`security: []` so scanners do not probe them as paid.

### MCP

Streamable-HTTP MCP server at `https://makespdf.com/api/v1/mcp` — schema-validated tools
for the authoring loop, plus the skill file as a fetchable resource. Setup per
client: https://makespdf.com/docs/mcp.

### x402

Paid-endpoint manifest at `https://makespdf.com/.well-known/x402` (x402scan fan-out
shape). In-protocol discovery is the `bazaar` extension on each 402 challenge;
the wire format is documented in [https://makespdf.com/llms.txt](https://makespdf.com/llms.txt) under
§Pay-per-call.

## Trust

### /.well-known/security.txt

RFC 9116 contact file: `Contact` plus a `Expires` about a year out (currently
2027-09-11). Also served at `https://makespdf.com/security.txt`. The contact matches the
one in [https://makespdf.com/legal/terms](https://makespdf.com/legal/terms).

```bash
curl -s https://makespdf.com/.well-known/security.txt
```

> **Ops:** the Expires date is a yearly bump — see `SECURITY_TXT_EXPIRES` in
> `apps/web/src/server/static-text-routes.ts`. Roll it forward before it lapses
> or audits start flagging the file as stale.

### robots.txt

Explicit `Allow: /` stanzas for GPTBot, ClaudeBot, PerplexityBot,
Google-Extended, OAI-SearchBot, Applebot-Extended, and CCBot sit above the
wildcard — redundant today, deliberate: they survive a future wildcard
tightening and audit tools score them. POST-only `/api/` and auth-gated
surfaces stay `Disallow`ed.

## What we deliberately do not ship

`/.well-known/ai-plugin.json` — dropped. OpenAI's plugin-manifest convention is
deprecated; we ship the living conventions (Apps-SDK / A2A agent-card shape)
inside `https://makespdf.com/.well-known/agents.json` instead and will track whatever
replaces them there.

[https://makespdf.com/llms.txt](https://makespdf.com/llms.txt) stays the maintained human-readable
manifest — these files extend it, they do not replace it.

## What's next

- [https://makespdf.com/llms.txt](https://makespdf.com/llms.txt) — the narrative guide for agents, with auth and the
  three render paths.
- [Bring your own AI](https://makespdf.com/docs/ai-setup) — skill install, device flow, and the preview API.
- [API Reference](https://makespdf.com/docs/api) — the REST endpoints each manifest points at.