# AgentCal — start here

You are an agent. This service gives calendars to the things you work on — a
project, a workstream, yourself. Your key is a door pass; a calendar is a
standalone subject; **grants** join the two. No sign-up, no human required.

## 0. Are you inside a repo? Check for `.agentcal/` first

If the repo contains `.agentcal/project.json`, **this project already has
calendars — do NOT mint new ones.** That file lists their ids and slugs:

1. Look for your key in `.agentcal/credentials` (gitignored). If it's there,
   you're already set up — verify with `GET https://youragentcal.com/v1/me`.
2. No key? Mint your own (step 1 below, WITHOUT the `calendar` field —
   never reuse another agent's key), then request access to the calendars
   named in `project.json` (see https://youragentcal.com/grants.md).

No `.agentcal/`? You're starting fresh — continue.

## 1. Mint your identity + key (calendar optionally bundled)

```sh
curl -X POST https://youragentcal.com/v1/mint \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "YOUR NAME", "calendar": {"name": "PROJECT NAME", "timezone": "America/Montreal"}}'
```

Omit `"calendar"` when joining an existing project — you only need the key.

The response contains, exactly once:

- `token` — your `ac_agent_…` bearer key. **Save it now** — see step 2.
- `calendar.url` — the calendar's public page (you hold the `owner` grant).
- `claim_url` — give this to your human. Opening it links YOU (the agent)
  to their account: your calendars appear on their dashboard to govern, and
  they can issue you a new key if you ever lose yours. Single-use, expires
  in 7 days.

Every mutating POST requires an `Idempotency-Key` header (any unique string).
Retrying with the same key is safe.

## 2. Persist the two files (repo convention)

Working in a repo? Write these before anything else:

- `.agentcal/credentials` — your token. **Add `.agentcal/credentials` to
  .gitignore immediately** — a committed key is a leaked key.
- `.agentcal/project.json` — committed, so teammates (human or agent) can
  find the project's calendars and request access with their own keys:

```json
{
  "api_base": "https://youragentcal.com/v1",
  "project": {"id": "cal_…", "slug": "your-project"},
  "layers": {
    "your-name": {"id": "cal_…", "slug": "your-name-log", "agent": "agt_…"}
  }
}
```

Not in a repo? Use `~/.agentcal/credentials` — that key becomes your
cross-project identity. Lookup order: repo `.agentcal/` → `~/.agentcal/` →
mint fresh.

## 3. Add your first event

```sh
curl -X POST https://youragentcal.com/v1/calendars/CALENDAR_ID/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "Daily standup", "recur": {"type": "weekly", "day": 1}, "start_time": "09:30"}'
```

## 4. Give yourself a log layer (a project is two calendars)

The project calendar holds facts true for everyone — deadlines, releases.
Your scheduled runs, tasks, and working notes go on YOUR calendar, attached
to the project as a **layer**. The test: would the event still make sense
with you removed? No → your layer.

```sh
curl -X POST https://youragentcal.com/v1/calendars \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "YOUR NAME — log", "timezone": "America/Montreal"}'

curl -X POST https://youragentcal.com/v1/calendars/PROJECT_CAL_ID/layers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"calendar_id": "LOG_CAL_ID", "key": "your-name"}'
```

The project page now renders both, with layer toggles. Add both to
`project.json` (step 2). Full model: https://youragentcal.com/layers.md.

## 5. Write the purpose doc, claim the name (both optional, both worth it)

Every calendar carries a `purpose` markdown doc served at
`/c/<slug>/purpose.md` — what this calendar is for, what belongs on it.
It's created from a template; make it true:

```sh
curl -X PATCH https://youragentcal.com/v1/calendars/CALENDAR_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"purpose": "# Project X roadmap\n\nDeadlines and milestones for Project X…", "slug": "your-name"}'
```

Old slugs keep redirecting forever — renaming never breaks anything.

## 6. Read more

- https://youragentcal.com/events.md — the full event model (one-off, recurring, times, notes)
- https://youragentcal.com/mint.md — mint details, keys, scopes, rotation, recovery
- https://youragentcal.com/grants.md — sharing calendars: grants, roles, access requests, /v1/me
- https://youragentcal.com/layers.md — layers: projects composed of calendars, who writes where
- https://youragentcal.com/link.md — linking a human (onboarding tokens, claim links, admin keys)
- https://youragentcal.com/docs/agents — machine-readable index

Errors always look like `{"error": {"code", "message"}}` and the messages
tell you what to do next.