# Build with Sure

Sure provides calendar building blocks for people, companies, and their agents.
Automate what you want to automate. Control what you want to control.

Start with a simple booking page. Change its copy, availability, or questions
through MCP. Give your coding agent a normal Git remote to reshape the entire
frontend. Preview your work, then publish when you want it live.

These initial public contracts describe shipped behavior, reviewed September 28,
2026. Account access currently requires an invitation.

## Start small

Follow the [quickstart](https://sure.day/docs/quickstart.md) to connect an agent and publish one change.
The owner creates a page and project token inside Sure; the agent uses that token
to work on that one page.

| You want to… | Use |
| --- | --- |
| Read private calendars, review source edits, or define labels | [Calendar MCP](https://sure.day/docs/calendar.md) |
| Edit copy, colors, availability, or intake questions | [Project MCP and configuration](https://sure.day/docs/configuration.md) |
| Build an entirely different frontend | [Sure-hosted Git and source files](https://sure.day/docs/projects.md#hosted-git) |
| Preview, commit, publish, or roll back | [Project MCP](https://sure.day/docs/projects.md) |
| Find a time, book, reschedule, or cancel | [Public booking RPC](https://sure.day/docs/booking.md) |

Project MCP and Git edit the same project source. A Git push updates the draft. Publishing
is a separate action; the normal Sure Publish button commits a changed draft for
you.

## Choose the right access

**The owner's calendar agent** uses a calendar access token with
`https://mcp.sure.day/mcp`. It can read that owner's connected sources. Applying
event changes needs both an editable agent grant and separate source-management
permission. [Connect a calendar agent](https://sure.day/docs/calendar.md).

**The owner's frontend agent** uses a project token with
`https://app.sure.day/project-mcp` or that project’s Git remote. It can read and
edit source, change scheduling policy, and publish. Keep the token in the agent’s
secret configuration, never in public frontend code or a Git remote URL.

**The booker or their agent** uses `https://app.sure.day/booking-rpc`. Reading
slots and creating a booking require no owner login. Changing an existing booking
requires its private management token. Availability does not expose event titles
or attendees.

Use the direction the owner or booker has given you. After a timeout, check the
current state and reuse the same idempotency key for the same booking request.
A pending operation is not a confirmed booking.

## Read these docs with an agent

- [Project MCP and Git reference](https://sure.day/docs/projects.md)
- [Calendar MCP and source edits](https://sure.day/docs/calendar.md)
- [Frontend and scheduling configuration](https://sure.day/docs/configuration.md)
- [Booking RPC reference](https://sure.day/docs/booking.md)
- [Project MCP tool schemas](https://sure.day/docs/mcp-tools.json), generated from the implemented project catalog;
  authenticated `tools/list` is authoritative.
- [Agent index](https://sure.day/llms.txt) and
  [complete reference as text](https://sure.day/llms-full.txt).

Mintlify’s documentation search MCP, if enabled for this site, searches these
pages. It does not authorize either calendar or project operations. Calendar MCP
and project MCP use separate endpoints, tokens, and tool catalogs.

## What is available today

Projects host static HTML, CSS, and JavaScript with one scheduling offer per
project. Git accepts fast-forward updates to `main`. Public booking supports
creation, rescheduling, and cancellation of Sure-created Google Calendar bookings
after the owner selects a destination and grants booking write access.

External project MCP does not expose private calendar reads, account connections,
concierge conversations, memory, worker control, or voice. Private calendar reads
and supported source-event changes use the separate owner-authorized calendar MCP.
Concierge conversations, memory, workers, and voice remain inside Sure. Payments,
team routing, and webhooks are future possibilities, not current public contracts.


---

# Quickstart

Use your own MCP-capable agent to change a booking page's heading. The same workflow applies to its HTML, CSS, JavaScript, scheduling rules, and questions.

## 1. Get a project token

An invited owner signs in at [app.sure.day](https://app.sure.day), opens the Calendars settings gear, then **Booking pages**, and creates or selects a page. Under **Advanced → Agent access**, choose **Create access token**. Save it in your agent's secret configuration; it is shown only once.

Connect your agent to `https://app.sure.day/project-mcp` with an `Authorization: Bearer <PROJECT_ACCESS_TOKEN>` header. Replace the placeholder through your client's secret settings. Keep the token out of source files, remote URLs, commits, and logs.

**Use project MCP for this workflow.** It reads and changes your selected page. [Calendar MCP](https://sure.day/docs/calendar.md) uses a different endpoint and token to read private calendar events and apply authorized source edits. The docs site's search MCP only finds documentation. These credentials and tool catalogs are separate.

Your MCP client should initialize with protocol version `2025-03-26` and discover the tools with `tools/list`. See the [connection contract](https://sure.day/docs/projects.md#mcp-connection) and [tool schemas](https://sure.day/docs/mcp-tools.json) if configuring a client manually. The token selects one existing project; there is no project creation or token-management tool on this endpoint.

## 2. Read the page

Call `project_get` with empty arguments:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "project_get", "arguments": {} }
}
```

Successful tool results contain JSON in `result.content[0].text`. Check `result.isError` before parsing it. Retain the returned `revision`, `files`, and `config`.

`revision` is the source version used for edits. It is not `gitCommit`, which is a Git commit SHA. Use the current source revision for every `expectedRevision` below.

## 3. Change the heading

Call `project_configure` using the revision from the read:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "project_configure",
    "arguments": {
      "expectedRevision": "SOURCE_REVISION_FROM_GET",
      "patch": { "copy": { "heading": "Let's find a time" } }
    }
  }
}
```

Save the new `revision` from the result. This changes `sure.json` in the draft. The starter page displays this heading; a custom frontend must use that configuration field to display it.

For a source change instead, call `project_edit` with `expectedRevision` and a `files` map. Each supplied value replaces that whole file; omitted files stay unchanged. Use `null` only for a file you intend to delete. Keep `index.html` and a valid `sure.json`.

## 4. Commit the draft

Call `project_commit` with the latest revision:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "project_commit",
    "arguments": {
      "expectedRevision": "SOURCE_REVISION_FROM_CONFIGURE",
      "message": "Update booking page heading"
    }
  }
}
```

The response includes `committed: true` and `gitCommit`. Committing saves history; it does not publish the page.

## 5. Preview the result

Call `project_preview` with empty arguments:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": { "name": "project_preview", "arguments": {} }
}
```

Open the returned `previewUrl` and check the heading and layout. The preview captures a fixed `revision` and expires after one hour. Keep the link private. If its revision differs from the commit you intended to review, read current state and reconcile the intervening changes before publishing.

## 6. Publish the reviewed revision

When the page is ready, call `project_publish` with the source revision you reviewed:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "project_publish",
    "arguments": { "expectedRevision": "SOURCE_REVISION_YOU_PREVIEWED" }
  }
}
```

Check that `publishedRevision` equals the reviewed revision, then open the returned `publicUrl`. Existing bookings are unchanged. Accepting new bookings also requires the owner to connect and choose a booking calendar in Sure; see [Booking RPC](https://sure.day/docs/booking.md).

The browser's **Publish** button automatically commits a dirty draft. MCP requires the explicit commit step shown above.

## If the page changed while you worked

A stale revision is rejected. Call `project_get`, compare the current files with your intended edit, and retry with the new revision only after reconciling them. Do not blindly retry with a newer value.

If you need to restore a public version, read `releases` and call `project_rollback` with one of its `revision` values. This changes the published page without altering the draft, Git history, or existing bookings.

For local coding tools, use the [hosted Git workflow](https://sure.day/docs/projects.md#hosted-git). For more page settings, use the [configuration reference](https://sure.day/docs/configuration.md).


---

# Calendar MCP

Calendar MCP lets an owner connect an external agent to their Google and iCloud calendars. It reads source events, prepares exact changes, applies authorized edits, and keeps custom labels in Sure.

This uses a separate endpoint and credential from [project MCP](https://sure.day/docs/projects.md). Project tokens edit booking-page source; calendar tokens access the owner's connected calendar sources. Neither token belongs in a public booking frontend. For slots and booking management, use the [public booking API](https://sure.day/docs/booking.md).

## Connect an agent

1. Sign in to [Sure](https://app.sure.day), open **Calendars → Agent connections → Manage calendar access**.
2. Name the connection. Leave **Allow authorized edits** unchecked for read-only access, or enable it when the agent should apply authorized changes and manage labels.
3. Choose **Create connection** and copy the token into your agent's secret configuration. Sure shows it once. Tokens expire after 30 days; use **Revoke** beside a connection to revoke that token. Up to 12 active connections are allowed.
4. Configure a Streamable HTTP MCP client with `https://mcp.sure.day/mcp` and `Authorization: Bearer <CALENDAR_ACCESS_TOKEN>`.

This is an account-scoped grant, not a grant for one booking page or one calendar. Reads can include all of the owner's connected sources, including calendars hidden from their agenda; `connectionId` filters an individual read, not the token's authority. A read-only token cannot apply provider edits or change labels. Preparing a preview does not change the provider.

For a client that supports bearer credentials from environment variables:

```toml
[mcp_servers.sure]
url = "https://mcp.sure.day/mcp"
bearer_token_env_var = "SURE_MCP_TOKEN"
```

Set `SURE_MCP_TOKEN` through the client's secret environment. Keep tokens out of chat messages, source files, Git, URLs, and logs. Project credentials and signed-in browser cookies do not authorize this endpoint. The current connection uses manual bearer tokens; OAuth discovery and automatic client registration are not provided.

## Enable source edits separately

An editable MCP grant does not grant provider access by itself. The source must also allow management, and the individual item must be writable.

- **Google:** under Calendar access, choose **Allow calendar management** for the connected account and complete Google consent. This is separate from read access and booking consent. Sure also checks the calendar's writer or owner permission.
- **iCloud:** connect your Apple Account email and an app-specific password in Calendars settings, then choose **Allow calendar management** for that iCloud connection in Calendar access. Sure uses CalDAV directly; no Mac companion or awake computer is required. **Disable calendar management** removes that connection's management permission. Calendar privileges and a usable source revision still determine whether an item is writable.
- **iCalendar feeds:** remain read-only. Use their original provider connection for source edits.

## Read before acting

Initialize the MCP connection, discover the current schemas with `tools/list`, and read `sure_skill` with `name: "calendar-review"` before calendar work. Tool results place their JSON value in `result.content[0].text`; check `result.isError` first. `sure_skill` returns a JSON object containing recipe text.

The complete calendar tool names are:

| Tool | Arguments and purpose |
| --- | --- |
| `sure_connections` | Empty arguments. Lists source connections and their management permission; also reports the current time and that Reminders are unsupported. |
| `sure_read` | Required `from`, `to`, `timezone`; optional `connectionId`. Reads a positive range of at most 31 elapsed days. Instants must include an offset; timezone must be valid. |
| `sure_get` | Required `target`. Reads a current source item, provider revision, and Sure labels. |
| `sure_prepare_change` | Required `target`, `expectedRevision`, `action`, `scope`, `notifications`, `reason`; optional `patch`. Returns an expiring before/after preview without applying it. |
| `sure_apply_change` | Required `planId`, `digest`, `authority`. Applies the exact prepared preview using its creating connection. |
| `sure_audit` | Optional `planId`. Returns recent edit summaries, or one plan's full before/after and outcome. |
| `sure_labels` | Empty arguments. Reads the owner's custom taxonomy and its revision. |
| `sure_define_labels` | Required `expectedRevision`, `labels`; optional `company`. Replaces the taxonomy with a revision check. |
| `sure_label_item` | Required `target`, `labels`, `expectedRevision`, `reason`. Assigns label IDs using the item's `labelsRevision`, not its provider revision. |
| `sure_skill` | Required `name`: `calendar-review`, `calendar-denoise`, `calendar-overlaps`, `calendar-close-loops`, or `calendar-labels`. |

These tools differ from the eight `project_*` tools in the [project schema download](https://sure.day/docs/mcp-tools.json). The calendar endpoint's authenticated `tools/list` is authoritative for calendar schemas. The five recipes are also available through MCP prompts and resources at `sure://skills/NAME/SKILL.md`.

For example, read a day using synthetic dates:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sure_read",
    "arguments": {
      "from": "2026-10-06T00:00:00-07:00",
      "to": "2026-10-07T00:00:00-07:00",
      "timezone": "America/Los_Angeles"
    }
  }
}
```

The result includes `now`, `from`, `to`, `timezone`, `calendars`, `items`, `errors`, `coverage`, and `remindersSupported`. Coverage is `complete-for-requested-sources` or `incomplete`. An empty or partial result does not establish that a person is free. Source copies remain distinct; duplicates, declined invitations, and nested sessions are not automatically conflicting commitments.

Reuse each item's `target` unchanged: it contains `provider`, `connectionId`, `calendarId`, `itemId`, and sometimes `occurrenceStart`. These are source identities, not project IDs. Read an iCloud range before using `sure_get` on its returned targets. Feed targets cannot be fetched or edited through `sure_get`.

## Prepare, review, apply

Read the selected item with `sure_get`, retain its current `revision`, and prepare the exact authorized change. This synthetic example makes a nonrecurring Google hold free:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "sure_prepare_change",
    "arguments": {
      "target": {
        "provider": "google",
        "connectionId": "CONNECTION_ID_FROM_READ",
        "calendarId": "CALENDAR_ID_FROM_READ",
        "itemId": "ITEM_ID_FROM_READ"
      },
      "expectedRevision": "REVISION_FROM_GET",
      "action": "update",
      "patch": { "busy": false },
      "scope": "item",
      "notifications": "none",
      "reason": "The owner asked to make this optional hold free."
    }
  }
}
```

Replace the source identifiers and revision with returned values. `action` is `update` or `delete`. An update needs a nonempty patch; a deletion uses an empty patch. Allowed patch fields are `title` (1–1,000 characters), `description` (up to 12,000), `location` (up to 2,000), `busy` (boolean), and timed `start` and `end`. Time changes require both instants, including offsets, and a positive duration. `reason` is 1–1,000 characters.

Use `scope: "item"` for a nonrecurring event. For recurring Google events, select an `occurrence`, or read and target the `recurrence.seriesId` master before choosing `series`. Google requires an explicit notification choice of `none` or `all`. iCloud supports individual `occurrence` edits and requires `provider-default`; whole-series edits are unavailable.

The preview returns `id`, `digest`, `createdAt`, `expiresAt`, `change`, `before`, `after`, `state: "prepared"`, and `effects`, including attendees and notification intent. Review the exact source, scope, times, and effects. Previews expire after ten minutes and can only be applied using the connection that prepared them.

Call `sure_apply_change` with that `id` as `planId`, the exact `digest`, and `authority`: 10–2,000 characters describing the user's actual instruction. This text records authority; inventing a justification does not grant permission. Deletion, series changes, and notifications need user authority covering those effects. Apply rechecks the current source revision before attempting a conditional write.

| State | Meaning and next action |
| --- | --- |
| `prepared` | No provider edit has been dispatched. Review and apply before expiry if authorized. |
| `applying` | A dispatch may be in progress or its response may have been interrupted. Inspect audit and source state. |
| `applied` | The provider result was verified. `result` contains the resulting item, or `null` for deletion. |
| `conflict` | This plan failed before provider dispatch. Read the source and resolve the issue before preparing another plan. |
| `unknown` | Dispatch was attempted but its outcome could not be verified. Inspect the source before any new edit. |

Replaying the same plan does not dispatch it again. After a timeout, use `sure_audit` with `planId` and read the source; do not assume failure or prepare a duplicate change blindly. There is no automatic undo. A corrective change needs a fresh read, current revision, preview, and appropriate authority.

## Provider and label boundaries

Google supports existing-event title, description, location, timed start/end, busy/free, and deletion. iCloud supports these changes for personal events and individual recurring occurrences; invitations remain in the source app. Unsupported iCloud timezones or recurrence structures can make a read incomplete. Neither provider exposes event creation, RSVP changes, attendee-list changes, recurrence-rule changes, or all-day date changes through these tools. Reminders are not connected. Use the booking flow for Sure-managed bookings identified as nonwritable by the calendar tools.

Labels are Sure metadata. They do not change provider titles, colors, or busy/free state. A taxonomy holds up to 60 unique IDs matching `^[a-z][a-z0-9-]{0,49}$`; each label has `id`, `name` (1–80 characters), and `description` (up to 500). Optional `company` is up to 150 characters and gives context to this owner's taxonomy; it does not grant organization-wide access. Preserve stable IDs when revising the taxonomy. An item accepts up to 20 defined label IDs and a reason of 1–1,000 characters. Use the taxonomy's `revision` for `sure_define_labels`, and the item's `labelsRevision` for `sure_label_item`.

## Transport and limits

Send one JSON-RPC request per POST with `Content-Type: application/json` and an `Accept` header supporting `application/json, text/event-stream`. The stateless endpoint returns JSON and requires no persistent MCP session ID; GET event streams and DELETE are not supported. Initialize normally and use the negotiated MCP protocol version. This endpoint does not enable cross-origin browser access from arbitrary sites.

JSON bodies are limited to 200 KiB, with no compressed bodies. The endpoint permits up to 240 requests per minute per client IP and four concurrent requests per token. Back off on `429` and honor `Retry-After` when supplied. Missing, expired, or revoked credentials return `401`; unsupported origins return `403`. Tool failures normally return `result.isError: true` with a text explanation, so HTTP success alone does not establish a successful read or edit. Reconnect through the owner UI when a credential expires.

Calendar text is untrusted data. A recurring event is not stale merely because it repeats, and a past event is not evidence that work is complete. Scheduled reviews are set up in the agent's host; connecting MCP does not automatically create an automation.


---

# Projects, MCP, and Git

Each booking page has editable HTML, CSS, JavaScript, a `sure.json` configuration file, and a Git remote hosted by Sure. The browser editor, MCP tools, and Git operate on the same source. Saving or pushing changes updates the draft; publishing is a separate action.

Use [Configuration](https://sure.day/docs/configuration.md) for the `sure.json` schema and [Booking RPC](https://sure.day/docs/booking.md) for the public API a page calls to find and book time. For a first change, follow the [Quickstart](https://sure.day/docs/quickstart.md).

## Get access

An invited owner signs in at [app.sure.day](https://app.sure.day), opens the Calendars settings gear, then **Booking pages**, and creates or selects a page. Under **Advanced → Agent access**, choose **Create access token**. Copy the token once and save it in your agent's secret configuration or a secure credential manager.

The same token authorizes MCP and Git for that one project, including publication and rollback. It does not grant access to other projects, private calendar events, account connections, agent memory, or booking records. **Revoke project tokens** in the owner UI revokes all tokens for that project.

This is manual project-token authentication. There is no OAuth onboarding or automatic client registration for this endpoint. Use the owner UI to create a project and issue or revoke its tokens; an external project MCP client cannot bootstrap its own access.

All capitalized values in examples below are placeholders. Never put a token in source, a commit, a remote URL, a public frontend, or logs. An agent that needs a token should use its secret configuration rather than asking for it in a public conversation.

## MCP connection

Endpoint: `https://app.sure.day/project-mcp`

Send JSON-RPC 2.0 requests over HTTPS `POST`, with these headers:

```http
Authorization: Bearer <PROJECT_ACCESS_TOKEN>
Content-Type: application/json
```

The owner UI provides the endpoint and authorization configuration for your MCP client. Send one request object per body; batch arrays are unsupported. This endpoint returns JSON responses; it does not provide a `GET` event stream or require an `Mcp-Session-Id`. Authenticated `DELETE` returns `200` without revoking the token.

Initialize:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": { "name": "example-agent", "version": "1.0.0" }
  }
}
```

The response is:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "sure-projects", "version": "1.0.0" }
  }
}
```

Send `notifications/initialized` after initialization; notifications receive `202` with no response body. `ping` returns an empty result object. Discover the current tool schemas with:

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }
```

The response's `result.tools` array contains each tool's `name`, `description`, and `inputSchema`.

The [static tool schemas](https://sure.day/docs/mcp-tools.json) are also available without authentication. They describe the API; making project requests still requires a project token.

Call a tool by its exact underscore-separated name:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "project_get", "arguments": {} }
}
```

The token selects the project. Do not supply `projectId`; it is omitted from the advertised tool schemas. A supplied ID for another project is rejected.

### Results and revisions

A successful tool call returns its value as JSON encoded inside a text content item:

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"revision\":\"SOURCE_REVISION\",\"previewUrl\":\"PREVIEW_URL\",\"expiresAt\":0}"
      }
    ]
  }
}
```

This example shows the `project_preview` result shape; the server supplies the real revision, URL, and expiration. Check `result.isError` before parsing `result.content[0].text` as JSON.

`project_get` returns the project overview. All successful source, commit, pull, publish, and rollback tools also return this overview:

| Field | Meaning |
| --- | --- |
| `id`, `name` | Project identity and display name. |
| `files` | Map of relative file paths to their full text contents. |
| `config` | Validated configuration from `sure.json`. |
| `revision` | Current source revision: a 64-character content hash. |
| `committed` | Whether the current draft matches the committed source. |
| `gitCommit` | Git commit associated with this source, when present. A dirty draft may omit it. |
| `repository` | `{ "url": "GIT_REMOTE_URL", "branch": "main", "head": "GIT_COMMIT_SHA" }`. |
| `publishedRevision` | Published source revision, or `null` before publication. It can differ from `revision`. |
| `publicUrl` | The page's stable public URL, or `null` if hosting is unavailable. Before the first publication, the page is not available at this URL. |
| `releases` | Recorded releases, each with `revision`, `gitCommit`, and `publishedAt`. Up to 50 are retained in this list. |
| `appOrigin` | Origin of the Sure app and public booking API. |

Times such as `publishedAt` and `expiresAt` are Unix milliseconds. Other fields may be returned; clients should ignore fields they do not use.

**`expectedRevision` is the source `revision`, not the Git commit SHA.** Treat it as an opaque value returned by Sure. Read current state, make your intended change, and use the returned revision for the next operation. A stale revision fails instead of overwriting someone else's edits. Read again and reconcile the changes before retrying.

### Available tools

| Tool | Arguments | Effect |
| --- | --- | --- |
| `project_get` | `{}` | Read the current draft, Git state, and releases. |
| `project_edit` | `expectedRevision`, `files` | Save a file patch. Each value is the complete replacement text; `null` deletes that file. Omitted files are preserved. |
| `project_configure` | `expectedRevision`, `patch` | Patch `sure.json` and validate the resulting configuration. Objects merge recursively; arrays replace their previous values. |
| `project_commit` | `expectedRevision`, `message` | Commit the draft to hosted `main`. Use a nonempty message of at most 300 characters. An already committed draft is returned unchanged. |
| `project_pull` | `expectedRevision`, optional `discardLocalChanges` | Restore the draft from hosted `main`. Dirty drafts are rejected unless `discardLocalChanges` is explicitly `true`. |
| `project_preview` | `{}` | Return `{ revision, previewUrl, expiresAt }` for the exact current source. The link expires after one hour. |
| `project_publish` | `expectedRevision` | Publish the current committed source. Uncommitted drafts are rejected. |
| `project_rollback` | `revision` | Point the public page to a revision from `releases`. Does not alter the draft, Git history, or existing bookings. |

These are the complete external project tools. There is no `calendar_read`, `project_create`, `project_list`, `project_checkout`, or token-management tool on this endpoint. Configuring a page does not grant calendar connection or booking-calendar administration access.

### Edit, preview, commit, publish

1. Call `project_get` and retain its `revision` and source.
2. Make a focused change with `project_edit` or `project_configure`.
3. Call `project_preview` and inspect the result. It captures a fixed revision; later edits do not update that preview. Keep the preview URL private: possession of the link grants access until it expires.
4. Call `project_commit` with the current revision and a useful message.
5. Call `project_publish` with the current revision. Verify the returned `publishedRevision` and public URL.

For example, after reading the source, a configuration change uses:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "project_configure",
    "arguments": {
      "expectedRevision": "SOURCE_REVISION",
      "patch": { "copy": { "heading": "Let's find a time" } }
    }
  }
}
```

The owner's **Publish** button automatically commits a dirty draft before publishing. MCP publication deliberately requires the explicit `project_commit` step. A preview is not a publication and does not make unpublished scheduling rules available to bookers.

### Errors

Invalid or revoked credentials return HTTP `401`. Unsupported HTTP methods return `405`. A browser request with an unrelated `Origin` is rejected with `403`.

Malformed JSON-RPC request objects return HTTP `400` with JSON-RPC code `-32600`. Unknown JSON-RPC methods return code `-32601`. A tool failure, including a stale revision or unknown tool name, normally returns HTTP `200` with `result.isError: true`:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "isError": true,
    "content": [
      { "type": "text", "text": "This project changed. Read its current revision before editing." }
    ]
  }
}
```

Tool errors contain a human-readable message, not a structured HTTP status field. Do not interpret HTTP `200` alone as success. HTTP `413` means the request is too large; `429` means to back off and honor `Retry-After` when supplied. Malformed JSON can be rejected before JSON-RPC handling, so clients must also handle non-JSON-RPC HTTP errors.

## Hosted Git

Copy the HTTPS remote from **Advanced → Git repository**, or read `repository.url` from `project_get`. Its form is:

```text
https://app.sure.day/git/projects/PROJECT_ID.git
```

Use username **`sure`** and the project token as the password when Git prompts. HTTPS Basic authentication is supported; integrations can alternatively supply `Authorization: Bearer <PROJECT_ACCESS_TOKEN>`. Keep credentials outside the remote URL. Configure a secure Git credential helper with credentials scoped to the repository path when working on multiple Sure projects.

```sh
git -c credential.useHttpPath=true clone https://app.sure.day/git/projects/PROJECT_ID.git booking-page
cd booking-page
git config credential.useHttpPath true
git pull --ff-only origin main
# Edit the frontend files.
git add index.html style.css sure.json
git commit -m "Update booking page"
git push origin main
```

Replace `PROJECT_ID` with your project's ID. The remote accepts fast-forward updates to the existing `main` branch. Additional branches, tags, branch deletion, and forced history rewrites are rejected. Successful pushes preserve Git history and update the Sure draft as committed source; they do not publish it. Read the resulting `revision` with MCP before publishing.

If someone has committed new work to `main`, fetch and integrate it locally, then push again. For example, `git pull --rebase origin main` can replay your local commits on the latest shared history. Resolve any conflicts; do not force-push around them.

A push is also rejected while the browser or MCP has uncommitted draft edits. Preserve those edits by committing them in Sure or with `project_commit`, then pull and reconcile before pushing. `project_pull` means importing the hosted branch into the Sure draft, not pulling into your local checkout. Only use `discardLocalChanges: true` when the owner has authorized replacing that draft.

Git authentication failures return `401`; a token for another project returns `404`. Draft conflicts return `409`. Invalid pushed source or history is rejected by Git without accepting a new remote commit. Keep local work and resolve the reported problem before retrying.

### Export once to GitHub

Create an empty repository in your own GitHub account or organization, then run these commands in your local Sure clone using your own GitHub authentication:

```sh
git remote add github https://github.com/OWNER/REPOSITORY.git
git push github main
```

This exports the current branch and its history. It does not configure synchronization. `origin` remains the Sure remote; changes made only on GitHub do not update the Sure draft or public page.

## Current source and transport limits

- Keep `index.html` and a valid `sure.json` in the source. A project supports 1–100 text files, up to 250,000 bytes each and 2,000,000 bytes total.
- Supported extensions are `.html`, `.css`, `.js`, `.json`, `.md`, `.svg`, and `.txt`. Use relative ASCII paths up to 180 characters, made from letters, digits, `_`, `-`, `.`, and `/`, starting with a letter or digit. Empty, `.` and `..` path segments and hidden names are rejected.
- Paths inside `memory`, `node_modules`, `credentials`, or `secrets` directories are rejected. Keep provider credentials, tokens, private calendar links, private memory, and personal calendar data out of the frontend source.
- Git source must be UTF-8 text. Symlinks, executable file modes, submodules, and NUL bytes are rejected. Every newly introduced commit is validated: removing a forbidden file or credential in a later commit does not make the earlier unsafe commit acceptable.
- The frontend is served as source files; it has no package installation or build step. Produce supported files locally before committing them.
- Git requests and repository history are capped at 32 MiB, including expanded object data. Histories support up to 51,219 reachable objects; commit and tree objects are each limited to 256,000 bytes. Git operations have a 30-second time limit. A long history can reach these limits even when the current draft is small.
- MCP JSON request bodies are limited to 2,500 KiB. Git and MCP each allow up to 120 requests per minute per client IP; Git also limits concurrent operations. Back off on `429`.

For scheduling rules, theme fields, copy, and booking questions, continue with [Configuration](https://sure.day/docs/configuration.md). For a custom page's public scheduling calls, use [Booking RPC](https://sure.day/docs/booking.md).


---

# Configuration and runtime

A Sure project contains ordinary HTML, CSS, and JavaScript plus `sure.json`. The JSON file defines the scheduling rules and the starter frontend's presentation. It is validated when source is saved or imported. See [Projects](https://sure.day/docs/projects.md) for Git, MCP, previews, publishing, and rollback, and [Booking](https://sure.day/docs/booking.md) for the public booking API.

## A complete valid `sure.json`

This example is synthetic. Exception dates are examples, not holidays inferred by Sure. All top-level sections shown here are required; there is no implicit defaulting of missing sections.

```json
{
  "version": 1,
  "timezone": "America/New_York",
  "availability": {
    "weekly": [
      { "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "12:00" },
      { "days": [1, 3], "start": "14:00", "end": "17:00" }
    ],
    "exceptions": [
      { "date": "2030-01-01", "windows": [] },
      { "date": "2030-01-02", "windows": [{ "start": "10:00", "end": "14:00" }] }
    ]
  },
  "offer": {
    "title": "A conversation",
    "durationMinutes": 25,
    "bufferMinutes": 15,
    "minimumNoticeMinutes": 1440,
    "horizonDays": 30
  },
  "theme": {
    "background": "#f8f7f3",
    "foreground": "#203b32",
    "accent": "#214c3d",
    "fontFamily": "Manrope, system-ui, sans-serif"
  },
  "copy": {
    "heading": "Time for a conversation",
    "introduction": "Choose a time that works for you.",
    "bookingLabel": "Book a conversation"
  },
  "form": {
    "questions": [
      { "id": "topic", "label": "What would you like to discuss?", "type": "textarea", "required": true },
      { "id": "context", "label": "Anything else to know?", "type": "text", "required": false }
    ]
  }
}
```

## Schema and limits

Numeric fields below must be JSON integers, not numeric strings. Strings cannot contain NUL characters. String length limits use JavaScript string length; for most text that is the character count, while some Unicode characters occupy two code units.

| Field | Rules |
| --- | --- |
| `version` | Exactly `1`. |
| `timezone` | Valid timezone recognized by the runtime, such as `UTC` or an IANA name; 1–100 characters. |
| `availability.weekly` | Array of 0–28 windows. |
| Weekly `days` | 1–7 distinct integers per window: Monday `1` through Sunday `7`. |
| Window `start`, `end` | Zero-padded `HH:MM`, from `00:00` through `23:59`. Start must be earlier than end on the same day; `24:00` and overnight windows are not supported. |
| `availability.exceptions` | Array of 0–366 entries, with one entry per date. |
| Exception `date` | Real date in `YYYY-MM-DD` format. |
| Exception `windows` | Array of 0–8 windows using the same start/end rules. |
| `offer.title` | 1–200 characters. |
| `offer.durationMinutes` | Integer, 5–480. |
| `offer.bufferMinutes` | Integer, 0–240. |
| `offer.minimumNoticeMinutes` | Integer, 0–43,200. |
| `offer.horizonDays` | Integer, 1–365. |
| `theme.background`, `theme.foreground`, `theme.accent` | Six-digit hex colors, for example `#214c3d`. Three-digit hex, alpha, named colors, and CSS expressions are not accepted here. |
| `theme.fontFamily` | 1–100 characters. The starter uses this as a CSS font-family value; it does not download fonts. |
| `copy.heading` | 1–200 characters. |
| `copy.introduction` | 0–4,000 characters; an empty string is allowed. |
| `copy.bookingLabel` | 1–100 characters. |
| `form.questions` | Array of 0–12 questions. |
| Question `id` | Unique, 1–60 characters, matching `^[a-z][a-z0-9_-]*$`. |
| Question `label` | 1–300 characters. |
| Question `type` | Exactly `text` or `textarea`. |
| Question `required` | JSON boolean. |

Unknown properties do not add backend capabilities. Use the documented shape; the validated runtime configuration contains the supported fields. A custom frontend may add its own separate source files and choose how to present the supported configuration.

## Scheduling semantics

Weekly windows and exception dates are interpreted in `timezone`, independent of the timezone a booker uses to view dates. Multiple windows can apply to the same weekday. A matching exception **replaces every weekly window for that date**. `windows: []` closes that date; an empty `weekly` array offers only explicitly opened exception dates.

A booking must fit entirely within one window and stay on the same configured local date. Adjacent windows are not automatically merged. Candidate starts occur every 15 minutes from each window's start: a window beginning at `09:10` permits starts such as `09:10`, `09:25`, and `09:40`, subject to duration, notice, conflicts, and the requested day.

Duration is elapsed time in minutes. Actual instants are checked through daylight-saving transitions; do not generate slots by adding fixed UTC offsets to local strings. Use the public API's returned `start`, `end`, and token. The API also requires the entire meeting to fit inside the day requested by the booker.

Minimum notice is measured from the current instant. The booking's start must be before the current instant plus `horizonDays × 24 hours`; this is a rolling horizon, not a count of local calendar-date boundaries.

Buffer is a minimum gap from busy time, before or after the booking. When another Sure booking also has a buffer, the larger buffer applies, rather than adding both buffers. Buffer is a conflict rule; it does not add to the displayed meeting duration or require the buffer itself to fit inside an availability window.

The backend enforces scheduling and required form answers. Theme and copy guide the starter frontend; changing JavaScript or CSS can change its appearance, but does not bypass scheduling validation. Required question answers are trimmed nonempty strings, each at most 2,000 characters; see [Booking](https://sure.day/docs/booking.md#book-create-a-booking).

Draft configuration changes affect previews. Public booking uses the currently published configuration. Publication or rollback can invalidate unused slot tokens from another source revision. Changing configuration does not move or cancel existing bookings.

## Source file constraints

A source snapshot contains at most 100 files and 2,000,000 UTF-8 bytes in total. Each file is text, contains no NUL characters, and is at most 250,000 UTF-8 bytes. Keep nonempty `index.html` and `sure.json` at the project root.

Paths are relative, at most 180 characters, begin with an ASCII letter or digit, and otherwise use ASCII letters, digits, `_`, `.`, `/`, or `-`. Empty segments, `.` or `..` segments, hidden path segments, and directories named `memory`, `node_modules`, `credentials`, or `secrets` are not allowed. Supported extensions are `.html`, `.css`, `.js`, `.json`, `.md`, `.svg`, and `.txt`.

Keep credentials, private calendar links, private conversation or memory files, booking records, and form answers out of the repository. Source validation rejects known credential patterns; that is not a substitute for keeping secrets out of source. The repository is frontend source, not a secret store.

No package installation or build step is required for the starter. Use relative asset URLs so the same source works under a published revision or a preview URL. `sure-runtime.json` and `sure-font.ttf` are supplied by hosting at the source directory; do not create project files with those names expecting to replace the hosted responses.

## Hosted URLs and runtime JSON

Use the `publicUrl` or `previewUrl` returned by the project API rather than constructing the host yourself. Current hosting uses the separate origin `https://pages.sure.day`.

| URL shape | Behavior |
| --- | --- |
| `https://pages.sure.day/p/PROJECT_ID/` | Redirects to the currently published revision's `index.html`. Unpublished pages return `404`. |
| `.../p/PROJECT_ID/r/REVISION/index.html` | Source from that retained published release. |
| `.../p/PROJECT_ID/v/PREVIEW_CAPABILITY/index.html` | A specific draft snapshot. Preview capabilities expire after one hour; keep preview URLs private. |

`REVISION` is a source revision returned by Sure, not a Git commit SHA. A preview is fixed to the source that was previewed; saving later edits does not change an already-open preview. Request a fresh preview after editing. Historical public URLs are available while that release is retained; do not assume unlimited release retention.

From either directory, fetch the runtime beside your HTML:

```js
const response = await fetch('./sure-runtime.json', { credentials: 'omit' });
if (!response.ok) throw new Error('This page is unavailable.');
const runtime = await response.json();
```

The exact response shape is:

```js
{
  appOrigin: 'https://app.sure.day',
  projectId: 'PROJECT_ID',
  revision: 'SOURCE_REVISION',
  config: { /* complete validated sure.json configuration */ },
  preview: false
}
```

`preview` is always a boolean: `false` for a published release and `true` for a preview. This response contains no owner credentials, booking answers, management tokens, or private calendar events. `config` is the validated configuration, rather than a promise to preserve extra JSON properties or the original JSON formatting.

Send public booking requests to `runtime.appOrigin + '/booking-rpc'` with `runtime.projectId`. A custom frontend must disable booking submissions when `runtime.preview` is true. The starter disables its search and booking buttons and labels the page as a preview. Preview source does not become the active booking policy: the public API always uses the currently published page, and there is no separate preview booking endpoint.

Hosting serves `GET` and `HEAD`. Hosted code is isolated from the signed-in app's origin. Its content security policy allows scripts and styles from its own origin, including inline scripts/styles; connections can go to that origin and the Sure app. Objects, child frames, workers, and native form submissions are blocked. The page may only be framed by the Sure app. Use JavaScript booking RPC, not an HTML form action to another service. Arbitrary external script, font, analytics, or payment URLs are not enabled by default.

The supplied `sure-font.ttf` is the starter's Manrope font. `theme.fontFamily` chooses fonts already available to the page or device; it does not relax hosting restrictions.

## Optional private day in an owner preview

A public visitor does not receive private calendar data. The signed-in Booking pages editor can explicitly send a simplified view of the owner's current day to an embedded preview after the owner chooses **Show my day here**. This is an optional UI message contract, not a public calendar-read API.

First, the preview announces readiness to the containing editor:

```js
if (runtime.preview && window.parent !== window) {
  window.parent.postMessage({
    type: 'sure:ready',
    projectId: runtime.projectId,
    revision: runtime.revision,
  }, runtime.appOrigin);
}
```

The editor checks the preview origin, its exact iframe window, the project ID, and the current source revision before enabling the owner's action. Readiness alone does not send calendar data. If the source revision changed, open a fresh preview.

After the owner's explicit action, the editor can send:

```json
{
  "type": "sure:day",
  "projectId": "PROJECT_ID",
  "date": "2030-04-08",
  "events": [
    { "title": "Example appointment", "time": "9:00 AM – 9:30 AM" },
    { "title": "Example all-day event", "time": "All day" }
  ],
  "coverage": "complete"
}
```

`date` is today's date in the project's timezone. `events` contains only display titles and preformatted time labels; `time` is not an ISO timestamp or a stable format for calculations. The payload has no event IDs, provider records, credentials, descriptions, or management capabilities. `coverage` is `complete` or `incomplete`; an empty list with incomplete coverage must not be described as a guaranteed free day. The starter renders at most 200 entries.

Check the sender and render text safely:

```js
window.addEventListener('message', event => {
  if (!runtime.preview || event.origin !== runtime.appOrigin ||
      event.source !== window.parent || event.data?.type !== 'sure:day' ||
      event.data.projectId !== runtime.projectId) return;

  const day = event.data;
  if (!Array.isArray(day.events)) return;
  const list = document.querySelector('#events');
  list.replaceChildren();
  for (const item of day.events.slice(0, 200)) {
    const li = document.createElement('li');
    li.textContent = `${String(item.time ?? '')} · ${String(item.title ?? '')}`;
    list.append(li);
  }
});
```

Treat this payload as private, temporary display data. Do not commit it, embed it in a public page, or forward it to another service. The handshake does not grant the preview access to the app's authenticated APIs and does not make an anonymous public page calendar-aware.


---

# Public booking API

Use this API to find times and create, inspect, move, or cancel a booking made through a Sure booking page. Project source, Git, publication, and MCP editing are documented in [Projects](https://sure.day/docs/projects.md). Scheduling rules, forms, and the hosted frontend runtime are documented in [Configuration](https://sure.day/docs/configuration.md).

All identifiers, dates, people, and tokens below are synthetic examples or placeholders. Replace `PROJECT_ID`, `SLOT_TOKEN`, and `MANAGEMENT_TOKEN` with values returned for your page. Do not invent a slot token or build a management token yourself.

## Before a page can accept bookings

The owner must publish a booking page and choose a writable Google destination in **Calendars → Booking pages → the page → Booking calendar**. Connecting a read-only calendar or iCalendar feed is not booking consent. The owner must grant Google booking access and save a writable calendar as the destination.

The public API does not configure that destination or grant provider access. It operates only on Sure bookings. It is not an API for arbitrary calendar event writes, RSVP changes, payment collection, or a promised email delivery service.

Availability requires successful checks of the owner's connected calendars. An unavailable calendar is an error, not evidence of free time. Responses expose bookable times, not the owner's calendar events or private source records.

## HTTP contract

Send JSON to:

```text
POST https://app.sure.day/booking-rpc
Content-Type: application/json
```

```json
{
  "operation": "slots",
  "args": {
    "projectId": "PROJECT_ID",
    "date": "2030-04-08",
    "timezone": "America/New_York"
  }
}
```

Successful responses are ordinary JSON objects at the top level. There is no JSON-RPC envelope and no `result` wrapper. The five supported operations are `slots`, `book`, `get`, `move`, and `cancel`.

Public `slots` and `book` requests need no owner session or project Git/MCP token. `book` requires a slot capability returned by `slots`; `get`, `move`, and `cancel` require a booking management capability. Use `credentials: "omit"` in a browser. Never place an owner's Git/MCP credential in public frontend code.

```js
async function bookingRpc(operation, args) {
  const response = await fetch('https://app.sure.day/booking-rpc', {
    method: 'POST',
    credentials: 'omit',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ operation, args }),
  });
  const body = await response.json().catch(() => null);
  if (!response.ok) {
    throw new Error(body?.error ?? `Booking request failed (${response.status})`);
  }
  return body;
}
```

Browser CORS currently allows the Sure app origin, `https://app.sure.day`, and its configured hosted-page origin, currently `https://pages.sure.day`. Arbitrary external website origins are not enabled. `OPTIONS` is supported for approved origins, with `Content-Type` as the allowed request header. A server client can call the endpoint without an `Origin` header. Sure-hosted pages also restrict framing to the Sure app; publishing a page does not enable arbitrary third-party iframe embedding.

The request body limit is 64 KiB (65,536 bytes). The endpoint currently allows 40 requests per minute per client IP, shared across operations and preflight requests. Handle `429`, respect `Retry-After` when present, and use backoff. Treat rate limits as operational limits that may change; avoid polling every second.

## `slots`: find times for one day

Required arguments:

| Field | Type | Meaning |
| --- | --- | --- |
| `projectId` | string | The published page's project ID. |
| `date` | string | A real date in `YYYY-MM-DD` format. |
| `timezone` | string | A valid timezone name, such as `America/New_York`, defining the requested day. Maximum 100 characters. |

Optional argument:

| Field | Type | Meaning |
| --- | --- | --- |
| `manageToken` | string | Management token for a booking on this same page, when finding a replacement time. Excludes that booking's own reservation and provider event from conflicts. |

This is a one-day query, not a search starting on that date. Query another date to display another day. The complete meeting must fit within the requested day. Local daylight-saving transitions determine the actual start and end of that day.

```json
{
  "slots": [
    {
      "start": "2030-04-08T13:00:00.000Z",
      "end": "2030-04-08T13:25:00.000Z",
      "token": "SLOT_TOKEN"
    }
  ],
  "timezone": "America/New_York",
  "revision": "PUBLISHED_SOURCE_REVISION"
}
```

`start` and `end` are ISO instants in UTC. The response's `timezone` is the **page's configured timezone**, which may differ from the timezone used to request the day. Display the returned instants in the booker's preferred timezone; send the returned token unchanged. Account for repeated local clock times when displaying daylight-saving transitions.

The slot list may be empty. Slot tokens expire after ten minutes and bind the page, published source revision, and start time. They do not reserve a time. The server checks current rules and conflicts again when a booking or move is submitted. A publication or rollback to another source revision can invalidate an unused token; request fresh slots after a stale-token or conflict response.

## `book`: create a booking

```json
{
  "operation": "book",
  "args": {
    "projectId": "PROJECT_ID",
    "slot": "SLOT_TOKEN",
    "name": "Example Booker",
    "email": "booker@example.com",
    "answers": { "topic": "A first conversation" },
    "idempotencyKey": "a-unique-booking-request-001"
  }
}
```

| Field | Required | Rules |
| --- | --- | --- |
| `projectId` | yes | Same published page used for the slot query. |
| `slot` | yes | Opaque token from a returned slot; do not substitute a timestamp or the whole slot object. |
| `name` | yes | String, 1–200 characters before trimming; must remain nonempty after trimming. |
| `email` | yes | String, 1–254 characters, trimmed and lowercased; must have a non-whitespace local part, `@`, and a dotted domain. |
| `answers` | no | Object keyed by question IDs in `config.form.questions`; defaults to `{}`. Values must be strings of at most 2,000 characters. Required answers must remain nonempty after trimming. Send only configured question IDs. |
| `idempotencyKey` | yes | String, 16–100 characters. Generate one per intended booking, for example with `crypto.randomUUID()`, and retain it for retries. |

Strings must not contain NUL characters. Unknown answer IDs are not saved as form answers, but still participate in request matching; do not add or remove them during a retry.

The response contains a booking and its private management link:

```json
{
  "booking": {
    "id": "BOOKING_ID",
    "projectId": "PROJECT_ID",
    "state": "confirmed",
    "title": "A conversation",
    "start": "2030-04-08T13:00:00.000Z",
    "end": "2030-04-08T13:25:00.000Z",
    "timezone": "America/New_York"
  },
  "manageUrl": "https://app.sure.day/booking/#token=MANAGEMENT_TOKEN"
}
```

`state` can be `creating` instead of `confirmed`. A successful HTTP response with a pending state is not confirmation that the provider calendar has finished updating. Display a pending message and offer the management link.

The idempotency key is scoped to the page. A retry with the same key must describe the same chosen start, trimmed name, normalized email, and trimmed answers. Reusing the key for a different request returns `409`. A matching accepted request returns the existing booking, including its current state, even if the original slot token has since expired. This recovery still requires the page and its destination to remain available. Never use a new key merely because the first response timed out.

## Shared booking object and states

Every booking response uses the same public shape: `id`, `projectId`, `state`, `title`, `start`, `end`, and `timezone`. It does not return the booker's name, email, answers, or owner calendar records.

| State | Meaning for the frontend |
| --- | --- |
| `creating` | The request is accepted; provider creation is not yet confirmed. |
| `confirmed` | The current calendar operation completed. |
| `moving` | The new time is pending; returned `start`, `end`, and `timezone` describe the requested new time. |
| `cancelling` | Cancellation is pending. Do not claim that the time is already cancelled or free. |
| `cancelled` | Cancellation completed. |

Pending operations retain reservations while the provider outcome is uncertain. While a move is pending, both the old and requested new times remain protected. Failures can remain pending; there is no guaranteed completion time. `get` reads status rather than starting another calendar operation. The supplied management UI polls pending bookings about every 15 seconds; use similar or slower polling with backoff on errors.

## Management capability and `get`

Anyone holding the management token can read the booking's public status, move it, or cancel it. Keep the token and the complete management link out of public source, analytics, logs, and unrelated third-party requests. The link uses a URL **fragment**, `#token=...`, rather than a query parameter. Preserve that format.

Management tokens expire 730 days after the booking was created. They identify a specific booking; no owner login or separate `projectId` is required for `get`, `move`, or `cancel`.

```json
{
  "operation": "get",
  "args": { "token": "MANAGEMENT_TOKEN" }
}
```

Response: `{ "booking": { ... } }`, using the shared booking shape. `get` does not return another management link.

To read the fragment in a management frontend:

```js
const token = new URLSearchParams(location.hash.slice(1)).get('token');
// Keep token private; send it only in the JSON body of the booking requests.
```

## `move`: reschedule a confirmed booking

First call `slots` with the same page ID and `manageToken: MANAGEMENT_TOKEN` so the booking does not conflict with itself. Then submit:

```json
{
  "operation": "move",
  "args": {
    "token": "MANAGEMENT_TOKEN",
    "slot": "NEW_SLOT_TOKEN",
    "idempotencyKey": "a-unique-move-request-0001"
  }
}
```

All three arguments are required. The slot must belong to the booking's page and follow its current published rules. The idempotency key has the same 16–100 character rule as `book`; it is a new key for this intended move, retained for retries.

Response: `{ "booking": { ... } }`, normally `confirmed` or `moving`. The title stays the booking's original title. A new move requires `confirmed` state; a pending change returns `409` rather than starting another move.

Retries of the **most recent move** with the same key and chosen start return its current outcome, including when that slot token has expired. A changed start with that key returns `409`. Only the most recent move key is remembered: do not replay an older move after a later move has been accepted. Check `get` after an uncertain outcome before initiating a different move.

## `cancel`: cancel a booking

```json
{
  "operation": "cancel",
  "args": { "token": "MANAGEMENT_TOKEN" }
}
```

`token` is the only required argument. No idempotency key is needed. Repeating cancellation is safe, including when it is already pending or finished. Cancellation may also be requested while creation or a move is pending.

Response: `{ "booking": { ... } }`, with `cancelling` or `cancelled`. Keep checking a pending result using `get`. A cancelled booking cannot be moved into a new booking; start a new booking request if that is what the person wants.

## Errors and uncertain outcomes

Application errors normally use a non-2xx HTTP status and `{ "error": "Human-readable message" }`. Edge, CORS, method, or rate-limit errors may have a non-JSON body. Branch on the status and handle parse failure; do not depend on exact error wording.

| Status | Typical cause and response |
| --- | --- |
| `400` | Invalid date, input, required answer, or request body. Correct the request. |
| `403` | Invalid, expired, or wrong-page capability, or an unapproved browser origin. Obtain the appropriate capability; do not bypass origin restrictions. |
| `404` | Missing/unavailable booking page or booking, or unknown operation. |
| `405` | Unsupported method or missing/wrong JSON content type. |
| `409` | Taken or stale slot, changed published rules, reused request key with different input, pending operation, or missing writable-calendar setup. Read current state or fresh availability; owner setup issues require the owner. |
| `413` | Request body exceeds the size limit. |
| `429` | Too many requests. Respect retry timing and back off. |
| `503` | Availability or another dependency cannot currently be checked. Do not interpret this as an empty/free calendar. |

A network timeout or interrupted response does not prove that a mutation failed. For `book`, retry the same logical request with the same idempotency key. Once you have the management token, use `get` to resolve uncertainty. For `move`, preserve its key and chosen start; for `cancel`, reuse the same management token. Never label pending work confirmed, and never create a second booking merely to recover a missing response.


# Project MCP tool schemas

```json
{
  "tools": [
    {
      "name": "project_get",
      "description": "Read canonical source, configuration, current revision, repository, and releases. Never includes credentials or private memory.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      }
    },
    {
      "name": "project_edit",
      "description": "Change ordinary frontend source files using an optimistic revision. A file value of null deletes it. sure.json contains scheduling and theme configuration.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string"
          },
          "files": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "required": [
          "expectedRevision",
          "files"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "project_configure",
      "description": "Patch scheduling rules, theme, copy, or questions in the canonical sure.json source. Values are validated before saving.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string"
          },
          "patch": {
            "type": "object"
          }
        },
        "required": [
          "expectedRevision",
          "patch"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "project_pull",
      "description": "Restore the draft from this project’s Sure-hosted Git main branch. Rejects uncommitted draft edits unless discardLocalChanges is explicitly authorized; previous revisions are retained.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string"
          },
          "discardLocalChanges": {
            "type": "boolean"
          }
        },
        "required": [
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "project_commit",
      "description": "Commit the current source to this project’s Sure-hosted Git remote. Git pushes and MCP edits share this source and revision checks prevent overwriting concurrent work.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "expectedRevision",
          "message"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "project_preview",
      "description": "Create a short-lived preview URL for the exact current source revision. No public release changes.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": [],
        "additionalProperties": false
      }
    },
    {
      "name": "project_publish",
      "description": "Publish the exact current, committed source revision to the project public URL.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "expectedRevision": {
            "type": "string"
          }
        },
        "required": [
          "expectedRevision"
        ],
        "additionalProperties": false
      }
    },
    {
      "name": "project_rollback",
      "description": "Restore a previously published frontend/configuration release. This never changes or cancels bookings.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "string"
          }
        },
        "required": [
          "revision"
        ],
        "additionalProperties": false
      }
    }
  ]
}
```