# AGENTS.md — ucalyptus.me

Guidance for AI agents (coding agents working in this repo, and answer/browser
agents visiting the live site). This is a personal academic/professional site
for **Sayantan Das** (Member of Technical Staff, Toronto; previously a Senior Applied AI Scientist at Manulife).

## What this site is

A Jekyll site (academicpages theme) served by **Cloudflare Pages**, with two
Cloudflare Workers in front for dynamic behavior. It publishes the author's
biography, research publications, agent-infrastructure projects, CV/resume,
blog, and talks — plus a full set of machine-readable discovery endpoints.

## Fastest way to understand the person or answer a question about them

Prefer these structured endpoints over scraping HTML:

- `/llms.txt` — concise overview for LLMs.
- `/llms-full.txt` — full-text dump of site content.
- `/api/site.json` — structured site data (identity, sections, publications, posts, projects).
- `/ai/faq.json` and the homepage `FAQPage` JSON-LD — common Q&A about the author.
- `/.well-known/agent-card.json` — A2A agent card (WebMCP + static interfaces).
- `/.well-known/mcp.json` — MCP manifest.
- `/openapi.json` — OpenAPI 3.1 spec for the real agent-auth API (below).

## Agent API (real, live)

A stateless OAuth 2.0 `client_credentials` server gates one extended-profile
endpoint. Full spec: `/openapi.json`. Human-readable flow: `/auth.md`.

1. `POST /oauth/register` → `client_id` + `client_secret` (HMAC-derived, not stored).
2. `POST /oauth/token` (`grant_type=client_credentials`) → 15-minute ES256 Bearer token.
3. `GET /api/agent/full-profile` with `Authorization: Bearer <token>` → extended CV/availability JSON.

Public JWKS: `/.well-known/jwks.json`. Discovery: `/.well-known/oauth-authorization-server`
and `/.well-known/oauth-protected-resource` (served per-host by the Worker).

## WebMCP

Every page registers WebMCP tools via `navigator.modelContext`
(`get_site_overview`, `search_content`, `list_content`, `get_content_item`,
`get_cv_summary`, `get_contact_info`, `get_faq`, and the OAuth-gated
`get_full_profile`). See `_includes/webmcp.html`.

## Repo conventions (for coding agents)

- **Deploy origin is Cloudflare Pages**, not GitHub Pages (the latter is stale).
  A `git push` to `master` triggers a Pages build (~5–6 min). The two Workers
  deploy via their own GitHub Actions when files under `workers/**` change.
- **Workers:** `workers/markdown-negotiation` (Accept: text/markdown, homepage
  `Link` headers, `/.well-known/api-catalog`) and `workers/agent-auth` (OAuth +
  gated endpoint + per-host OAuth discovery docs).
- **Static files with no extension** (e.g. `.well-known/oauth-*`) need their
  `Content-Type` forced in `_headers` — Pages guesses wrong otherwise.
- **Jekyll gotcha:** a file with YAML front matter is processed (Markdown→HTML);
  a file with *no* front matter is copied byte-for-byte. `auth.md` and this file
  are intentionally front-matter-free so they serve raw.
- **Commits:** author `ucalyptus <sdas.codes@gmail.com>`, **no** `Co-Authored-By`
  trailers.
- **Honesty rule for agent-readiness work:** never publish a discovery signal
  (fake API, fake commerce endpoint, fake login) for something that doesn't
  exist. Only describe real, live surfaces. See `files/agent-seo-playbook.md`.

## Status boards

- `CF_AEO.md` — isitagentready.com findings + status.
- `arrivl.md` — arrivl.ai AEO audit TODO.
- `ora.md` — ora.ai scan TODO.

## Contact

Email `hello@ucalyptus.me` · book a call at `https://cal.com/ucalyptus` ·
GitHub `ucalyptus` · LinkedIn `ucalyptus`.