# Super Calendar Agent Contract

Contract version: 1.0.0  
Audience: autonomous agents, LLM tools, crawlers, coding assistants, MCP clients, calendar clients, and integration builders.

This document is the operational contract for interacting with Super Calendar. `/llms.txt` is the short map. This file is the behavior contract.

## 1. Core model

Super Calendar converts time-related data into portable calendar-ready events.

```txt
source data -> domain adapter -> normalized event semantics -> output surface
```

The domain is not the product. Weather, moon phases, holidays, exchange rates, crypto, earnings, seasons, religion, trivia, custom events, spaces, and future sources are adapters.

The product-level abstraction is:

```txt
temporal data -> event semantics -> portable surface
```

Portable surfaces may include ICS/WebCal, JSON/XML, text/ANSI/HTML, CSV/TSV/NDJSON/JSONL when documented, I/O nodes, MCP tools, and deterministic interaction gateway flows.

## 2. Authority order

When sources conflict, use this order:

1. User explicit instruction for the current task.
2. OpenAPI for HTTP routes, parameters, response schemas, and supported formats.
3. MCP tool contract when using MCP.
4. I/O API contract for low-level node addressing.
5. Runtime i18n manifest for language availability and file mapping.
6. Capability registry for capability planning and lifecycle labels.
7. Workflow state machines for execution order.
8. This contract for behavior and safety rules.
9. `/llms.txt` for discovery and routing.
10. Human documentation for explanation and examples.
11. Prior model knowledge only as weak context, never as executable contract.

Do not use intuition or pattern matching to invent missing parameters, routes, formats, domains, lifecycle states, authentication, billing, or storage behavior.

## 3. Primary machine-readable contracts

| Purpose | Resource |
|---|---|
| Agent behavior | `/agents/contract.md` |
| Agent discovery index | `/agents/index.json` |
| Capability planning | `/agents/capabilities.json` |
| Capability schema | `/agents/capabilities.schema.json` |
| Gateway request/response schema | `/agents/gateway.schema.json` |
| Workflow state machines | `/agents/workflows.json` |
| Workflow schema | `/agents/workflows.schema.json` |
| Contract/version metadata | `/agents/version.json` |
| HTTP route behavior | `/api/swagger/json` |
| I/O node behavior | `/io/ioapi.json` |
| Runtime language availability | `/common/i18n/manifest.json` |
| Human import instructions | `/importing/` |

## 4. Discovery rules

Agents must discover before executing:

1. Read `/llms.txt` for identity and routing.
2. Read `/agents/index.json` for agent resources.
3. Read `/agents/contract.md` for behavior rules.
4. Read `/agents/capabilities.json` before choosing domain/surface.
5. Read `/api/swagger/json` before constructing HTTP requests.
6. Read `/io/ioapi.json` before constructing I/O node URLs.
7. Read `/common/i18n/manifest.json` before claiming language availability.
8. Read MCP tool descriptions before invoking MCP tools.

If a contract is missing or unreachable, report the missing contract instead of guessing.

## 5. Lifecycle states

Allowed labels: `stable`, `beta`, `alpha`, `experimental`, `planned`, `deprecated`, `unknown`.

If a route or surface has no lifecycle label, do not call it stable by assumption.

## 6. Capability registry

Use `/agents/capabilities.json` for high-level planning: domains, surfaces, preferred output, lifecycle, required validation contract, and public/authenticated/internal status.

The registry is not a substitute for OpenAPI, MCP, or I/O contracts.

```txt
capabilities.json decides what to try
OpenAPI/MCP/I/O decides how to execute
```

## 7. Domain model

Known public or planned domains may include: `weather`, `moon`, `holidays`, `exchange`, `crypto`, `earnings`, `seasons`, `religion`, `events`, `trivia`, `custom`, `spaces`.

A domain is a source adapter, not a guarantee of identical behavior. Never assume shared parameters, event fields, format support, i18n support, cache behavior, rate limits, preview behavior, or authentication behavior across domains.

## 8. Domain-to-surface binding

Choose output surface by task and by `/agents/capabilities.json`.

General guidance:

```txt
ics     calendar import/subscription
webcal  calendar subscription links
json    application integration or debugging
xml     XML-based clients or explicit user request
text    simple readable output
ansi    terminal-friendly output
html    browser-readable document output
csv     tabular export when documented
tsv     tabular export when documented
ndjson  stream or batch processing when documented
jsonl   JSON Lines alias for NDJSON when documented
io      low-bandwidth node reads
mcp     tool-based agent interaction
gateway guided deterministic choices
```

Do not claim a format works for a domain until the authoritative contract confirms it.

## 9. Feed-generation workflow

When a user asks for a calendar feed:

