# sfclarity — agent guide

This file is for an AI agent or crawler visiting sfclarity.com, not a contributor. (The repository's
own `AGENTS.md` is internal dev-workflow guidance — branch/merge rules, arc pointers — and is not
what an agent connecting to the live site needs.)

## What this site offers

A public, read-only directory of San Francisco tech events — AI-enriched, geocoded, no account
required, no paywall. There is no write access and no account or sign-in needed to read this data.

## How to connect

- **[`/openapi.json`](/openapi.json)** — OpenAPI 3.1 for the two real read-only endpoints (published
  events, landing-page stats), served directly by Supabase PostgREST under a publishable key that
  can only ever read `published = true` rows.
- **MCP server** — a minimal, unauthenticated, read-only JSON-RPC 2.0 server (`search_events`,
  `get_event`), deployed as a separate Cloudflare Worker, NOT on this domain:
  `https://sfclarity-mcp-server.cloudflare-driveway392.workers.dev/mcp`. Server card at that same
  Worker's own `/.well-known/mcp/server-card.json`.
- **[`/llms.txt`](/llms.txt)** — full site overview (llmstxt.org convention).
- **[`/index.md`](/index.md)** — markdown twin of the homepage; any page with one is served via
  `Accept: text/markdown` content negotiation.
- **[`/.well-known/api-catalog`](/.well-known/api-catalog)** — RFC 9727 API catalog (linkset).
- **[`/.well-known/ai-catalog.json`](/.well-known/ai-catalog.json)** — Agentic Resource Discovery
  (ARD) entry, now including the MCP server above.
- **[`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json)** — agent-skills
  index entry for the MCP server.
- **[`/developers`](/developers)** — a human-readable page collecting every surface above in one
  place, plus this API's two real error shapes.
- **[`robots.txt`](/robots.txt)** — AI-agent traffic is explicitly welcome (`Content-Signal:
search=yes,ai-input=yes,ai-train=no,use=reference`).

Nonexistent paths on THIS domain (including agent-surface probes like `/api/*`, `.well-known/mcp*`,
and OAuth metadata) return a real `404` status — JSON body for a non-browser `Accept` — never a `200`
soft-404. The MCP server above lives on its own separate domain and is the one real exception to
"no `.well-known/mcp*` here" — it was never added to sfclarity.com itself.

## Source

The source repository is private, not publicly browsable. This site — `llms.txt`, `AGENTS.md`, and
`openapi.json` — is the canonical, always-reachable agent-facing interface. Bug reports and
feature requests go to [`sfsanityorg/sfclarity-issues`](https://github.com/sfsanityorg/sfclarity-issues)
(public issue tracker) — see [`/contact`](/contact). [`/privacy`](/privacy) states what's
collected today.