{
  "$schema": "https://super-calendar.io/agents/surfaces.schema.json",
  "name": "Super Calendar Surface Decision Contract",
  "version": "1.0.0",
  "kind": "surface-decision-contract",
  "description": "Deterministic guidance for choosing output surfaces. This file does not replace OpenAPI; it tells agents which documented surface to prefer.",
  "surfaces": {
    "webcal": { "purpose": "Calendar subscription URL for humans and calendar clients." },
    "ics": { "purpose": "iCalendar file output for import, download, or calendar clients." },
    "json": { "purpose": "Structured application and agent output." },
    "xml": { "purpose": "Structured XML output for crawlers, legacy clients, and XML-first consumers." },
    "text": { "purpose": "Plain text output for low-complexity clients." },
    "ansi": { "purpose": "Terminal-oriented output." },
    "html": { "purpose": "Human-readable document output when documented." },
    "csv": { "purpose": "Tabular export." },
    "tsv": { "purpose": "Tabular export with tab separators." },
    "ndjson": { "purpose": "Line-oriented JSON stream." },
    "jsonl": { "purpose": "Alias for NDJSON when documented." },
    "io": { "purpose": "Low-bandwidth node addressing." }
  },
  "decision_order": [
    "honor_explicit_user_surface_if_documented",
    "honor_client_protocol_requirement",
    "prefer_domain_default",
    "fall_back_only_to_documented_surfaces",
    "stop_if_no_documented_surface_matches"
  ],
  "domain_defaults": {
    "weather": {
      "agent": "json",
      "crawler": "xml",
      "calendar_client": "ics",
      "human_subscription": "webcal",
      "low_bandwidth": "io",
      "fallback": ["json", "xml", "text"]
    },
    "exchange": {
      "agent": "json",
      "crawler": "xml",
      "calendar_client": "ics",
      "human_subscription": "webcal",
      "low_bandwidth": "io",
      "fallback": ["json", "csv", "text"]
    },
    "moon": {
      "agent": "json",
      "crawler": "xml",
      "calendar_client": "ics",
      "human_subscription": "webcal",
      "low_bandwidth": "io",
      "fallback": ["json", "xml", "text"]
    },
    "seasons": {
      "agent": "json",
      "crawler": "xml",
      "calendar_client": "ics",
      "human_subscription": "webcal",
      "low_bandwidth": "io",
      "fallback": ["json", "xml", "text"]
    },
    "religion": {
      "agent": "json",
      "crawler": "xml",
      "calendar_client": "ics",
      "human_subscription": "webcal",
      "low_bandwidth": "io",
      "fallback": ["json", "jsonl", "text"]
    }
  },
  "rules": {
    "do_not_try_random_formats": true,
    "do_not_use_probabilistic_fallback_for_public_execution": true,
    "validate_supported_formats_in_openapi": true,
    "private_feed_urls_are_credentials": true
  }
}