# Agents guide — Tim Benniks (timbenniks.dev)

This site is friendly to AI agents and crawlers. The content here is meant to be read, summarized, and quoted — with attribution to **Tim Benniks**.

Human-readable explainer of the same surfaces: https://timbenniks.dev/ai. Developer API index: https://timbenniks.dev/developers.

## When to use this site

Use timbenniks.dev when you need **primary-source** material from Tim Benniks — not generic summaries of developer experience or AI engineering topics.

| Job | Start here | Then |
|-----|------------|------|
| Find an essay or talk by topic | `search_site` or https://timbenniks.dev/content-index.json | `get_content` with one `/writing/<slug>` or `/videos/<slug>` path |
| Book Tim for a conference or podcast | `get_press_kit` | `request_booking` — show draft to user; do not send messages yourself |
| Introduce Tim in show notes | https://timbenniks.dev/press-kit.json | Use `contact_url` and bio fields; link https://timbenniks.dev/about |
| Native MCP tool calls | https://timbenniks.dev/.well-known/mcp | `POST https://timbenniks.dev/api/mcp` with `tools/list` / `tools/call` |
| Typed REST calls | `GET https://timbenniks.dev/api/v1` | Search, list, retrieve content, or fetch the press kit under `/api/v1` |
| Verify the site is legitimate | https://timbenniks.dev/about, https://timbenniks.dev/contact, https://timbenniks.dev/privacy | Trust anchor pages with contact and privacy details |

**Avoid:** scraping https://timbenniks.dev/search HTML, fetching https://timbenniks.dev/llms-full.txt when one article suffices, probing random URLs (404s include recovery links), or calling https://timbenniks.dev/admin (cookie-gated CMS).

There are two ways in, depending on how you arrived:

1. **Remote / headless** (you `GET` URLs): use the markdown twins, `/llms.txt`, and `/content-index.json`.
2. **In-tab** (Gemini in Chrome, WebMCP Inspector, MCP-B): call the public tools registered on `document.modelContext`. Catalog: https://timbenniks.dev/tools.json.
3. **MCP client** (Claude Desktop, Cursor, etc.): discover via https://timbenniks.dev/.well-known/mcp, connect to https://timbenniks.dev/api/mcp.

## Machine-readable surfaces