1. Identify the domain from intent.
2. Read the capability registry.
3. Confirm the domain lifecycle.
4. Read OpenAPI for exact route, parameter names, and supported formats.
5. Ask only for required missing parameters.
6. Use explicit user input first.
7. Preserve explicit language, region, units, timezone, and surface choices.
8. Generate URLs only with documented parameters.
9. Offer preview/import/copy actions only where UI or documentation supports them.
10. Explain that WebCal subscriptions update over time, while downloaded ICS files may be static depending on the client.
11. If the feed may contain private data, warn that the URL may function as an access credential.

Do not silently add location, language, timezone, country, or personalization based on IP or model assumptions.

## 10. Developer workflow

When a developer asks how to integrate: start with OpenAPI, identify the domain/route, confirm required and optional parameters, confirm supported formats, provide a minimal request, and point to I/O/MCP/gateway only when the use case needs those surfaces.

Do not present undocumented convenience URLs as stable APIs.

## 11. Autonomous-agent workflow

When an autonomous agent acts without continuous user confirmation: prefer deterministic gateway when available, MCP when supported, OpenAPI for HTTP, I/O for low-level reads, stop on missing parameters, and return a missing-capability report instead of guessing.

A missing-capability report must include: `requested_task`, `selected_domain`, `selected_surface`, `missing_parameter_or_route`, `contracts_checked`, and `safe_next_action`.

## 12. Gateway behavior

The interaction gateway, when available, is a deterministic decision layer:

```txt
user intent -> menu/options -> validated choice -> domain action -> output surface
```

Use `/agents/gateway.schema.json` for input/output shape. Do not assume the gateway exists unless it is advertised by `/llms.txt`, `/agents/capabilities.json`, OpenAPI, MCP, or another explicit deployment contract.

If the gateway exists in one document but not in OpenAPI, treat it as `beta` or `experimental` unless explicitly marked `stable`.

## 13. MCP behavior

When using MCP: discover tools from the MCP contract, use tool schemas instead of HTTP route guessing, do not map REST parameters to MCP arguments unless confirmed, report tool absence instead of inventing tools, and preserve privacy constraints.

MCP is an agent surface. REST/OpenAPI is an application surface. They may overlap but are not identical by assumption.

## 14. I/O node behavior

I/O nodes are deterministic, small, low-bandwidth reads for widgets, simple clients, embedded devices, CLIs, shell scripts, low-cost previews, agent field reads, and bandwidth-sensitive environments.

Follow `/io/ioapi.json` for root, table, row, column, cell, field, format suffixes, and indexing rules. Do not derive arbitrary I/O paths from examples unless the I/O contract permits that shape.

## 15. Language and agnostic serving

Anonymous runtime language resolution priority:

1. Explicit user input, such as `?lang=pt-BR`.
2. Explicit app configuration.
3. Browser preference exposed locally, such as `navigator.languages`.
4. Document default, such as static HTML `lang`.
5. System fallback, currently `en`.

Rules: browser preference outranks static HTML default; IP must not be used for language; country must not be inferred from network location; anonymous browser language must not be persisted; explicit choice always wins.

Use `/common/i18n/manifest.json` for available languages.

## 16. Privacy contract

For anonymous visitors: do not infer language from IP, infer country from IP, infer geolocation, persist anonymous language preference, fingerprint visitors, personalize from infrastructure metadata, or assume identity.

For authenticated spaces: preferences may be stored only as user/account/space-managed data; permissions must be respected; private feed URLs must be treated as credentials and must not be exposed in logs, public replies, examples, screenshots, or telemetry.

## 17. WebCal and ICS link handling

A public feed URL may be shared only if the content is intended to be public. A private feed URL may reveal personal events, internal notes, routines, bookings, sensitive schedules, corporate workflows, or custom user content.

Warn when private content is possible:

```txt
Anyone with this link may be able to view the feed. Treat it like an access credential.
```

## 18. Calendar semantics

Respect iCalendar semantics: all-day `DTEND` is exclusive; do not guess timezone conversion; do not change recurrence rules unless requested; do not localize dates by IP; preserve explicit language and calendar-surface choices; do not convert a WebCal subscription into static ICS unless requested.

## 19. Runtime pages and hydration

Some public pages assemble commands, language, direction, high-level/low-level surfaces, and previews at runtime. Do not treat crawler-visible loading states as proof that a feature does not exist. Prefer machine-readable manifests and API contracts.

## 20. Error behavior

When a request fails: report exact contract used, exact route attempted, missing required parameters separately from server errors, and do not retry with guessed parameter names or switch domains silently.

Preferred error response:

```txt
I could not complete the request because the documented contract does not expose <capability>. I checked <contract>. Safe next step: <action>.
```

## 21. Do and do not

Do: use OpenAPI before URLs, capability registry before domain/surface selection, MCP before tool calls when available, I/O API before node addressing, i18n manifest for languages, preserve explicit choices, treat private links as credentials, and report missing capability instead of inventing it.

Do not: invent routes or parameters, assume schema uniformity across domains, infer language/country/timezone/location from IP, persist anonymous preferences, expose private feed links, treat runtime placeholders as final state, or call alpha/beta/experimental routes stable without documentation.