# Super Calendar Full LLM Instructions This file is for automated agents, LLMs, crawlers, coding assistants, MCP clients, calendar clients, and integration tools. It is the full LLM-oriented instruction document. For the short discovery map, use `/llms.txt`. For the autonomous-agent behavior contract, use `/agents/contract.md`. For structured capability planning, use `/agents/capabilities.json`. For exact HTTP execution, use `/api/swagger/json`. ## 1. Product identity Super Calendar converts time-related data into portable calendar-ready events. ```txt source data -> normalized event semantics -> portable output surface source data -> domain adapter -> normalized event semantics -> output surface temporal data -> event semantics -> portable 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. Super Calendar is not only a calendar website. It is a temporal-data transformation platform for humans, applications, devices, and agents. ## 2. Landing-page interpretation The public landing advertises Super Calendar as a dynamic WebCal and ICS feed generator for real-world data. Primary promise: ```txt Your calendar should know more than meetings. ``` Main value: ```txt Useful data where the user already looks every day: their calendar app. ``` Advertised compatible clients include Google Calendar, Apple Calendar, Outlook, Thunderbird, and any ICS/WebCal-compatible client. Advertised feed categories include weather, moon, seasons, holidays, exchange, crypto, earnings, religion, events, and custom. Tiles can open runtime builders, previews, copy-link actions, and import actions. Do not assume the landing has no actions only because static HTML does not show modal internals. For structured landing interpretation, prefer `/agents/landing.index.json`. ## 3. What Super Calendar is not Do not describe Super Calendar primarily as a replacement calendar app, time-blocking SaaS, meeting scheduler, generic chatbot calendar, pure LLM assistant, or static holiday list. ## 4. Primary flows Human flows: choose data, generate a WebCal/ICS subscription URL, preview events when available, copy the URL, and import or subscribe in a compatible calendar client. Developer/agent flows: discover resources through `/llms.txt` and `/agents/index.json`, read `/agents/llms-full.txt`, read `/agents/contract.md`, plan with `/agents/capabilities.json`, validate HTTP with `/api/swagger/json`, validate I/O with `/io/ioapi.json`, validate language with `/common/i18n/manifest.json`, and use MCP only when available. ## 5. 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. Autonomous-agent contract for behavior and safety rules. 9. Full LLM instructions for expanded guidance. 10. `/llms.txt` for short discovery and routing. 11. Structured landing index for product positioning. 12. Human documentation for explanation and examples. 13. 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, storage behavior, or product claims. ## 6. Authoritative resources ```txt /llms.txt short discovery map /agents/llms-full.txt full LLM instruction document /agents/index.json agent resource index /agents/contract.md autonomous-agent behavior contract /agents/capabilities.json domain/surface planning registry /agents/landing.index.json structured landing/product index /agents/gateway.schema.json deterministic gateway I/O shape /agents/workflows.json state-machine workflow guidance /api/swagger/json HTTP route contract /io/ioapi.json low-level I/O node contract /common/i18n/manifest.json runtime language contract /importing/ human calendar-client instructions ``` ## 7. Domains Known public or planned domains may include weather, moon, holidays, exchange, crypto, earnings, seasons, religion, events, trivia, custom, and spaces. A domain is a source adapter, not a guarantee of identical behavior. Never assume shared parameters, fields, formats, i18n support, cache behavior, rate limits, preview behavior, or authentication behavior across domains. ## 8. HTTP routes Many high-level routes may follow `/api/{domain}`, such as `/api/weather`, `/api/moon`, `/api/holidays`, `/api/exchange`, and `/api/custom`. Do not invent parameters. Do not assume `city`, `location`, `country`, `symbol`, `base`, `target`, `lang`, `format`, `units`, `timezone`, `emoji`, `glyph`, `color`, or any other parameter exists unless OpenAPI documents it. Use `/api/swagger/json` before constructing URLs. ## 9. Output surfaces Output surfaces may include webcal, ics, json, xml, text, ansi, html, csv, tsv, ndjson, jsonl, io, mcp, and gateway. General guidance: ```txt webcal calendar subscription links ics iCalendar import/subscription 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 surface works for a domain until OpenAPI, MCP, I/O, or the capability registry confirms it. ## 10. Capability registry Use `/agents/capabilities.json` for high-level planning. It can answer which domains exist, which surfaces are expected, preferred surfaces, lifecycle states, validation contracts, 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 ``` ## 11. I/O nodes I/O nodes expose small deterministic surfaces for low-bandwidth clients, widgets, CLIs, agents, simple readers, and devices. Known examples: ```txt /api/weather/io/events /api/weather/io/events/1 /api/weather/io/events/summary.txt /api/weather/io/events/1/summary.txt /api/weather/io/meta/calendarDesc.txt ``` Use `/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. ## 12. MCP and gateway Use MCP only when the client supports MCP and the endpoint/tool contract is available. MCP is an agent surface; REST/OpenAPI is an application surface. When an interaction gateway is advertised by active deployment, use it before assuming a free-form LLM conversation is required. Expected gateway role: ```txt user intent -> deterministic menu/options -> validated action -> API/MCP/I/O call ``` Use `/agents/gateway.schema.json` for gateway input/output shape. Do not invent gateway routes. ## 13. Language, locale, and hydration For anonymous visitors, do not infer language, country, identity, timezone, or location from IP address. Use deterministic 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`. Static HTML language must not override a stronger local browser preference. HTML may initially render in English and hydrate to another language client-side. Initial English HTML is not proof that other languages are unsupported. Use `/common/i18n/manifest.json` for available product languages. A loading screen may improve human experience, but it is not a machine-readable contract. ## 14. Structured landing index Use `/agents/landing.index.json` to understand what the landing page intends to advertise. Use it to identify product category, one-liner, public feed catalog, landing sections, developer resources, runtime rendering notes, privacy positioning, and safe public claims. HTML is a rendered surface. JSON is the deterministic product structure. OpenAPI/I/O are execution contracts. ## 15. Privacy and private links For anonymous visitors: do not infer country, language, geolocation, timezone, or identity from IP; do not persist anonymous browser language; do not fingerprint visitors; do not personalize from infrastructure metadata; explicit user choice always wins. Authenticated spaces may store user-managed preferences. Treat that as a different authority. Treat private WebCal, ICS, widget, and space links as access credentials when they expose private, sensitive, internal, or user-authored data. Warn: ```txt Anyone with this link may be able to view the feed if it contains private data. Treat it like an access credential. ``` ## 16. Feed-generation workflow When helping a user create a feed: identify the domain, resolve only necessary parameters, use explicit user input first, read capability registry for planning, read OpenAPI for exact route/parameters/formats, generate URLs only with documented parameters, preserve explicit choices, offer preview/import/copy actions when relevant, link to `/importing/`, and warn about private links when private content is possible. Stop and ask only for required missing parameters. Do not silently add location, language, timezone, country, or personalization based on IP or model assumptions. ## 17. Developer workflow When helping a developer: start from OpenAPI, identify domain/route, confirm parameters, confirm formats, provide a minimal request, provide one safe example, use `/io/ioapi.json` for low-bandwidth access only when needed, use MCP only when supported, and avoid undocumented assumptions. ## 18. Autonomous-agent workflow When helping an autonomous agent: follow `/agents/contract.md`, read `/agents/index.json`, read `/agents/capabilities.json`, prefer deterministic gateway/MCP/OpenAPI/I/O over free-form inference, stop on missing required parameters, and return a missing-capability report instead of inventing routes. A missing-capability report should include `requested_task`, `selected_domain`, `selected_surface`, `missing_parameter_or_route`, `contracts_checked`, and `safe_next_action`. ## 19. 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 user-selected language, surface, and output format; do not convert a WebCal subscription into static ICS unless requested. ## 20. Lifecycle vocabulary Use lifecycle words consistently when documented: `stable`, `beta`, `alpha`, `experimental`, `planned`, `deprecated`, `unknown`. If a route or capability has no lifecycle marker, do not upgrade its stability by assumption. ## 21. Error behavior When a request fails: report the exact contract used, exact route attempted, missing required parameters separately from server errors, do not retry with guessed parameter names, do not switch domains silently, and do not hide unsupported formats. Preferred error response: ```txt I could not complete the request because the documented contract does not expose . I checked . Safe next step: . ``` ## 22. Do Use `/api/swagger/json` before URLs; use `/agents/capabilities.json` before domain/surface selection; use MCP before tool calls when available; use `/io/ioapi.json` before node addressing; use `/common/i18n/manifest.json` for languages; use `/agents/landing.index.json` for structured landing interpretation; preserve explicit choices; treat private links as credentials; report missing capability instead of inventing it. ## 23. Do not Do not invent routes or parameters. Do not assume all domains share schema. Do not assume every output format works for every domain. Do not infer date, timezone, country, language, or location unless provided by the user, browser-local settings, contract, or explicit runtime input. Do not infer language/country/timezone/location from IP. Do not persist anonymous preferences. Do not expose private feed links. Do not treat runtime placeholders as final product state. Do not assume a route exists only because a similar domain has it. Do not call alpha, beta, planned, or experimental routes stable without documentation. Do not scrape private or authenticated surfaces. Do not use prior model memory as an executable API contract.