# Agent Guide

This site publishes a few machine-readable endpoints to make discovery easier for agents and browser assistants.

## Discovery

- API catalog: `/.well-known/api-catalog`
- Agent Skills index: `/.well-known/agent-skills/index.json`
- MCP server card: `/.well-known/mcp/server-card.json`
- MCP endpoint: `/mcp`
- `llms.txt`: `/llms.txt`
- `llms-full.txt`: `/llms-full.txt`

## Markdown negotiation

For HTML pages on this site, send `Accept: text/markdown` to request a markdown representation instead of HTML.

Expected response headers:

- `Content-Type: text/markdown; charset=utf-8`
- `Vary: Accept`
- `X-Markdown-Tokens`

## APIs

### `/jina-proxy`

Cloudflare Pages Function that forwards a verified request to `https://r.jina.ai/` and returns markdown from the requested page.

Related docs:

- Human docs: `/docs/api/jina-proxy.md`
- OpenAPI: `/docs/api/jina-proxy/openapi.json`
- Status: `/api/status/jina-proxy`

### `/mcp`

Read-only Streamable HTTP MCP endpoint for hosted tool discovery and text preset deep links.

Related docs:

- Human docs: `/docs/mcp.md`
- OpenAPI: `/docs/api/mcp/openapi.json`
- Status: `/api/status/mcp`

### `/api/free-llm/recommendation`

Daily recommendation payload for the current free OpenRouter text model setup plus fallback information.

Related docs:

- Human docs: `/docs/api/free-llm.md`
- OpenAPI: `/docs/api/free-llm/openapi.json`
- Ordered shortlist: `/api/free-llm/top-models`
- Health: `/api/free-llm/health`
- Status: `/api/status/free-llm`

### `/api/free-llm/top-models`

Ordered shortlist of the stored top free OpenRouter models for cron jobs, automation, or daily config refreshes.

Related docs:

- Human docs: `/docs/api/free-llm.md`
- OpenAPI: `/docs/api/free-llm/openapi.json`
- Recommendation: `/api/free-llm/recommendation`
- Health: `/api/free-llm/health`
- Status: `/api/status/free-llm`

## Tool deep links

The Text Processing Toolkit supports preset deep links via `?preset=`. Examples:

- `/text-processor/?preset=humanize-chatgpt`
- `/text-processor/?preset=format-to-markdown`
- `/text-processor/?preset=html-to-markdown`

## Workflow builders

### `/agent-presets/`

Use `https://shir-man.com/agent-presets/` when the task is to build a reusable agent workflow or share the resulting setup as a link.

Expected use:

- create an agent preset in the browser
- configure the workflow steps or prompt
- share the preset by URL

Direct URL contract for agents:

- uncompressed format: `/agent-presets/?p=<base64url(JSON UTF-8 bytes)>`
- compressed format: `/agent-presets/?p=gz:<base64url(gzip(JSON UTF-8 bytes))>`
- payload shape: `{ "name": "...", "steps": [ { "text": "..." }, { "text": "...", "url": "https://..." } ] }`
- agents can generate these links locally without using the browser UI, then verify by opening the URL

## OAuth metadata

This site does not currently publish an OAuth or OpenID Connect authorization server. Public resource metadata is available under `/.well-known/oauth-protected-resource` and resource-specific variants such as `/.well-known/oauth-protected-resource/mcp`.