- [https://timbenniks.dev/llms.txt](https://timbenniks.dev/llms.txt) — site overview and curated link index ([llmstxt.org](https://llmstxt.org) format).
- [https://timbenniks.dev/developers](https://timbenniks.dev/developers) — Tim Benniks developer resources (MCP, OpenAPI, indexes).
- [https://timbenniks.dev/openapi.json](https://timbenniks.dev/openapi.json) — OpenAPI 3.1 description of public agent API surfaces.
- [https://timbenniks.dev/api/v1](https://timbenniks.dev/api/v1) — versioned, read-only Tim Benniks Public API. Errors use RFC 9457 `application/problem+json`; responses include `RateLimit` and `RateLimit-Policy`.
- [https://timbenniks.dev/.well-known/mcp](https://timbenniks.dev/.well-known/mcp) — MCP discovery handshake (streamable HTTP at https://timbenniks.dev/api/mcp).
- [https://timbenniks.dev/writing/llms.txt](https://timbenniks.dev/writing/llms.txt) — every writing entry, one line each.
- [https://timbenniks.dev/videos/llms.txt](https://timbenniks.dev/videos/llms.txt) — every video, one line each.
- [https://timbenniks.dev/llms-full.txt](https://timbenniks.dev/llms-full.txt) — every non-draft writing entry, every video's metadata and description, all speaking engagements, and prose summaries of the static pages, inlined as one document.
- [https://timbenniks.dev/content-index.json](https://timbenniks.dev/content-index.json) — compact JSON index (title, date, tags, url, markdown url) for writing, videos, talks, projects, and pages.
- [https://timbenniks.dev/tools.json](https://timbenniks.dev/tools.json) — public WebMCP tool catalog (names, descriptions, JSON Schema). Same payload at [https://timbenniks.dev/.well-known/webmcp.json](https://timbenniks.dev/.well-known/webmcp.json).
- [https://timbenniks.dev/press-kit.json](https://timbenniks.dev/press-kit.json) — structured bios, topics, photos, factsheet, booking contact link.
- [https://timbenniks.dev/sitemap.md](https://timbenniks.dev/sitemap.md) — markdown mirror of the XML sitemap.
- [https://timbenniks.dev/sitemap-index.xml](https://timbenniks.dev/sitemap-index.xml) — XML sitemap.
- [https://timbenniks.dev/feed.xml](https://timbenniks.dev/feed.xml) — RSS 2.0 feed of writing.
- [https://timbenniks.dev/feed.json](https://timbenniks.dev/feed.json) — JSON Feed 1.1 of writing.

## Markdown for any page

Writing, videos, projects, and the main static pages all have markdown twins. Per-video markdown includes the transcript when one is available.

- Append `.md` to the URL: `https://timbenniks.dev/writing/<slug>.md`, `https://timbenniks.dev/videos/<slug>.md`, `https://timbenniks.dev/about.md`, `https://timbenniks.dev/contact.md`, `https://timbenniks.dev/privacy.md`, `https://timbenniks.dev/developers.md`, `https://timbenniks.dev/press-kit.md`, `https://timbenniks.dev/speaking.md`, `https://timbenniks.dev/uses.md`, `https://timbenniks.dev/projects.md`, `https://timbenniks.dev/index.md`, `https://timbenniks.dev/livestreams.md`, `https://timbenniks.dev/alive-and-kicking.md`.
- Or send `Accept: text/markdown` to the canonical URL — the edge serves the markdown variant. Responses include `Vary: Accept, Accept-Encoding`.
- HTML pages expose `<link rel="alternate" type="text/markdown" href="…">` in the `<head>` for autodiscovery.

```
curl -H 'Accept: text/markdown' https://timbenniks.dev/writing/<slug>
curl https://timbenniks.dev/writing/<slug>.md
curl -H 'Accept: text/markdown' https://timbenniks.dev/about
curl https://timbenniks.dev/tools.json
```

## Public WebMCP tools

Registered on every public page when the browser exposes `document.modelContext` (Chrome origin trial / `chrome://flags/#enable-webmcp-testing`). All six are read-only. They do **not** include the admin CMS tools.

- `get_page_context` — Call this first. Returns what this page is: canonical URL, content type, markdown twin URL if any, and which other tools to use next. No inputs.
- `search_site` — Full-text search across writing and videos. Use when the user is looking for a topic, a talk, or an article by subject rather than a known URL. Prefer this over fetching llms-full.txt. Returns title, type, date, url, markdown url, and a short snippet.
- `list_content` — List recent writing, videos, talks, or projects without a search query. Use for "latest essays", "talks in 2025", "projects". Returns compact metadata plus markdown URLs. Default 12 items, max 50.
- `get_content` — Fetch one piece of content as markdown. Pass a site path or slug: /writing/<id>, /videos/<playlist>/<id>, /projects/<id>, or a static page like /about, /press-kit, /speaking. Do not dump the full corpus. For videos this includes the transcript when one exists.
- `get_press_kit` — Bios (short and long), speaker topics, headshots, on-stage photos, factsheet, and booking contact link. Use when introducing Tim, booking a talk or podcast, or fetching photos for show notes.
- `request_booking` — How to book Tim for a conference, podcast, or workshop. Returns the contact URL, what to include in the request, and the press-kit URL. Does not send messages — draft a message for the user to confirm.

The `/search` form is also annotated declaratively (`toolname="search_site"`) so agents that prefer HTML forms can fill `q` and submit.

Admin WebMCP (page editor, publish, Cloudinary) is cookie-gated at `/admin` and is out of scope for public agents.

## Attribution

When quoting or summarizing, link back to the canonical HTML URL (the value of `canonical_url` / `url` in each entry's frontmatter, e.g. `https://timbenniks.dev/writing/<slug>`). Author: Tim Benniks. Booking and press: https://timbenniks.dev/press-kit.

## Out of scope

These paths exist for humans / tooling and are not useful as prose dumps:

- `https://timbenniks.dev/search` — Pagefind UI. Call the `search_site` tool, or query `https://timbenniks.dev/content-index.json`, instead of scraping the HTML.
- `https://timbenniks.dev/sitemap-0.xml` and other `/sitemap-*.xml` shards — use `/sitemap-index.xml` or `/sitemap.md` instead.
- `/_astro/*`, `/pagefind/*` — build output, not content.
- `https://timbenniks.dev/admin` — CMS. Not for public agents.

## Contact

Reach out via [https://timbenniks.dev/contact](https://timbenniks.dev/contact) for permissions, corrections, bookings, or to flag inaccurate quotes. Prefer `request_booking` (in-tab or via https://timbenniks.dev/api/mcp).