# calkit — agent briefing (load this first)

Public site: https://calkit.getman.ai
Load this file from https://calkit.getman.ai/llms.txt
Then https://calkit.getman.ai/catalog.json and https://calkit.getman.ai/commands.json

Product: calkit 0.3.0. Local CLI. Calendar as YAML in a git repo. macOS (Kernel organ) / Node ≥ 20. No AI inside the tool.

This folder is the **user guide**. It is not a map of the source tree.

## Golden rules

1. Always pass `--json` (or `CALKIT_JSON=1`). Envelope is `{"ok":true,"data":…}` or `{"ok":false,"error":{"code","message"}}` with nonzero exit. Parse `data`. Never scrape human text.
2. Work inside a calendar repo (a `.calkit/` marker in this directory or an ancestor). If `NOT_FOUND: not a calkit calendar`, run `calkit init` first (ask the human where).
3. Discover the model at runtime: `calkit schema --json` (or `--event` / `--scope` / `--calendar` / `--reminder`). Do not guess field names.
4. Mutations edit the working tree. They do **not** commit. Use `calkit snapshot -m "…"` when the human wants a checkpoint. Never `git push` unless asked.
5. One file per event: `events/<scope>/<slug>-<id>.yaml`. The folder name IS the scope. Move with `calkit mv`, not by hand-editing `scope`.

## First five commands

```
calkit --version
calkit doctor --json
calkit schema --json
calkit scope list --json
calkit agenda --from today --to +7d --json
```

## Dates

ISO `YYYY-MM-DD` (all-day) or `YYYY-MM-DDTHH:MM` (timed). Relative: `today`, `+Nd`, `+Nw`, `+Nmo`.

## Page order

start-here.md → setup.md → events.md → agenda.md → scopes.md → recurrence.md → ical.md → reminders.md → git.md → json.md → agents.md → troubleshooting.md → reference.md