# 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`

### `/api/github/history`

Read-only lookup for the exact GitHub Now, Day, Week, or Month ranking published at
or before an ISO-8601 timestamp. Month is the rolling 30-day dashboard list shown at
that time, not a calendar-month recomputation.

Related docs:

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

The status endpoint also reports archive ranges for private daily star evidence and
actorless sampled WatchEvent batches. Those event batches are explicitly incomplete
because GitHub's public Events API is capped; they are not a global event stream.

### `/api/feed/history`

Read-only replay of the exact immutable Top Year publication archived at or before
a requested UTC timestamp:

```text
GET /api/feed/history?sort=year&at=<UTC-ISO-8601-Z>
```

`sort=year` is required; `at` defaults to now. The service selects the latest
manifest across immutable `top-year-v1`, `top-year-v2`, and `top-year-v3`
publications in the preserved legacy and versioned ledgers with
`published_at <= at`, verifies that exact content-addressed R2 object, and
returns the archived publication envelope verbatim. Use it for “what did Top
Year show then?” The algorithm version is part of the archive: older
publications retain their original semantics and are never translated into a
newer version. A corrupt or
unavailable selected archive fails closed; the service does not skip that
selected archive for an older publication, reconstruct a ranking, or fall back
to live Year, Month, or Trending data.

Successful responses support a strong `ETag`/`If-None-Match`, expose
`Last-Modified`, `Link`, and `X-Year-History-Requested-At` to CORS clients, and
preserve the coverage recorded at publication time.

Related docs:

- Human docs: `/docs/api/top-year-history.md`
- OpenAPI: `/docs/api/top-year-history/openapi.json`
- Current Year feed: `/api/feed?sort=year`

### Dashboard Top Year and agent chat

Use `/homepage/?sort=year` for the published rolling Top Year feed. Its target is
the latest 365 complete UTC days through the last completed day, and its coverage
fields disclose how much indefinite daily history is currently materialized.

Current `top-year-v3`, like preserved v2, treats `(feed source, source_id)` as
the event identity.
Hacker News and Lobsters rank by each event's latest stored points; LessWrong
ranks by latest stored karma. Comments break only an exact-primary tie. These
totals belong to events published inside the rolling window, but they are the
latest totals stored now—not engagement gained inside the window and not an
event-day snapshot.

Hype stays in its own column. Because GitHub, Hugging Face, Reddit, and Replicate
use incompatible native units, Hype compares each event by midpoint empirical
percentile within its known provider cohort, and a cohort needs at least five
eligible events. The merged `popular` Top 100 is news-only: Hacker News,
LessWrong, and Lobsters, compared by source percentile with no source quota or
repeated-source penalty and with exact URL/title duplicates removed. GitHub Year
remains empty with `status: "collecting"` until direct 365-day star-gain evidence
exists; no Month, Trending, lifetime-star, or repository-recency filler is valid.

V3 keeps v2's identity, ranking, and scoring formula unchanged. For ambiguous
legacy events that share a canonical destination, v3 hydrates the display title
from the owning source rather than borrowing another event's canonical title;
unsafe identity hydration blocks publication. Each v3 source event must carry
`event_title_verified: true` and nonempty `title_provenance`. Historical v1 and
v2 publications remain exact replays of what was actually published. Do not
reinterpret or relabel them using v3 rules.

The in-page chat's read-only `get_feed_snapshot` tool accepts `sort="year"` and a
limit up to 100, preserving the published order. Named calendar periods remain a
different bounded archive query and should not be used to reconstruct Top Year.

Related docs:

- Dashboard: `/homepage/?sort=year`
- Historical exact replay: `/api/feed/history?sort=year`
- Agent API: `/docs/api/agent-chat.md`
- Agent OpenAPI: `/docs/api/agent-chat/openapi.json`

## 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`.