# CalEvents Full Agent Context

CalEvents helps students and visitors discover upcoming UC Berkeley campus events. The site is optimized for both humans and agents: humans use the React application at the homepage, while agents should use the static JSON resources and discovery documents.

## Public Data Resources

### `GET /events.json`

Returns the current event snapshot:

```json
{
  "events": [
    {
      "id": "source:event-id",
      "title": "Event title",
      "organizer": "Campus unit",
      "date": "2026-04-30",
      "time": "4:00 PM",
      "location": "Venue",
      "description": "Event summary",
      "tags": ["Academic"],
      "topics": ["ai-machine-learning"],
      "url": "https://official-source.example/event",
      "source": "livewhale"
    }
  ],
  "sources": [{ "title": "Source title", "uri": "https://source.example" }],
  "lastUpdated": 1777560000000,
  "topic_vocabulary": {
    "version": 1,
    "topics": [
      {
        "slug": "ai-machine-learning",
        "label": "AI and Machine Learning",
        "group": "fields",
        "synonyms": ["ai", "machine learning"]
      }
    ]
  }
}
```

Use this file for event search, filtering, and recommendations. The file is regenerated by GitHub Actions and published through Vercel.

### `GET /status.json`

Returns the latest ingestion status. Important fields include:

- `generated_at`: ISO timestamp for the latest snapshot generation
- `total_events`: number of events in the published snapshot
- `sources`: per-source health records
- `fallback_used`: whether cached source data was used
- `data_quality_blocked`: whether the dataset should be treated as materially incomplete
- `topics.outcome`: `ok` or `error` for topic assignment in this publish
- `topics.assigned_count`: events assigned topics in this run
- `topics.carried_forward_count`: events that kept topics from the prior snapshot
- `topics.error`: optional topic assignment error

Recovered fallback state is an engineering signal, not user-facing copy. If `data_quality_blocked` is not true and events are present, agents can continue using the feed. Report `topics.outcome` separately from source health. A topic assignment error does not make an event source degraded. If `topics.outcome` is `error`, report `topics.carried_forward_count` and `topics.error`.

### `GET /search-index.json`

Returns a compact generated index for local search. Agents can use this for fast matching, but direct filtering over `events.json` is simpler and stable.

## Recommended Agent Workflow

1. Prefer homepage WebMCP `search_berkeley_events` when available (same ranked path as the UI).
2. Otherwise fetch `https://cal-events.com/events.json`.
3. Filter events by `date >= today` in America/Los_Angeles.
4. Filter by `tags[0]` for the primary displayed category.
5. Filter by `topics` for a published topic slug. Read valid slugs from `topic_vocabulary.topics`.
6. Present concise results with the official event `url`.
8. Share UI state via `?q=&date=&category=&topic=&source=&event=` (`build_calevents_url` / `apply_ui_state`).
9. If needed, fetch `https://cal-events.com/status.json` to explain freshness, source coverage, or topic assignment.

## URL Workspace

Query params on `https://cal-events.com/`: `q`, `date` (`today`|`tomorrow`|`week`|`upcoming`), `category`, `topic`, `source`, `event`. See `/for-agents.html`. Topic values come from `events.json.topic_vocabulary.topics`.

## CRUD Limits

Read-only. No create/update/delete for events or status via CalEvents.

## Source Ids

- `livewhale`: UC Berkeley Events
- `callink`: CalLink student organization events
- `cal_performances`: Cal Performances
- `calbears`: Cal Bears Athletics
- `bampfa`: Berkeley Art Museum and Pacific Film Archive
- `haas`: Berkeley Haas
- `berkeley_law`: Berkeley Law
- `simons`: Simons Institute
- `luma`: Luma Berkeley calendars
- `begin`: Berkeley Gateway to Innovation
- `ai_risk`: Berkeley AI Risk speaker series
- `brsl`: Berkeley Risk and Security Lab

## Content Policy

The event feed is public and may be indexed for search and used as agent input. The site does not grant permission to train foundation models on the content; see `robots.txt` Content Signals.