From 130ea0fbe9142874c4704117b1cd9df5fe0b20de Mon Sep 17 00:00:00 2001
From: Rob Weaver <rob@accuweaver.com>
Date: Sat, 16 May 2026 16:32:57 -0600
Subject: [PATCH] Add Go rewrite of work-cal-sync alongside Python version

Implements the improve-setup spec: a Go reimplementation of the calendar sync tool that ships as a code-signed .app bundle plus CLI binary, with subcommands for setup, install, uninstall, and status. The Python version is preserved unchanged and the two coexist via different launchd labels.

- cmd/work-cal-sync: subcommand dispatch and bundle routing for EventKit access

- cmd/ekprobe: diagnostic helper for EventKit auth and calendar listing

- pkg/eventkit: cgo bridge to EventKit.framework with Info.plist for TCC

- internal/sync: config, caldav, ical, keyring, plist, wizard, diff, managed, sync engine

- Makefile: build/install targets for both the CLI and the .app bundle, with auto-detected codesign identity

- docs: architecture, user guide, troubleshooting

- Spec at .kiro/specs/improve-setup/
---
 .gitignore                                |  19 +
 .kiro/specs/improve-setup/design.md       | 135 ++++
 .kiro/specs/improve-setup/requirements.md | 197 +++++
 .kiro/specs/improve-setup/tasks.md        | 159 ++++
 Makefile                                  |  98 +++
 README.md                                 | 222 +++++-
 cmd/ekprobe/main.go                       | 111 +++
 cmd/ekprobe/probe.m                       |  92 +++
 cmd/work-cal-sync/doc.go                  |   7 +
 cmd/work-cal-sync/main.go                 | 886 ++++++++++++++++++++++
 docs/architecture.md                      | 251 ++++++
 docs/troubleshooting.md                   | 158 ++++
 docs/user-guide.md                        | 319 ++++++++
 go.mod                                    |  17 +
 go.sum                                    |  18 +
 internal/sync/caldav.go                   | 415 ++++++++++
 internal/sync/caldav_test.go              | 231 ++++++
 internal/sync/config.go                   | 124 +++
 internal/sync/config_test.go              | 118 +++
 internal/sync/diff.go                     |  98 +++
 internal/sync/diff_test.go                | 414 ++++++++++
 internal/sync/doc.go                      |   9 +
 internal/sync/ical.go                     | 227 ++++++
 internal/sync/ical_test.go                | 263 +++++++
 internal/sync/keyring.go                  |  54 ++
 internal/sync/keyring_test.go             | 111 +++
 internal/sync/managed.go                  |  96 +++
 internal/sync/managed_test.go             | 266 +++++++
 internal/sync/plist.go                    | 265 +++++++
 internal/sync/plist_test.go               | 428 +++++++++++
 internal/sync/prompt.go                   | 217 ++++++
 internal/sync/prompt_test.go              | 335 ++++++++
 internal/sync/sync.go                     | 347 +++++++++
 internal/sync/sync_test.go                | 704 +++++++++++++++++
 internal/sync/url.go                      |  54 ++
 internal/sync/url_test.go                 |  41 +
 internal/sync/wizard.go                   | 370 +++++++++
 internal/sync/wizard_test.go              | 369 +++++++++
 pkg/eventkit/Info.plist                   |  28 +
 pkg/eventkit/doc.go                       |   7 +
 pkg/eventkit/eventkit.go                  | 259 +++++++
 pkg/eventkit/eventkit.h                   | 125 +++
 pkg/eventkit/eventkit.m                   | 362 +++++++++
 pkg/eventkit/eventkit_test.go             |  51 ++
 44 files changed, 9036 insertions(+), 41 deletions(-)
 create mode 100644 .gitignore
 create mode 100644 .kiro/specs/improve-setup/design.md
 create mode 100644 .kiro/specs/improve-setup/requirements.md
 create mode 100644 .kiro/specs/improve-setup/tasks.md
 create mode 100644 Makefile
 create mode 100644 cmd/ekprobe/main.go
 create mode 100644 cmd/ekprobe/probe.m
 create mode 100644 cmd/work-cal-sync/doc.go
 create mode 100644 cmd/work-cal-sync/main.go
 create mode 100644 docs/architecture.md
 create mode 100644 docs/troubleshooting.md
 create mode 100644 docs/user-guide.md
 create mode 100644 go.mod
 create mode 100644 go.sum
 create mode 100644 internal/sync/caldav.go
 create mode 100644 internal/sync/caldav_test.go
 create mode 100644 internal/sync/config.go
 create mode 100644 internal/sync/config_test.go
 create mode 100644 internal/sync/diff.go
 create mode 100644 internal/sync/diff_test.go
 create mode 100644 internal/sync/doc.go
 create mode 100644 internal/sync/ical.go
 create mode 100644 internal/sync/ical_test.go
 create mode 100644 internal/sync/keyring.go
 create mode 100644 internal/sync/keyring_test.go
 create mode 100644 internal/sync/managed.go
 create mode 100644 internal/sync/managed_test.go
 create mode 100644 internal/sync/plist.go
 create mode 100644 internal/sync/plist_test.go
 create mode 100644 internal/sync/prompt.go
 create mode 100644 internal/sync/prompt_test.go
 create mode 100644 internal/sync/sync.go
 create mode 100644 internal/sync/sync_test.go
 create mode 100644 internal/sync/url.go
 create mode 100644 internal/sync/url_test.go
 create mode 100644 internal/sync/wizard.go
 create mode 100644 internal/sync/wizard_test.go
 create mode 100644 pkg/eventkit/Info.plist
 create mode 100644 pkg/eventkit/doc.go
 create mode 100644 pkg/eventkit/eventkit.go
 create mode 100644 pkg/eventkit/eventkit.h
 create mode 100644 pkg/eventkit/eventkit.m
 create mode 100644 pkg/eventkit/eventkit_test.go

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..8704868
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,19 @@
+# Compiled binaries (repo-root only, not nested paths)
+/work-cal-sync
+/meeting-alerter
+/ekprobe
+
+# macOS .app bundles produced by the Makefile
+/work-cal-sync.app/
+/meeting-alerter.app/
+
+# Go build artifacts
+*.exe
+*.test
+*.out
+
+# Mypy cache
+.mypy_cache/
+
+# Editor / OS noise
+.DS_Store
diff --git a/.kiro/specs/improve-setup/design.md b/.kiro/specs/improve-setup/design.md
new file mode 100644
index 0000000..0b03f34
--- /dev/null
+++ b/.kiro/specs/improve-setup/design.md
@@ -0,0 +1,135 @@
+# Design: Rewrite in Go with Improved Setup
+
+## Overview
+A single Go binary with subcommands that replaces the Python+bash setup. The Python implementation stays in the repo as an alternative.
+
+## Project layout
+
+```
+work-cal-sync/
+├── cmd/work-cal-sync/
+│   └── main.go              # Entry point: subcommand dispatch
+├── internal/
+│   ├── eventkit/            # cgo bindings to EventKit.framework
+│   │   ├── eventkit.go
+│   │   └── eventkit.m
+│   └── sync/                # Everything else: config, caldav, wizard, plist, sync logic
+│       ├── config.go
+│       ├── caldav.go
+│       ├── wizard.go
+│       ├── plist.go
+│       └── sync.go
+├── go.mod
+├── go.sum
+├── Makefile
+├── README.md
+├── work-cal-sync.py         # Preserved Python implementation
+├── setup.sh                 # Preserved Python installer
+└── tel.dead.work-cal-sync.plist  # Preserved Python plist template
+```
+
+Two internal packages: `eventkit` (isolated because of cgo) and `sync` (everything else). If `sync` grows large enough to warrant splitting later, that's easy.
+
+## Key design decisions
+
+### Single binary, subcommands via standard library `flag` or a small library
+- For a handful of subcommands, `flag.NewFlagSet` per subcommand is enough
+- Avoid pulling in `cobra`/`urfave/cli` unless the surface grows
+- Root `main.go` dispatches on `os.Args[1]` to the appropriate handler
+
+### cgo only for EventKit
+- EventKit has no Go binding and no REST surface, so cgo is required
+- Thin ObjC bridge in `eventkit.m` with extern "C" functions
+- Go side defines structs and calls bridge functions
+- Keychain uses `github.com/zalando/go-keyring` instead of custom cgo
+
+### CalDAV via go-webdav + go-ical
+- `github.com/emersion/go-webdav` for CalDAV protocol
+- `github.com/emersion/go-ical` for VCALENDAR/VEVENT generation and parsing
+- Custom properties (`X-WORK-CAL-ID`, `X-WORK-CAL-MODIFIED`) attached to VEVENT for tracking
+
+### Config
+- Path: `~/.config/work-cal-sync/config.json`
+- Permissions: directory `0700`, file `0600`
+- Format:
+  ```go
+  type Config struct {
+      WorkCalendarID    string `json:"work_calendar_id"`
+      WorkCalendarName  string `json:"work_calendar_name"`
+      CalDAVServer      string `json:"caldav_server"`
+      CalDAVUsername    string `json:"caldav_username"`
+      CalDAVCalendarURL string `json:"caldav_calendar_url"`
+      DaysBack          int    `json:"days_back"`
+      DaysForward       int    `json:"days_forward"`
+  }
+  ```
+  Stores both the calendar ID (stable) and the name (for display).
+
+### HTTPS validation
+- A small helper checks the parsed URL: scheme must be `https`, OR host must be `localhost`/`127.0.0.1`/`::1`
+- No `--allow-http` flag; loopback exception covers the legitimate case
+
+### launchd plist
+- Generated from a Go string template at install time
+- Plist label: `tel.dead.work-cal-sync.go` (different from Python version's `tel.dead.work-cal-sync` so they can coexist during migration)
+- Path: `~/Library/LaunchAgents/tel.dead.work-cal-sync.go.plist`
+- `RunAtLoad=false`, `StartInterval=900`, `KeepAlive=false`
+- Log to `~/Library/Logs/work-cal-sync.log`
+
+### Status command
+- Reads config (no password)
+- Runs `launchctl list tel.dead.work-cal-sync.go` to check job status
+- Tails last ~20 lines of the log file
+
+## Subcommand dispatch (sketch)
+
+```go
+func main() {
+    if len(os.Args) < 2 {
+        runSync()
+        return
+    }
+    switch os.Args[1] {
+    case "setup":     runSetup(os.Args[2:])
+    case "install":   runInstall(os.Args[2:])
+    case "uninstall": runUninstall(os.Args[2:])
+    case "status":    runStatus(os.Args[2:])
+    case "-h", "--help", "help":
+        printUsage()
+    default:
+        // Treat unknown args as flags to the sync command
+        runSync()
+    }
+}
+```
+
+## Dependencies
+
+| Dependency | Purpose |
+|-----------|---------|
+| `github.com/emersion/go-webdav` | CalDAV client |
+| `github.com/emersion/go-ical` | iCalendar parsing/generation |
+| `github.com/zalando/go-keyring` | macOS Keychain |
+| Standard library + cgo | EventKit bridge |
+
+## Build
+
+- `go build ./cmd/work-cal-sync` produces the binary
+- `go install github.com/<owner>/work-cal-sync/cmd/work-cal-sync@latest` for users
+- Makefile targets: `build`, `install` (local copy to `~/bin/`), `clean`
+- Min Go version: 1.22
+- Requires Xcode Command Line Tools for cgo
+
+## Coexistence with Python version
+
+- Different launchd label means both can be installed without conflict
+- README will warn against running both pointed at the same CalDAV calendar (they'd fight over the same events)
+- A user migrating from Python would: stop the Python launchd job, run `work-cal-sync setup`, run `work-cal-sync install`
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| EventKit cgo bridge complexity | Keep ObjC layer to data extraction only; all logic in Go |
+| `go-webdav` edge cases vs Python `caldav` | Test against Radicale; document supported servers |
+| Users accidentally run both implementations | Different plist labels + README warning |
diff --git a/.kiro/specs/improve-setup/requirements.md b/.kiro/specs/improve-setup/requirements.md
new file mode 100644
index 0000000..30d67f7
--- /dev/null
+++ b/.kiro/specs/improve-setup/requirements.md
@@ -0,0 +1,197 @@
+# Requirements Document
+
+## Introduction
+
+`work-cal-sync` copies work Exchange/O365 calendar events from macOS Calendar.app to a self-hosted CalDAV server. This document captures the as-built Go rewrite that runs alongside the original Python implementation. The original Python script (`work-cal-sync.py`) and bash installer (`setup.sh`) are preserved in the repository for users who prefer not to install Go, but the Go implementation is the recommended path.
+
+A separate spec (`meeting-alerter`) covers an unrelated tool that shares the EventKit bridge but is otherwise independent. Meeting-alerter is **out of scope** for this document; only the calendar sync tool and its diagnostic helper are described here.
+
+## Glossary
+
+- **CalDAV**: RFC 4791 calendar protocol used to talk to self-hosted servers like Radicale, Nextcloud, and Baikal.
+- **EventKit**: macOS framework for reading and writing local calendar data, including calendars synced from Exchange/O365 accounts configured in **System Settings → Internet Accounts**.
+- **launchd**: macOS service manager. A LaunchAgent plist runs the sync binary on a 15-minute schedule.
+- **TCC**: Apple's Transparency, Consent, and Control privacy subsystem. Calendar access permissions are recorded against a process's **bundle id**, not its binary path, which is why this tool ships as a `.app` bundle rather than a bare binary.
+- **`.app` bundle**: macOS application directory layout (`Foo.app/Contents/Info.plist`, `Foo.app/Contents/MacOS/Foo`). Required so TCC honors the Calendar permission grant.
+- **Loopback host**: `localhost`, `127.0.0.1`, or `::1`. The wizard allows plain HTTP for these only.
+- **Managed event**: A CalDAV event created by this tool, identified by the custom iCalendar properties `X-WORK-CAL-ID` and `X-WORK-CAL-MODIFIED`.
+
+## Architecture (as built)
+
+Go module: `github.com/djdead/work-cal-sync`
+
+```text
+cmd/
+  work-cal-sync/         main binary: sync, setup, install, uninstall, status,
+                         plus hidden bundle-routing subcommands
+  ekprobe/               diagnostic helper for verifying EventKit access
+pkg/
+  eventkit/              cgo bridge to EventKit.framework + Info.plist used
+                         by the .app bundle
+internal/
+  sync/                  config, caldav, ical, keyring, plist, prompt, url,
+                         wizard, diff, managed, sync engine
+work-cal-sync.app/       built .app bundle (gitignored, produced by `make app`)
+work-cal-sync.py         preserved Python implementation
+setup.sh                 preserved Python installer
+tel.dead.work-cal-sync.plist   preserved Python launchd template
+```
+
+The Python implementation continues to work. The Go implementation uses a different launchd label (`tel.dead.work-cal-sync.go`) so both can be installed without conflict during migration, though they should not point at the same CalDAV calendar.
+
+## Requirements
+
+### REQ-1: Single binary with subcommands
+
+- **What**: One Go binary at `cmd/work-cal-sync/` that handles `sync`, `setup`, `install`, `uninstall`, and `status` via subcommands.
+- **Why**: Simpler to build, distribute, and document than multiple binaries for a tool of this size.
+- **Acceptance criteria**:
+  - Default invocation (no args) runs sync; this is the path launchd takes.
+  - `setup`, `install`, `uninstall`, `status` are public subcommands.
+  - `help`, `-h`, `--help` print usage to stdout and exit 0.
+  - Unknown args are passed through to the sync command rather than rejected (forward-compat for sync flags).
+
+### REQ-2: Bundle-routing subcommands
+
+- **What**: Hidden subcommands (`request-access`, `list-calendars-internal`, `fetch-events-internal`) exist so the main binary can re-invoke itself inside the `.app` bundle to perform EventKit work, then read results back through a temp file.
+- **Why**: macOS attaches Calendar (TCC) permissions to a bundle id, but only honors them when the process is launched via Launch Services (`open -a Foo.app`). A direct shell exec of the binary inside the bundle is attributed to the shell, not the bundle, and silently returns no calendars. Routing through `open -W -n -a … --args …` makes Launch Services attribute the work to the bundle.
+- **Acceptance criteria**:
+  - `request-access` calls `eventkit.RequestAccess` and exits 0/1/2 (granted/error/denied).
+  - `list-calendars-internal <result-path>` writes the calendar list as JSON.
+  - `fetch-events-internal <result-path> <calendar-id> <start-unix> <end-unix>` writes events as JSON.
+  - These subcommands are not advertised in `help` output.
+  - The main binary's `setup` and default `sync` paths use bundle-routed helpers (`listCalendarsViaBundle`, `fetchEventsViaBundle`) when running outside the bundle.
+
+### REQ-3: `.app` bundle distribution
+
+- **What**: The Go binary is shipped as a code-signed macOS `.app` bundle at `~/Applications/work-cal-sync.app`.
+- **Why**: TCC will not grant Calendar access to a bare binary, and a stable code-signing identity prevents TCC from treating each rebuild as a new app and re-prompting.
+- **Acceptance criteria**:
+  - `make app` produces `work-cal-sync.app/` with `Contents/MacOS/work-cal-sync`, `Contents/Info.plist` (with `NSCalendarsFullAccessUsageDescription`), and `Contents/PkgInfo`.
+  - The bundle is signed with `codesign --identifier tel.dead.work-cal-sync` using a developer identity (defaults to the first `Apple Development:` identity in the keychain; falls back to ad-hoc `-` if none).
+  - `make install-app` copies the bundle to `~/Applications/work-cal-sync.app`.
+  - Bundle-routing helpers in the main binary look for the bundle in `~/Applications` first, then `/Applications`, and fail with a clear "run `make install-app`" message if neither exists.
+
+### REQ-4: Sync logic
+
+- **What**: Sync work events to a CalDAV server using rsync-delete semantics.
+- **Why**: Keep the CalDAV calendar an exact mirror of the work calendar inside the configured time window.
+- **Acceptance criteria**:
+  - Reads work events via the EventKit bridge (`pkg/eventkit`).
+  - Writes to CalDAV via `github.com/emersion/go-webdav` and `github.com/emersion/go-ical`.
+  - Each managed VEVENT carries `X-WORK-CAL-ID` (EventKit external id) and `X-WORK-CAL-MODIFIED` (Unix seconds).
+  - Diff produces three sets: create (in work, not in CalDAV), update (in both, work modified later), delete (in CalDAV, not in work).
+  - Sync window is `[now - DaysBack, now + DaysForward]` from config.
+  - Logs counts and per-event actions via `log/slog`.
+
+### REQ-5: Setup subcommand
+
+- **What**: `work-cal-sync setup` runs the interactive configuration wizard.
+- **Why**: Co-locating with the sync binary lets the wizard reuse the same EventKit and CalDAV code paths.
+- **Acceptance criteria**:
+  - Lists Exchange/O365 calendars via the bundle-routed EventKit helper.
+  - Prompts for CalDAV server URL, username, password (password via terminal echo-off).
+  - Rejects URLs that aren't `https://` unless the host is loopback (`localhost`, `127.0.0.1`, `::1`).
+  - Lists calendars from the CalDAV server for selection.
+  - Prompts for `DaysBack` (default 7) and `DaysForward` (default 90).
+  - Saves config to `~/.config/work-cal-sync/config.json` with directory `0700` and file `0600`.
+  - Saves password to macOS Keychain via `github.com/zalando/go-keyring` (service `work-cal-sync`, account = CalDAV username).
+  - When config already exists, current values are shown as defaults and Enter keeps them.
+
+### REQ-6: Install subcommand
+
+- **What**: `work-cal-sync install` installs the launchd plist and loads the job.
+- **Why**: Users shouldn't write plists by hand or remember `launchctl` syntax.
+- **Acceptance criteria**:
+  - Resolves the running binary path with `os.Executable` and `filepath.EvalSymlinks`.
+  - If no config exists, runs `setup` first.
+  - Generates the plist from an in-code Go template (no external files); fields: `Label`, `BinaryPath`, `LogPath`.
+  - Plist label: `tel.dead.work-cal-sync.go` (distinct from Python version).
+  - Plist location: `~/Library/LaunchAgents/tel.dead.work-cal-sync.go.plist`.
+  - Plist values: `StartInterval=900`, `RunAtLoad=false`, `KeepAlive=false`, stdout and stderr redirected to `~/Library/Logs/work-cal-sync.log`.
+  - Atomic write: temp file in same directory, rename over destination.
+  - Idempotent: unloads any existing job before loading, so re-running is safe.
+
+### REQ-7: Uninstall subcommand
+
+- **What**: `work-cal-sync uninstall` removes the launchd plist and config.
+- **Why**: Users shouldn't have to remember multiple manual cleanup commands.
+- **Acceptance criteria**:
+  - Lists what will be removed and asks for y/n confirmation (default `no`).
+  - Unloads the launchd job (idempotent: succeeds even if not loaded).
+  - Removes the plist file (idempotent on missing file).
+  - Removes the entire `~/.config/work-cal-sync/` directory.
+  - Does **not** remove the binary (user may have installed via `go install`, Homebrew, copy, etc.).
+  - Does **not** delete the Keychain entry; instead prints the `security delete-generic-password -s work-cal-sync -a <user>` command.
+  - Failures during removal are logged but don't abort the rest of the uninstall.
+
+### REQ-8: Status subcommand
+
+- **What**: `work-cal-sync status` shows current state.
+- **Why**: Quick way to verify configuration and recent activity without opening multiple files.
+- **Acceptance criteria**:
+  - Prints config path and pretty-printed JSON contents (no password — `Config` has no password field).
+  - Prints launchd state by running `launchctl list <label>`; "not loaded" is reported as state, not as an error.
+  - Prints the last 20 lines of `~/Library/Logs/work-cal-sync.log`; missing file reports "not found", empty file reports "empty".
+  - Does not exit non-zero on partial failures; the goal is to dump whatever state can be observed.
+
+### REQ-9: Logging and verbosity
+
+- **What**: All subcommands emit `log/slog` text to stderr with consistent format.
+- **Why**: launchd captures stderr to the log file; consistent format makes the log readable.
+- **Acceptance criteria**:
+  - Default level: `Debug` when stderr is a terminal (interactive runs), `Info` otherwise (launchd runs).
+  - `-v` / `--verbose` forces `Debug`. `-q` / `--quiet` forces `Info`.
+  - Verbosity flags are accepted by every subcommand and stripped before further parsing.
+  - TTY detection uses `golang.org/x/term`.
+
+### REQ-10: Keychain integration
+
+- **What**: Store and retrieve the CalDAV password via the macOS Keychain.
+- **Why**: Avoid plaintext credentials on disk and avoid hand-written cgo against `Security.framework`.
+- **Acceptance criteria**:
+  - Uses `github.com/zalando/go-keyring`.
+  - Service: `work-cal-sync`. Account: the CalDAV username from config.
+  - `KeyringStore.Get`, `Set`, `Delete` wrap the library so call sites are testable.
+  - Setup writes/updates the password; sync reads it; uninstall does not touch it (REQ-7).
+
+### REQ-11: Build and distribution
+
+- **What**: A Makefile drives the build, bundle, codesign, and install workflow.
+- **Why**: A single command (`make install-app`) gets the user from clone to working install.
+- **Acceptance criteria**:
+  - `make build` produces `./work-cal-sync` (a bare binary, useful for `go vet`/tests).
+  - `make install` copies the binary to `~/bin/work-cal-sync`.
+  - `make app` produces a code-signed `work-cal-sync.app/` bundle.
+  - `make install-app` installs the bundle to `~/Applications/`.
+  - `make clean` removes both binaries and both bundles.
+  - `CODESIGN_IDENTITY` env/var override is supported, with auto-detection and ad-hoc fallback.
+  - `go install github.com/djdead/work-cal-sync/cmd/work-cal-sync@latest` works for users who only want the bare binary; they will still need `make install-app` from a clone for full Calendar access.
+
+### REQ-12: Diagnostic helper
+
+- **What**: `cmd/ekprobe` is a small standalone binary that exercises the EventKit bridge.
+- **Why**: TCC issues are common during install; a focused tool makes diagnosing access problems quicker than poking at the main binary.
+- **Acceptance criteria**:
+  - Lives at `cmd/ekprobe/` with its own `main.go` and ObjC bridge (`probe.m`).
+  - Reports authorization status, requests access, and lists Exchange/O365 calendars.
+  - Documented in `docs/troubleshooting.md`.
+
+### REQ-13: Preserve Python implementation
+
+- **What**: Keep the Python script and bash installer in the repo for users who prefer them.
+- **Why**: This is a fork; not every user wants Go. Both implementations should remain functional.
+- **Acceptance criteria**:
+  - `work-cal-sync.py`, `setup.sh`, and `tel.dead.work-cal-sync.plist` remain in the repo root.
+  - README describes both options and recommends the Go version as the default.
+  - Different launchd labels (`tel.dead.work-cal-sync` Python, `tel.dead.work-cal-sync.go` Go) so both can be installed simultaneously, with a documented warning not to point both at the same CalDAV calendar.
+
+## Non-requirements (out of scope)
+
+- The `meeting-alerter` tool (`cmd/meeting-alerter/`). Covered by a separate spec.
+- Cross-platform support. macOS-only due to EventKit.
+- GUI or menu bar app.
+- Two-way sync (CalDAV → work).
+- Attendee/RSVP data.
+- Recurring event exceptions beyond what `go-ical` handles natively.
+- Backward-compatible config format with the Python version. The Go version starts fresh and adds `work_calendar_id` for stable identification across renames.
diff --git a/.kiro/specs/improve-setup/tasks.md b/.kiro/specs/improve-setup/tasks.md
new file mode 100644
index 0000000..f7af25b
--- /dev/null
+++ b/.kiro/specs/improve-setup/tasks.md
@@ -0,0 +1,159 @@
+# Implementation Plan: Rewrite in Go with Improved Setup
+
+## Overview
+
+This plan reflects the as-built Go implementation that ships alongside the original Python `work-cal-sync.py`. It does **not** cover `cmd/meeting-alerter`, which is tracked in a separate spec.
+
+The Go implementation is a single binary (`cmd/work-cal-sync`) plus a small diagnostic helper (`cmd/ekprobe`). Code is organized as:
+
+- `pkg/eventkit/` — cgo bridge to EventKit.framework (exported because the diagnostic binary uses it too)
+- `internal/sync/` — config, caldav, ical, keyring, plist, prompt, url, wizard, diff, managed, sync engine
+- `cmd/work-cal-sync/main.go` — subcommand dispatch and bundle-routing helpers
+
+The most important late-stage discovery was that macOS TCC will not grant Calendar access to a bare binary. Sync works only when the binary runs inside a code-signed `.app` bundle, launched via Launch Services. The bundle-routing subcommands (`request-access`, `list-calendars-internal`, `fetch-events-internal`) and the `make app` / `make install-app` targets exist for this reason.
+
+## Tasks
+
+- [x] 1. Project scaffolding
+  - [x] 1.1 Initialize Go module: `github.com/djdead/work-cal-sync`
+  - [x] 1.2 Create directory structure: `cmd/work-cal-sync/`, `cmd/ekprobe/`, `pkg/eventkit/`, `internal/sync/`
+  - [x] 1.3 Create Makefile with `build`, `install`, `app`, `install-app`, `clean` targets
+  - [x] 1.4 Add `.gitignore` for binaries, `.app` bundles, and build artifacts
+  - [x] 1.5 Add build constraint `//go:build darwin` to all Go files
+
+- [x] 2. EventKit cgo bridge (`pkg/eventkit/`)
+  - [x] 2.1 ObjC bridge (`eventkit.m`, `eventkit.h`) with extern "C" entry points: request access, list calendars (filtered to Exchange/O365), fetch events in time range
+  - [x] 2.2 Go layer (`eventkit.go`) with `Calendar` and `Event` structs, `RequestAccess`, `AuthorizationStatus`, `ListExchangeCalendars`, `FetchEvents`
+  - [x] 2.3 Authorization flow with timeout
+  - [x] 2.4 NSDate ↔ time.Time conversion
+  - [x] 2.5 `Info.plist` with `NSCalendarsFullAccessUsageDescription` for the .app bundle
+
+- [x] 3. Config (`internal/sync/config.go`)
+  - [x] 3.1 `Load`, `Save`, `Path` helpers
+  - [x] 3.2 Directory `0700`, file `0600`, atomic write via temp file + rename
+  - [x] 3.3 `Config` struct with JSON tags including `work_calendar_id`
+
+- [x] 4. CalDAV client (`internal/sync/caldav.go`, `ical.go`, `managed.go`)
+  - [x] 4.1 Wrap `github.com/emersion/go-webdav` for connect, list calendars, fetch, create, update, delete
+  - [x] 4.2 Build VCALENDAR/VEVENT via `github.com/emersion/go-ical` with `X-WORK-CAL-ID` and `X-WORK-CAL-MODIFIED` properties
+  - [x] 4.3 Parse managed events from CalDAV into a map keyed by `X-WORK-CAL-ID`
+
+- [x] 5. Sync engine (`internal/sync/sync.go`, `diff.go`)
+  - [x] 5.1 Fetch work events from EventKit (via injected `FetchEventKit` hook so the main binary can route through the bundle)
+  - [x] 5.2 Fetch managed events from CalDAV
+  - [x] 5.3 Diff: create / update (by `X-WORK-CAL-MODIFIED`) / delete
+  - [x] 5.4 Structured `slog` output with counts and per-event actions
+
+- [x] 6. Wizard (`internal/sync/wizard.go`, `prompt.go`, `url.go`, `keyring.go`)
+  - [x] 6.1 Interactive prompts via `Prompter` (stdin/stdout, password via terminal echo-off)
+  - [x] 6.2 Numbered list selection helper
+  - [x] 6.3 HTTPS validation (loopback hosts allowed)
+  - [x] 6.4 Reuse-existing-values flow when config already present
+  - [x] 6.5 Save config and store password via `github.com/zalando/go-keyring`
+
+- [x] 7. launchd plist (`internal/sync/plist.go`)
+  - [x] 7.1 Generate plist from a Go `text/template` string with XML escaping
+  - [x] 7.2 `Generate`, `InstallPlist` (atomic), `LoadJob`, `UnloadJob` (idempotent), `RemovePlist` (idempotent), `PlistPath`, `Label`
+  - [x] 7.3 Label `tel.dead.work-cal-sync.go` to coexist with the Python version
+  - [x] 7.4 Plist values: `StartInterval=900`, `RunAtLoad=false`, `KeepAlive=false`, log to `~/Library/Logs/work-cal-sync.log`
+
+- [x] 8. `.app` bundle and bundle routing
+  - [x] 8.1 `make app` produces a code-signed `work-cal-sync.app/` with `Contents/Info.plist`, `Contents/MacOS/work-cal-sync`, `Contents/PkgInfo`
+  - [x] 8.2 `make install-app` copies bundle to `~/Applications/`
+  - [x] 8.3 `CODESIGN_IDENTITY` auto-detected (first `Apple Development:`) with ad-hoc `-` fallback
+  - [x] 8.4 Hidden subcommands `request-access`, `list-calendars-internal`, `fetch-events-internal` for in-bundle execution
+  - [x] 8.5 `findBundlePath`, `runViaBundle`, `listCalendarsViaBundle`, `fetchEventsViaBundle` helpers in main; results returned via JSON in temp files
+  - [x] 8.6 Clear error message when bundle is missing ("Run `make install-app` to install the bundle")
+
+- [x] 9. Main entry point (`cmd/work-cal-sync/main.go`)
+  - [x] 9.1 Subcommand dispatch on `os.Args[1]`; unknown args fall through to sync
+  - [x] 9.2 No-arg default: run sync (the launchd path)
+  - [x] 9.3 `setup`: load existing config, run wizard with bundle-routed EventKit and CalDAV adapters
+  - [x] 9.4 `install`: resolve binary path, run setup if no config, generate + install plist, unload-then-load for idempotence
+  - [x] 9.5 `uninstall`: confirm (default no), unload, remove plist, remove config dir, print Keychain removal command
+  - [x] 9.6 `status`: print config (no password), launchd state, last 20 log lines
+  - [x] 9.7 `help` / `-h` / `--help`: print usage to stdout
+  - [x] 9.8 `-v` / `-q` verbosity flags with TTY-aware default via `golang.org/x/term`
+  - [x] 9.9 Centralized `slog` text logger to stderr
+
+- [x] 10. Diagnostic helper (`cmd/ekprobe/`)
+  - [x] 10.1 `main.go` and ObjC bridge (`probe.m`)
+  - [x] 10.2 Reports auth status, requests access, lists Exchange/O365 calendars
+
+- [x] 11. Tests
+  - [x] 11.1 Unit tests for config, caldav, diff, ical, keyring, managed, plist, prompt, url, wizard, sync, main
+  - [x] 11.2 Test hooks: `runLaunchctl` is a package var so tests can stub launchctl
+  - [x] 11.3 `Engine` exposes injectable `FetchEventKit`, `FetchCalDAV`, `PutCalDAV`, `DeleteCalDAV` for table tests
+
+- [x] 12. Documentation
+  - [x] 12.1 `README.md` updated with both Python and Go install paths
+  - [x] 12.2 `docs/architecture.md` describes the bundle-routing approach and module layout
+  - [x] 12.3 `docs/user-guide.md` walks through setup → install → status
+  - [x] 12.4 `docs/troubleshooting.md` covers TCC issues and `ekprobe` usage
+  - [x] 12.5 Migration note for Python users (stop Python launchd job, then `setup` + `install`)
+
+- [ ] 13. Verification and release
+  - [x] 13.1 `go build ./cmd/work-cal-sync` succeeds
+  - [ ] 13.2 `go vet ./...` clean across the whole module
+  - [x] 13.3 Manual test: install, setup, run sync, status, uninstall against a local Radicale instance
+  - [ ] 13.4 Tag a v0.1.0 release once verification is green
+
+## Task Dependency Graph
+
+Tasks are organized into waves. Tasks in the same wave can be executed in parallel; later waves depend on earlier ones.
+
+```json
+{
+  "waves": [
+    {
+      "wave": 1,
+      "tasks": [1],
+      "description": "Scaffolding before any code"
+    },
+    {
+      "wave": 2,
+      "tasks": [2, 3, 4],
+      "description": "Foundational packages: EventKit bridge, config, CalDAV client (parallel)"
+    },
+    {
+      "wave": 3,
+      "tasks": [5, 6, 7],
+      "description": "Sync engine, wizard, launchd plist (parallel; depend on wave 2)"
+    },
+    {
+      "wave": 4,
+      "tasks": [8],
+      "description": "App bundle and bundle-routing helpers (depend on EventKit bridge from wave 2)"
+    },
+    {
+      "wave": 5,
+      "tasks": [9],
+      "description": "Main entry point ties wizard, plist, sync, and bundle routing into subcommands"
+    },
+    {
+      "wave": 6,
+      "tasks": [10, 11],
+      "description": "Diagnostic helper and tests (parallel; both depend on wave 5)"
+    },
+    {
+      "wave": 7,
+      "tasks": [12],
+      "description": "Documentation"
+    },
+    {
+      "wave": 8,
+      "tasks": [13],
+      "description": "Final verification and release"
+    }
+  ]
+}
+```
+
+## Notes
+
+- The Python implementation (`work-cal-sync.py`, `setup.sh`, `tel.dead.work-cal-sync.plist`) stays in the repo unchanged. Both versions coexist via different launchd labels (`tel.dead.work-cal-sync` for Python, `tel.dead.work-cal-sync.go` for Go).
+- cgo is required for the EventKit bridge. Keychain access uses `github.com/zalando/go-keyring` instead of a custom Security.framework bridge.
+- TCC requires a code-signed `.app` bundle with `NSCalendarsFullAccessUsageDescription`. Running the bare binary works for `setup`, `install`, and `status`, but EventKit-touching paths re-invoke the bundle via Launch Services.
+- Subcommand dispatch uses standard library only (no `cobra` / `urfave-cli`).
+- `cmd/meeting-alerter/` is **out of scope** for this spec; it is tracked separately at `.kiro/specs/meeting-alerter/`.
+- Status legend: `[x]` complete, `[-]` in progress, `[ ]` not started.
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..286aec2
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,98 @@
+INSTALL_DIR     := $(HOME)/bin
+APP_INSTALL_DIR := $(HOME)/Applications
+
+# CODESIGN_IDENTITY selects which keychain identity signs each .app
+# bundle. A stable identity (anything other than the "-" ad-hoc
+# sentinel) keeps TCC from treating each rebuild as a brand new app
+# and re-prompting for Calendar access. Override on the command line
+# for a different identity:
+#   make app CODESIGN_IDENTITY="Apple Development: you@example.com (XXXXXXXXXX)"
+CODESIGN_IDENTITY ?= $(shell security find-identity -p codesigning -v 2>/dev/null | awk -F'"' '/Apple Development/ {print $$2; exit}' | head -1)
+ifeq ($(strip $(CODESIGN_IDENTITY)),)
+CODESIGN_IDENTITY := -
+endif
+
+# Two CLIs share the build / bundle / install pattern. Each entry has:
+#   * a BINARY name (matches both ./cmd/<name> and the produced binary)
+#   * a BUNDLE_ID for codesign / TCC tracking
+# All targets live at the top of this file so contributors don't need
+# to read the recipes to understand what's available.
+.PHONY: build install clean app install-app
+.PHONY: build-work-cal-sync install-work-cal-sync app-work-cal-sync install-app-work-cal-sync
+.PHONY: build-meeting-alerter install-meeting-alerter app-meeting-alerter install-app-meeting-alerter
+
+# Aliases that match the pre-existing names for the work-cal-sync flow.
+build:        build-work-cal-sync
+install:      install-work-cal-sync
+app:          app-work-cal-sync
+install-app:  install-app-work-cal-sync
+
+clean:
+	rm -f work-cal-sync meeting-alerter
+	rm -rf work-cal-sync.app meeting-alerter.app
+
+# ── work-cal-sync ────────────────────────────────────────────────────
+
+WCS_BUNDLE_ID := tel.dead.work-cal-sync
+
+build-work-cal-sync:
+	go build -o work-cal-sync ./cmd/work-cal-sync
+
+install-work-cal-sync: build-work-cal-sync
+	mkdir -p $(INSTALL_DIR)
+	cp work-cal-sync $(INSTALL_DIR)/work-cal-sync
+
+# Build the .app bundle. We cannot ship a bare binary because EventKit
+# (Calendar access) requires the calling executable to live inside a
+# proper bundle with an Info.plist declaring
+# NSCalendarsFullAccessUsageDescription. The binary inside the bundle
+# is the same one `make build` produces; it is still invoked from the
+# CLI via its bundle path.
+app-work-cal-sync: build-work-cal-sync
+	rm -rf work-cal-sync.app
+	mkdir -p work-cal-sync.app/Contents/MacOS
+	cp work-cal-sync work-cal-sync.app/Contents/MacOS/work-cal-sync
+	cp pkg/eventkit/Info.plist work-cal-sync.app/Contents/Info.plist
+	printf 'APPL????' > work-cal-sync.app/Contents/PkgInfo
+	codesign --force --sign "$(CODESIGN_IDENTITY)" --identifier $(WCS_BUNDLE_ID) work-cal-sync.app
+
+install-app-work-cal-sync: app-work-cal-sync
+	mkdir -p $(APP_INSTALL_DIR)
+	rm -rf $(APP_INSTALL_DIR)/work-cal-sync.app
+	cp -R work-cal-sync.app $(APP_INSTALL_DIR)/work-cal-sync.app
+
+# ── meeting-alerter ───────────────────────────────────────────────────
+
+MA_BUNDLE_ID := tel.dead.meeting-alerter
+
+build-meeting-alerter:
+	go build -o meeting-alerter ./cmd/meeting-alerter
+
+install-meeting-alerter: build-meeting-alerter
+	mkdir -p $(INSTALL_DIR)
+	cp meeting-alerter $(INSTALL_DIR)/meeting-alerter
+
+# Same Info.plist (NSCalendarsFullAccessUsageDescription) works for
+# either bundle; the only difference for TCC is the bundle id, which
+# the codesign --identifier flag overrides.
+app-meeting-alerter: build-meeting-alerter
+	rm -rf meeting-alerter.app
+	mkdir -p meeting-alerter.app/Contents/MacOS
+	cp meeting-alerter meeting-alerter.app/Contents/MacOS/meeting-alerter
+	cp pkg/eventkit/Info.plist meeting-alerter.app/Contents/Info.plist
+	# The shared Info.plist is authored for work-cal-sync; rewrite the
+	# bundle-identity keys so this bundle is its own app from macOS's
+	# perspective. Without this codesign reports Format=bundle (rather
+	# than "app bundle") and Launch Services refuses to associate the
+	# binary with Calendar permission grants.
+	plutil -replace CFBundleExecutable -string meeting-alerter meeting-alerter.app/Contents/Info.plist
+	plutil -replace CFBundleName -string meeting-alerter meeting-alerter.app/Contents/Info.plist
+	plutil -replace CFBundleDisplayName -string meeting-alerter meeting-alerter.app/Contents/Info.plist
+	plutil -replace CFBundleIdentifier -string $(MA_BUNDLE_ID) meeting-alerter.app/Contents/Info.plist
+	printf 'APPL????' > meeting-alerter.app/Contents/PkgInfo
+	codesign --force --sign "$(CODESIGN_IDENTITY)" --identifier $(MA_BUNDLE_ID) meeting-alerter.app
+
+install-app-meeting-alerter: app-meeting-alerter
+	mkdir -p $(APP_INSTALL_DIR)
+	rm -rf $(APP_INSTALL_DIR)/meeting-alerter.app
+	cp -R meeting-alerter.app $(APP_INSTALL_DIR)/meeting-alerter.app
diff --git a/README.md b/README.md
index cdf9b8b..d142d4d 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,184 @@
 # work-cal-sync
 
-Copies work Exchange/O365 calendar events from macOS Calendar.app to a self-hosted CalDAV server (Radicale, Nextcloud, Baikal, etc.).
+Sync your work Exchange/O365 calendar from macOS Calendar.app to a CalDAV server (iCloud, Radicale, Nextcloud, Baikal, etc.).
 
-If you use a self-hosted CalDAV server for your personal calendar and want your work appointments to show up there — without giving a third-party service access to your calendar data — this is for you.
+If you want your work appointments to show up in your personal calendar setup — without giving a third-party SaaS access to your data — this is for you. macOS already speaks Exchange/O365 via your Internet Account, so this tool just bridges the two locally on your Mac.
+
+> **macOS-only.** Depends on Apple's EventKit framework. Does not run on Linux, Windows, or in CI.
+
+For a deeper explanation of the components, data flow, macOS permissions, and how to reuse the EventKit pieces in your own tools, see [docs/architecture.md](docs/architecture.md).
 
 ## How it works
 
-- Reads your work Exchange/O365 calendar via **EventKit** — the same framework macOS Calendar.app uses. No Exchange credentials needed in the script; macOS manages authentication via your Internet Account.
-- Writes to a dedicated calendar on your CalDAV server using the **caldav** Python library.
+- Reads your Exchange/O365 calendar via **EventKit** — the same framework macOS Calendar.app uses. No Exchange credentials live in the tool; macOS handles authentication via your Internet Account.
+- Writes to a dedicated calendar on your CalDAV server.
 - Syncs with `rsync --delete` semantics: creates new events, updates changed ones, deletes cancelled ones.
 - Runs every 15 minutes via **launchd**. No need to keep Calendar.app open.
 
 ## Requirements
 
 - macOS 13 (Ventura) or later, Apple Silicon or Intel
-- Python 3.11+ (Homebrew recommended: `brew install python`)
-- Your work Exchange/O365 account added to macOS via **System Settings → Internet Accounts**
+- Your work Exchange/O365 account added in **System Settings → Internet Accounts**
 - A CalDAV server with a dedicated calendar for work events
+- Go 1.22+ and Xcode Command Line Tools (for the cgo bridge to EventKit)
+- An Apple Development code-signing identity in your keychain. If you don't already have one, the easiest way to get one is to open Xcode → Settings → Accounts and add your Apple ID. Without this, macOS re-prompts for Calendar access on every rebuild.
+
+## Installation
+
+This repo ships **two implementations** of the same tool. Most people will want the Go version:
+
+|                  | [Go (recommended)](#go-recommended)        | [Python (preserved)](#python-preserved)    |
+| ---------------- | ------------------------------------------ | ------------------------------------------ |
+| Distribution     | macOS `.app` bundle + CLI binary           | Script + `pip` dependencies                |
+| Install via      | `make install-app && make install`         | `setup.sh` (clones repo)                   |
+| Toolchain needed | Go 1.22+, Xcode CLT, codesign identity     | Python 3.11+                               |
+| Subcommands      | `setup`, `install`, `uninstall`, `status`  | Wizard runs on first use                   |
+| Status           | Active, recommended for new users          | Preserved for users who prefer Python      |
+
+The two implementations use different launchd labels, so they can coexist on the same machine — but you should not point them at the same target CalDAV calendar. See [Coexistence](#coexistence).
+
+## Go (recommended)
+
+The Go build produces two artifacts that work together:
 
-## Install
+- `work-cal-sync.app` — a macOS application bundle installed to `~/Applications`. macOS Calendar permission is granted to this bundle, not to the CLI binary, because TCC only honors Calendar grants for processes launched via Launch Services.
+- `work-cal-sync` — a CLI binary on your `PATH` that you actually invoke (`work-cal-sync setup`, etc.). When the CLI needs to touch EventKit, it forks a child via `open` against the bundle so the OS attributes the call correctly.
+
+You need both. `make install-app` installs the bundle; `make install` installs the CLI.
+
+### Install (Go)
 
 ```bash
 git clone https://github.com/djdead/work-cal-sync.git
 cd work-cal-sync
-./setup.sh
+make install-app    # builds and installs work-cal-sync.app to ~/Applications
+make install        # builds and installs the CLI to ~/bin/work-cal-sync
 ```
 
-`setup.sh` will:
-1. Install Python dependencies (`pyobjc-framework-EventKit`, `caldav`, `keyring`)
-2. Copy the script to `~/bin/`
-3. Run the interactive setup wizard
-4. Install and load a launchd job to sync every 15 minutes
+Make sure `~/bin` is on your `PATH`:
 
-## First-run setup wizard
+```bash
+export PATH="$HOME/bin:$PATH"
+```
 
-On first run you will be prompted to:
+Verify:
 
-1. **Choose your work calendar** — detected automatically from Exchange/O365 accounts in Calendar.app
-2. **Enter your CalDAV server URL** — e.g. `https://cal.example.com`
-3. **Enter your CalDAV username and password** — password is stored in macOS Keychain, never in the config file
-4. **Choose your target CalDAV calendar** — fetched from your server so you can pick from a list
-5. **Set the sync window** — defaults to 7 days back, 90 days forward
+```bash
+work-cal-sync help
+```
 
-Configuration is saved to `~/.config/work-cal-sync/config.json`. To reconfigure, delete that file and re-run the script.
+The first time you run any subcommand that touches EventKit (`setup`, no-arg sync), macOS will pop up a "work-cal-sync would like to access your calendars" dialog. Click **OK**. The grant persists across rebuilds because `make app` signs the bundle with a stable Apple Development identity from your keychain.
 
-## Logs
+### Subcommands
 
-```
-~/Library/Logs/work-cal-sync.log
-```
+The CLI dispatches on its first argument. Paths used by every subcommand:
+
+- Bundle: `~/Applications/work-cal-sync.app`
+- CLI: `~/bin/work-cal-sync` (or wherever your `make install` target lives)
+- Config: `~/.config/work-cal-sync/config.json` (mode `0600`)
+- Plist: `~/Library/LaunchAgents/tel.dead.work-cal-sync.go.plist`
+- Log: `~/Library/Logs/work-cal-sync.log`
+- Keychain service: `work-cal-sync` (account is your CalDAV username)
+
+#### `work-cal-sync` (no arguments) — run a sync
+
+Runs a single sync and exits. This is what `launchd` invokes every 15 minutes once the job is installed.
+
+- **When to use**: rarely by hand — you'll usually let `launchd` drive it. Run manually to test config changes or trigger an immediate sync.
+- **Behavior**: loads `config.json`, reads the password from Keychain, fetches events from your work calendar via EventKit (forking through the bundle), fetches managed events from your CalDAV calendar, then creates / updates / deletes events to match.
+- **Side effects**: creates, modifies, and deletes events on the target CalDAV calendar. Only events tagged with `X-WORK-CAL-ID` are touched, so user-created events in the same calendar are left alone — but in practice the target should be a dedicated calendar.
+- **Flags**: `-v` / `--verbose` enables per-event debug logs. `-q` / `--quiet` suppresses them. The default level is DEBUG when stderr is a terminal, INFO when not — interactive runs are chatty, `launchd` log files are tidy.
+
+#### `work-cal-sync setup` — interactive wizard
+
+- **When to use**: first-time configuration, or when you want to change the CalDAV server, target calendar, credentials, or sync window.
+- **Behavior**:
+  1. Detects Exchange/O365 calendars from your macOS Internet Accounts and prompts you to pick one.
+  2. Prompts for CalDAV server URL (HTTPS required, except for loopback hosts), username, and password.
+  3. Connects to the server, lists calendars, prompts you to pick the target.
+  4. Prompts for sync window in days back / days forward (defaults: 7 / 90).
+  5. Writes config to `~/.config/work-cal-sync/config.json` and password to Keychain.
+- **Side effects**: creates / overwrites the config file and Keychain entry. Does not touch `launchd` or your calendars.
+- **Re-running**: shows current values as defaults; press Enter to keep each one. The password is always re-prompted.
+
+#### `work-cal-sync install` — schedule via launchd
+
+- **When to use**: after `setup` (or as a shortcut — `install` will run `setup` first if no config exists), or to re-install after upgrading the binary so the plist points at the new path.
+- **Behavior**:
+  1. If no config exists, runs `setup` first.
+  2. Resolves the absolute path of the running binary via `os.Executable()`.
+  3. Generates `~/Library/LaunchAgents/tel.dead.work-cal-sync.go.plist` from a built-in template.
+  4. Loads the launchd job. Idempotent — safe to run again.
+- **Side effects**: writes the plist and registers a `launchd` agent under your user. The job runs every 15 minutes; output goes to `~/Library/Logs/work-cal-sync.log`.
+
+#### `work-cal-sync uninstall` — clean up
+
+- **When to use**: when you're done with the tool, or before switching to a different install location.
+- **Behavior**: lists what will be removed, asks for `y/n`, then unloads the launchd job, removes the plist, removes `~/.config/work-cal-sync/`. Prints the `security delete-generic-password` command for clearing the Keychain entry yourself.
+- **Not touched**: the binary, the bundle (in `~/Applications`), the Keychain entry, or events already on your CalDAV server.
+
+#### `work-cal-sync status` — health check
+
+Prints config (without the password), launchd job state via `launchctl list`, and the last 20 lines of the log file. Read-only.
+
+#### `work-cal-sync help` / `-h` / `--help`
+
+Prints usage and the list of subcommands.
+
+### Migrating from the Python version
 
-## Reconfigure
+1. **Stop the Python launchd job first** so it can't race with the Go job:
+
+   ```bash
+   launchctl unload ~/Library/LaunchAgents/tel.dead.work-cal-sync.plist
+   ```
+
+2. **Install the Go bundle and CLI** as above.
+
+3. **Run `work-cal-sync setup`.** Re-enter your CalDAV URL, username, and password. The Go config format diverges from the Python version's, so the old config is overwritten.
+
+4. **Run `work-cal-sync install`** to schedule the Go launchd job. It uses a different label (`tel.dead.work-cal-sync.go`) so the Python plist remains on disk but unloaded.
+
+5. **Optional cleanup** once the Go version is working:
+
+   ```bash
+   rm ~/Library/LaunchAgents/tel.dead.work-cal-sync.plist
+   rm ~/bin/work-cal-sync.py
+   ```
+
+   The Keychain entry can stay — both versions use the same service name (`work-cal-sync`), so it's reused.
+
+### Coexistence
+
+Both implementations can be installed at once: their launchd labels differ.
+
+- Python: `tel.dead.work-cal-sync`
+- Go: `tel.dead.work-cal-sync.go`
+
+**⚠️ Do not point both at the same CalDAV calendar.** Each version claims ownership of events via the `X-WORK-CAL-ID` property. Running them against the same destination calendar produces churn, duplicates, and unexpected deletes. To run them side-by-side (e.g. to A/B compare), use **different target CalDAV calendars**. Reading from the same Exchange source is fine.
+
+The Keychain entry and config file path are shared between the two — running `setup` on one will overwrite the other's config. Back up the file if you need to switch back.
+
+## Python (preserved)
+
+The original Python implementation lives at the repo root for users who prefer not to install Go:
+
+- `work-cal-sync.py` — the sync script
+- `setup.sh` — the installer and first-run wizard
+
+It's functionally equivalent to the Go version but no longer the recommended path for new installs.
 
 ```bash
-rm ~/.config/work-cal-sync/config.json
-python3 ~/bin/work-cal-sync.py
+git clone https://github.com/djdead/work-cal-sync.git
+cd work-cal-sync
+./setup.sh
 ```
 
-## Uninstall
+`setup.sh` installs Python dependencies (`pyobjc-framework-EventKit`, `caldav`, `keyring`), copies the script to `~/bin/`, runs the interactive setup wizard, and installs a `launchd` job that syncs every 15 minutes.
+
+To reconfigure: `rm ~/.config/work-cal-sync/config.json && python3 ~/bin/work-cal-sync.py`.
+
+To uninstall:
 
 ```bash
 launchctl unload ~/Library/LaunchAgents/tel.dead.work-cal-sync.plist
@@ -66,15 +187,19 @@ rm ~/bin/work-cal-sync.py
 rm -rf ~/.config/work-cal-sync
 ```
 
-To remove the saved password from Keychain, open **Keychain Access**, search for `work-cal-sync`, and delete the entry.
-
-## Tested with
+## Tested combinations
 
 - macOS 15 Sequoia, M4 Pro
-- Exchange Online (O365)
-- Radicale 3.x
+- Exchange Online (Adobe O365 tenant) as the source
+- Targets: iCloud (`https://caldav.icloud.com`) with an app-specific password, Radicale 3.x for local testing
+
+Other CalDAV servers that follow RFC 4791 should work. Please open an issue if you test against another server.
+
+### iCloud notes
 
-Other CalDAV servers that follow RFC 4791 should work. Please open an issue if you test with another server.
+- Use an [app-specific password](https://account.apple.com), not your Apple ID password.
+- Create a fresh **iCloud calendar** for the destination. Don't pick your existing personal calendar — even though only `X-WORK-CAL-ID`-tagged events are touched, mixing 100+ work events into your personal view is unpleasant.
+- iCloud's CalDAV is quirky in subtle ways (host sharding, empty-calendar 404s for the `calendar-data` property). The CalDAV client handles these.
 
 ## Why not just use gSyncIt / CalDAVconnect / etc.?
 
@@ -83,20 +208,35 @@ Other CalDAV servers that follow RFC 4791 should work. Please open an issue if y
 - **Outlook CalDAV Synchronizer** is Windows-only and dead on new Outlook.
 - **macOS Calendar.app** can display both your Exchange and CalDAV calendars simultaneously, but has no built-in way to copy events between accounts.
 
-This script fills that gap: fully local, no cloud intermediary, no credentials stored in plaintext.
-
 ## Limitations
 
-- **One-way only** — work → personal CalDAV. Changes made on the CalDAV side are overwritten on the next sync.
+- **One-way only** — work → CalDAV. Changes made on the CalDAV side are overwritten on the next sync.
 - **No attendee/RSVP data** — EventKit exposes attendees but they are not currently written to CalDAV events.
 - **Exchange Online only** — EWS/on-premises Exchange is not tested but may work since macOS abstracts the protocol.
-- **EWS deprecation** — Microsoft is deprecating EWS for Exchange Online. This script uses EventKit (not EWS directly), so it should be unaffected as long as macOS continues to support Exchange accounts natively.
+- **EWS deprecation** — Microsoft is deprecating EWS for Exchange Online. This tool uses EventKit (not EWS directly), so it should be unaffected as long as macOS continues to support Exchange accounts natively.
+
+## Building your own EventKit-based tool
+
+The `pkg/eventkit` package is a public Go wrapper around the parts of EventKit needed to list calendars, fetch events, and observe changes. It's safe to import from outside this repo.
+
+A worked example lives in `cmd/meeting-alerter`: a small CLI that watches your calendar and posts a macOS notification a configurable number of minutes before each upcoming meeting. To build and install it:
+
+```bash
+make install-app-meeting-alerter   # macOS .app bundle for TCC permission
+make install-meeting-alerter       # CLI binary on ~/bin
+meeting-alerter setup              # pick the calendar + lookahead/notify-before minutes
+meeting-alerter list               # one-shot: print upcoming meetings
+meeting-alerter watch              # long-running watcher; reacts to EventKit changes via NSNotificationCenter
+```
+
+The alerter doubles as a scaffold for any tool that wants to react to calendar changes. See [docs/architecture.md](docs/architecture.md#reusing-the-eventkit-pieces) for the package API and the bundle pattern your tool will need to satisfy macOS TCC.
 
 ## Contributing
 
 PRs welcome. Known areas for improvement:
 
 - Attendee/organizer fields
-- Support for recurring event exceptions
+- Recurring event exception handling
 - Configurable sync interval
-- Tests
+- A `--dry-run` flag
+- Two-way sync (the diff engine could go either direction)
diff --git a/cmd/ekprobe/main.go b/cmd/ekprobe/main.go
new file mode 100644
index 0000000..6bc78be
--- /dev/null
+++ b/cmd/ekprobe/main.go
@@ -0,0 +1,111 @@
+//go:build darwin
+
+// Command ekprobe is a diagnostic tool for inspecting EventKit state on
+// the local machine. It prints the current authorization status,
+// requests access (which may pop the system permission dialog), then
+// dumps every calendar EventKit knows about with its source type so we
+// can see why the wizard might not be matching.
+//
+// This is not part of the user-facing product; it exists to help debug
+// "no Exchange/O365 calendars found" errors.
+package main
+
+/*
+#cgo CFLAGS: -fobjc-arc -x objective-c
+#cgo LDFLAGS: -framework EventKit -framework Foundation -Wl,-sectcreate,__TEXT,__info_plist,${SRCDIR}/../../pkg/eventkit/Info.plist
+
+#include <stdlib.h>
+
+typedef struct {
+    char* identifier;
+    char* title;
+    char* sourceTitle;
+    int   sourceType;
+    int   allowsContentModifications;
+} ProbeCalendar;
+
+int  probe_authorization_status(void);
+int  probe_request_access(double timeoutSeconds);
+ProbeCalendar* probe_list_all(int* outCount);
+void probe_free(ProbeCalendar* arr, int count);
+*/
+import "C"
+
+import (
+	"fmt"
+	"os"
+	"unsafe"
+)
+
+func main() {
+	statusName := func(s int) string {
+		switch s {
+		case 0:
+			return "NotDetermined"
+		case 1:
+			return "Restricted"
+		case 2:
+			return "Denied"
+		case 3:
+			return "FullAccess (or legacy Authorized)"
+		case 4:
+			return "WriteOnly"
+		default:
+			return fmt.Sprintf("unknown(%d)", s)
+		}
+	}
+
+	fmt.Printf("Initial authorization status: %d (%s)\n",
+		C.probe_authorization_status(), statusName(int(C.probe_authorization_status())))
+
+	fmt.Println("Requesting access (may show a system prompt)...")
+	granted := C.probe_request_access(C.double(30.0))
+	fmt.Printf("RequestAccess returned: %d (%s)\n",
+		granted, map[C.int]string{0: "denied or timed out", 1: "granted"}[granted])
+
+	fmt.Printf("Post-request authorization status: %d (%s)\n\n",
+		C.probe_authorization_status(), statusName(int(C.probe_authorization_status())))
+
+	if granted == 0 {
+		fmt.Fprintln(os.Stderr, "Access not granted — fix in System Settings → Privacy & Security → Calendars")
+		os.Exit(1)
+	}
+
+	sourceTypeName := func(t int) string {
+		switch t {
+		case 0:
+			return "Local"
+		case 1:
+			return "Exchange"
+		case 2:
+			return "CalDAV"
+		case 3:
+			return "MobileMe"
+		case 4:
+			return "Subscribed"
+		case 5:
+			return "Birthdays"
+		default:
+			return fmt.Sprintf("unknown(%d)", t)
+		}
+	}
+
+	var n C.int
+	cArr := C.probe_list_all(&n)
+	if cArr == nil {
+		fmt.Println("No calendars at all — that's unusual.")
+		return
+	}
+	defer C.probe_free(cArr, n)
+
+	count := int(n)
+	cs := unsafe.Slice(cArr, count)
+	fmt.Printf("Found %d total calendars:\n\n", count)
+	for i, c := range cs {
+		fmt.Printf("  [%d] title=%q\n", i, C.GoString(c.title))
+		fmt.Printf("       sourceTitle=%q\n", C.GoString(c.sourceTitle))
+		fmt.Printf("       sourceType=%d (%s)\n", int(c.sourceType), sourceTypeName(int(c.sourceType)))
+		fmt.Printf("       identifier=%s\n", C.GoString(c.identifier))
+		fmt.Printf("       writable=%v\n\n", c.allowsContentModifications != 0)
+	}
+}
diff --git a/cmd/ekprobe/probe.m b/cmd/ekprobe/probe.m
new file mode 100644
index 0000000..94ddc4d
--- /dev/null
+++ b/cmd/ekprobe/probe.m
@@ -0,0 +1,92 @@
+//go:build darwin
+
+#import <EventKit/EventKit.h>
+#import <Foundation/Foundation.h>
+
+#include <stdlib.h>
+#include <string.h>
+
+typedef struct {
+    char* identifier;
+    char* title;
+    char* sourceTitle;
+    int   sourceType;
+    int   allowsContentModifications;
+} ProbeCalendar;
+
+static EKEventStore* gStore = nil;
+static EKEventStore* sharedStore(void) {
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{ gStore = [[EKEventStore alloc] init]; });
+    return gStore;
+}
+
+static char* dupStr(NSString* s) {
+    const char* utf8 = (s != nil) ? [s UTF8String] : "";
+    if (utf8 == NULL) utf8 = "";
+    return strdup(utf8);
+}
+
+int probe_authorization_status(void) {
+    return (int)[EKEventStore authorizationStatusForEntityType:EKEntityTypeEvent];
+}
+
+int probe_request_access(double timeoutSeconds) {
+    EKEventStore* store = sharedStore();
+    dispatch_semaphore_t sem = dispatch_semaphore_create(0);
+    __block BOOL granted = NO;
+
+    void (^completion)(BOOL, NSError*) = ^(BOOL g, NSError* err) {
+        (void)err;
+        granted = g;
+        dispatch_semaphore_signal(sem);
+    };
+
+    SEL fullAccessSel = NSSelectorFromString(@"requestFullAccessToEventsWithCompletion:");
+    if ([store respondsToSelector:fullAccessSel]) {
+        typedef void (*Fn)(id, SEL, void(^)(BOOL, NSError*));
+        IMP imp = [store methodForSelector:fullAccessSel];
+        ((Fn)imp)(store, fullAccessSel, completion);
+    } else {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+        [store requestAccessToEntityType:EKEntityTypeEvent completion:completion];
+#pragma clang diagnostic pop
+    }
+
+    dispatch_time_t deadline = dispatch_time(DISPATCH_TIME_NOW,
+        (int64_t)(timeoutSeconds * (double)NSEC_PER_SEC));
+    if (dispatch_semaphore_wait(sem, deadline) != 0) return 0;
+    return granted ? 1 : 0;
+}
+
+ProbeCalendar* probe_list_all(int* outCount) {
+    if (outCount) *outCount = 0;
+    EKEventStore* store = sharedStore();
+    NSArray<EKCalendar*>* cals = [store calendarsForEntityType:EKEntityTypeEvent];
+    if (cals == nil || cals.count == 0) return NULL;
+
+    NSUInteger n = cals.count;
+    ProbeCalendar* arr = (ProbeCalendar*)calloc(n, sizeof(ProbeCalendar));
+    if (!arr) return NULL;
+    for (NSUInteger i = 0; i < n; i++) {
+        EKCalendar* c = cals[i];
+        arr[i].identifier = dupStr(c.calendarIdentifier);
+        arr[i].title      = dupStr(c.title);
+        arr[i].sourceTitle = dupStr(c.source ? c.source.title : @"");
+        arr[i].sourceType  = c.source ? (int)c.source.sourceType : -1;
+        arr[i].allowsContentModifications = c.allowsContentModifications ? 1 : 0;
+    }
+    if (outCount) *outCount = (int)n;
+    return arr;
+}
+
+void probe_free(ProbeCalendar* arr, int count) {
+    if (!arr) return;
+    for (int i = 0; i < count; i++) {
+        free(arr[i].identifier);
+        free(arr[i].title);
+        free(arr[i].sourceTitle);
+    }
+    free(arr);
+}
diff --git a/cmd/work-cal-sync/doc.go b/cmd/work-cal-sync/doc.go
new file mode 100644
index 0000000..1adf1f5
--- /dev/null
+++ b/cmd/work-cal-sync/doc.go
@@ -0,0 +1,7 @@
+//go:build darwin
+
+// Command work-cal-sync syncs work Exchange/O365 calendar events from
+// macOS Calendar.app to a self-hosted CalDAV server.
+//
+// This package is macOS-only because it relies on the EventKit framework.
+package main
diff --git a/cmd/work-cal-sync/main.go b/cmd/work-cal-sync/main.go
new file mode 100644
index 0000000..fd05ecc
--- /dev/null
+++ b/cmd/work-cal-sync/main.go
@@ -0,0 +1,886 @@
+//go:build darwin
+
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"log/slog"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"golang.org/x/term"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+	"github.com/djdead/work-cal-sync/internal/sync"
+)
+
+// main dispatches to the appropriate subcommand based on os.Args[1].
+//
+// With no arguments, sync runs as the default action (this is the path
+// launchd takes when invoking the binary on a schedule). Unknown first
+// arguments are treated as flags to the sync command rather than errors,
+// which keeps the door open for future sync-specific flags.
+//
+// Subcommand handlers are stubs at this stage; subsequent tasks fill in
+// their implementations.
+func main() {
+	if len(os.Args) < 2 {
+		runSync(nil)
+		return
+	}
+
+	switch os.Args[1] {
+	case "setup":
+		runSetup(os.Args[2:])
+	case "install":
+		runInstall(os.Args[2:])
+	case "uninstall":
+		runUninstall(os.Args[2:])
+	case "status":
+		runStatus(os.Args[2:])
+	case "request-access":
+		runRequestAccess(os.Args[2:])
+	case "list-calendars-internal":
+		runListCalendarsInternal(os.Args[2:])
+	case "fetch-events-internal":
+		runFetchEventsInternal(os.Args[2:])
+	case "-h", "--help", "help":
+		printUsage()
+	default:
+		// Treat unknown args as flags to the sync command.
+		runSync(os.Args[1:])
+	}
+}
+
+// runSync executes a single sync pass. This is the path launchd takes when
+// invoking the binary on its 15-minute schedule (no arguments).
+//
+// The args slice is currently ignored; it exists so future sync-specific
+// flags can be parsed without changing the dispatcher in main. Logs go to
+// stderr so launchd captures them to ~/Library/Logs/work-cal-sync.log.
+//
+// On any fatal condition this function calls os.Exit with a non-zero
+// status. The engine itself emits the run summary via slog, so a
+// successful exit is silent at the binary level.
+func runSync(args []string) {
+level, args := extractVerbosity(args)
+	log := newLogger(level)
+	_ = args
+
+	cfg, err := sync.Load()
+	if err != nil {
+		log.Error("sync: load config failed", "err", err)
+		os.Exit(1)
+	}
+	if cfg == nil {
+		fmt.Fprintln(os.Stderr, "work-cal-sync: no config found. Run `work-cal-sync setup` first.")
+		os.Exit(1)
+	}
+
+	password, err := sync.NewKeyringStore().Get(cfg.CalDAVUsername)
+	if err != nil {
+		log.Error("sync: read keychain password failed",
+			"caldav_username", cfg.CalDAVUsername, "err", err)
+		os.Exit(1)
+	}
+
+	client, err := sync.NewCalDAVClient(cfg.CalDAVServer, cfg.CalDAVUsername, password)
+	if err != nil {
+		log.Error("sync: build caldav client failed", "err", err)
+		os.Exit(1)
+	}
+	client.SetCalendarURL(cfg.CalDAVCalendarURL)
+
+	engine := sync.NewEngine()
+	engine.Log = log
+	engine.FetchCalDAV = client.FetchEvents
+	engine.PutCalDAV = client.PutEvent
+	engine.DeleteCalDAV = client.DeleteEvent
+
+	// FetchEventKit must run inside the .app bundle (see
+	// listCalendarsViaBundle for why). Replace the default direct call
+	// with a bundle-routed one.
+	engine.FetchEventKit = fetchEventsViaBundle
+
+	ctx := context.Background()
+	if _, err := engine.Sync(ctx, cfg); err != nil {
+		log.Error("sync: failed", "err", err)
+		os.Exit(1)
+	}
+}
+
+// runRequestAccess invokes EventKit access request and exits. It is the
+// path to call via `open -a work-cal-sync.app --args request-access`,
+// which makes Launch Services attribute the request to the .app bundle
+// (and its Info.plist) rather than the parent shell. Once permission is
+// granted, subsequent invocations from any shell will inherit the
+// already-granted state.
+//
+// Status code maps to authorization outcome:
+//
+//	0 — granted (FullAccess)
+//	1 — request errored (logged to stderr)
+//	2 — denied or otherwise unavailable (user clicked Don't Allow,
+//	    or the system has the permission disabled)
+//
+// Use a long timeout (5 minutes) because the system dialog may sit
+// behind other windows and the user needs time to find and click it.
+func runRequestAccess(args []string) {
+level, args := extractVerbosity(args)
+	log := newLogger(level)
+	_ = args
+
+	statusBefore := eventkit.AuthorizationStatus()
+	log.Info("request-access starting", "auth_status_before", statusBefore)
+
+	granted, err := eventkit.RequestAccess(5 * time.Minute)
+	if err != nil {
+		log.Error("request-access: errored", "err", err)
+		os.Exit(1)
+	}
+
+	statusAfter := eventkit.AuthorizationStatus()
+	log.Info("request-access finished",
+		"granted", granted,
+		"auth_status_after", statusAfter)
+
+	if !granted {
+		os.Exit(2)
+	}
+}
+
+// runSetup runs the interactive configuration wizard. It loads any
+// existing config (so the wizard can offer previous values as defaults),
+// builds adapters around the EventKit and CalDAV packages, and delegates
+// to sync.CompleteSetup which handles persistence and Keychain writes.
+//
+// On any error the cause is logged to stderr and the process exits 1.
+func runSetup(args []string) {
+level, args := extractVerbosity(args)
+	log := newLogger(level)
+	_ = args
+
+	existing, err := sync.Load()
+	if err != nil {
+		log.Error("setup: load existing config failed", "err", err)
+		os.Exit(1)
+	}
+
+	prompter := sync.NewPrompter(os.Stdin, os.Stdout)
+	ek := eventKitAdapter{}
+	dialer := caldavDialerAdapter{}
+	keyring := sync.NewKeyringStore()
+
+	if _, err := sync.CompleteSetup(prompter, existing, ek, dialer, keyring); err != nil {
+		log.Error("setup: failed", "err", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("Setup complete. Run `work-cal-sync install` to schedule.")
+}
+
+// eventKitAdapter satisfies sync.EventKitProvider by delegating to the
+// real EventKit bridge. Before listing calendars it explicitly requests
+// EventKit access so the user gets a system permission prompt on first
+// run; without this, macOS 14+ silently returns an empty list when the
+// authorization status is NotDetermined and the binary appears to "not
+// find any Exchange/O365 calendars" even when one is configured.
+type eventKitAdapter struct{}
+
+func (eventKitAdapter) ListExchangeCalendars() ([]eventkit.Calendar, error) {
+	// macOS attaches Calendar access to the launch method, not the
+	// binary path. Direct execs from a shell get attributed to the
+	// shell (which has no grant). Launching via `open` against the
+	// bundle in ~/Applications makes Launch Services attribute the
+	// process to the .app's bundle id, which DOES have a grant. So
+	// we delegate the actual EventKit call to a subprocess launched
+	// that way and read the result back through a temp file.
+	return listCalendarsViaBundle()
+}
+
+// caldavDialerAdapter satisfies sync.CalDAVDialer by constructing a fresh
+// CalDAVClient per call and listing its calendars. A new client per
+// dial-test keeps credentials scoped to the wizard's request and avoids
+// keeping connections around between prompts.
+type caldavDialerAdapter struct{}
+
+func (caldavDialerAdapter) ListCalendars(ctx context.Context, serverURL, username, password string) ([]sync.CalendarInfo, error) {
+	client, err := sync.NewCalDAVClient(serverURL, username, password)
+	if err != nil {
+		return nil, err
+	}
+	return client.ListCalendars(ctx)
+}
+
+// runInstall installs (or re-installs) the launchd job that runs the
+// sync on a 15-minute schedule.
+//
+// Steps, in order:
+//  1. Resolve the absolute path of the running binary so launchd
+//     invokes the same executable the user just ran.
+//  2. Resolve the log path (~/Library/Logs/work-cal-sync.log).
+//  3. If no config exists yet, run the setup wizard first (REQ-4:
+//     "Triggers `setup` if no config exists").
+//  4. Generate the plist with the resolved paths.
+//  5. Unload any existing job with the same label, then install the
+//     plist and load the job. Unload-before-load makes the operation
+//     idempotent — re-running install to update the binary path is a
+//     supported workflow (REQ-4).
+//  6. Print a confirmation including the plist and log paths.
+//
+// On any fatal error the cause is logged and the process exits 1.
+func runInstall(args []string) {
+level, args := extractVerbosity(args)
+	log := newLogger(level)
+	_ = args
+
+	// Resolve the absolute path of the running binary. EvalSymlinks
+	// follows any symlink chain (e.g. ~/bin/work-cal-sync ->
+	// /usr/local/bin/work-cal-sync) so launchd records a stable target
+	// rather than the symlink itself.
+	exe, err := os.Executable()
+	if err != nil {
+		log.Error("install: resolve executable path failed", "err", err)
+		os.Exit(1)
+	}
+	binaryPath, err := filepath.EvalSymlinks(exe)
+	if err != nil {
+		log.Error("install: evaluate symlinks failed", "exe", exe, "err", err)
+		os.Exit(1)
+	}
+
+	// Resolve the log path under ~/Library/Logs.
+	home, err := os.UserHomeDir()
+	if err != nil {
+		log.Error("install: resolve home directory failed", "err", err)
+		os.Exit(1)
+	}
+	logPath := filepath.Join(home, "Library", "Logs", "work-cal-sync.log")
+
+	// If no config exists yet, run setup first so the scheduled job
+	// has something to do once it fires.
+	cfg, err := sync.Load()
+	if err != nil {
+		log.Error("install: load config failed", "err", err)
+		os.Exit(1)
+	}
+	if cfg == nil {
+		fmt.Println("No config found. Running setup first...")
+		runSetup(nil)
+	}
+
+	// Render the plist for the resolved binary and log paths.
+	data := sync.Generate(binaryPath, logPath)
+
+	// Unload any existing job with the same label before loading the
+	// new one. UnloadJob is idempotent (no-op if the plist or job is
+	// missing), so this is safe on a first install too.
+	if err := sync.UnloadJob(); err != nil {
+		log.Error("install: unload existing job failed", "err", err)
+		os.Exit(1)
+	}
+
+	if err := sync.InstallPlist(data); err != nil {
+		log.Error("install: write plist failed", "err", err)
+		os.Exit(1)
+	}
+
+	if err := sync.LoadJob(); err != nil {
+		log.Error("install: load job failed", "err", err)
+		os.Exit(1)
+	}
+
+	plistPath, err := sync.PlistPath()
+	if err != nil {
+		// Both InstallPlist and LoadJob already resolved this path,
+		// so this is unlikely; fall back to a generic message.
+		log.Error("install: resolve plist path failed", "err", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("Installed.")
+	fmt.Printf("  plist: %s\n", plistPath)
+	fmt.Printf("  log:   %s\n", logPath)
+	fmt.Println("The job will run every 15 minutes. Use `work-cal-sync status` to verify.")
+}
+
+// runUninstall reverses what `install` did: unloads the launchd job,
+// removes the plist, and deletes the config directory. It does NOT
+// remove the binary itself (the user may have installed it via
+// `go install`, Homebrew, or by copying it into place — we don't know
+// where it lives) and it does NOT touch the Keychain entry; instead it
+// prints the `security delete-generic-password` command the user can
+// run, since deleting Keychain entries can prompt for the user's login
+// password and we'd rather make that an explicit choice (REQ-5).
+//
+// Steps, in order:
+//  1. Resolve the plist and config-directory paths and load the config
+//     (if any) so we can show the user exactly what will be removed
+//     and so we know which Keychain account to mention at the end.
+//  2. Print the removal plan and ask for y/n confirmation. Default is
+//     "no" — uninstall is destructive enough that an accidental Enter
+//     should not wipe the config.
+//  3. Unload the launchd job. UnloadJob is idempotent (no-op if the
+//     plist or job is missing) so this is safe even if `install` was
+//     never run.
+//  4. Remove the plist file.
+//  5. Remove the entire config directory (~/.config/work-cal-sync/).
+//     We use os.RemoveAll on the directory rather than just the
+//     config file so any stray files (e.g. an editor's swap file) get
+//     cleaned up too.
+//  6. Print the Keychain removal command, suffixed with the username
+//     when known.
+//
+// Failures during steps 3–5 are reported but don't abort the
+// uninstall: the user expects "remove everything" to do its best even
+// if individual pieces are missing.
+func runUninstall(args []string) {
+level, args := extractVerbosity(args)
+	log := newLogger(level)
+	_ = args
+
+	// Resolve paths up front so the confirmation message is accurate.
+	plistPath, err := sync.PlistPath()
+	if err != nil {
+		log.Error("uninstall: resolve plist path failed", "err", err)
+		os.Exit(1)
+	}
+	configPath, err := sync.Path()
+	if err != nil {
+		log.Error("uninstall: resolve config path failed", "err", err)
+		os.Exit(1)
+	}
+	configDir := filepath.Dir(configPath)
+
+	// Load config (best-effort) so we can name the Keychain account at
+	// the end. A missing or unreadable config is not fatal — the user
+	// may be cleaning up after a partial install.
+	cfg, cfgErr := sync.Load()
+	if cfgErr != nil {
+		log.Warn("uninstall: load config failed; continuing", "err", cfgErr)
+	}
+
+	// Show the user exactly what will be removed.
+	fmt.Println("This will remove the following:")
+	fmt.Printf("  launchd plist: %s\n", plistPath)
+	fmt.Printf("  config dir:    %s\n", configDir)
+	fmt.Println("It will NOT remove:")
+	fmt.Println("  - the work-cal-sync binary itself")
+	fmt.Println("  - the macOS Keychain entry (a command will be printed at the end)")
+	fmt.Println()
+
+	prompter := sync.NewPrompter(os.Stdin, os.Stdout)
+	ok, err := prompter.Confirm("Continue?", false)
+	if err != nil {
+		log.Error("uninstall: read confirmation failed", "err", err)
+		os.Exit(1)
+	}
+	if !ok {
+		fmt.Println("Aborted.")
+		return
+	}
+
+	// Unload the launchd job. Idempotent: returns nil if the plist or
+	// job is missing.
+	if err := sync.UnloadJob(); err != nil {
+		log.Warn("uninstall: unload launchd job failed; continuing", "err", err)
+	} else {
+		fmt.Println("Unloaded launchd job.")
+	}
+
+	// Remove the plist file.
+	if err := sync.RemovePlist(); err != nil {
+		log.Warn("uninstall: remove plist failed; continuing", "err", err)
+	} else {
+		fmt.Printf("Removed plist: %s\n", plistPath)
+	}
+
+	// Remove the config directory.
+	if err := os.RemoveAll(configDir); err != nil {
+		log.Warn("uninstall: remove config dir failed; continuing",
+			"path", configDir, "err", err)
+	} else {
+		fmt.Printf("Removed config dir: %s\n", configDir)
+	}
+
+	// Print the Keychain removal command. We suffix it with the
+	// username when we know it; otherwise we leave a placeholder.
+	account := "<your-caldav-username>"
+	if cfg != nil && cfg.CalDAVUsername != "" {
+		account = cfg.CalDAVUsername
+	}
+	fmt.Println()
+	fmt.Println("To remove the Keychain entry, run:")
+	fmt.Printf("  security delete-generic-password -s %s -a %s\n",
+		sync.KeyringService, account)
+}
+
+// runStatus reports the current install/config/launchd state. It prints
+// three sections, separated by blank lines, in this order:
+//
+//  1. Config: the path to the config file and its contents (the Config
+//     struct has no password field, so dumping it as pretty JSON is
+//     safe). If the config is missing, an informational message is
+//     printed and the next sections still run — a missing config does
+//     not prevent the user from inspecting launchd or log state.
+//
+//  2. Launchd: the output of `launchctl list <label>`. launchctl exits
+//     non-zero with a "Could not find service" message when the job is
+//     not loaded; we translate that into a friendly "not loaded"
+//     line. Any other launchctl error is reported but does not abort
+//     the command.
+//
+//  3. Log: the last ~20 lines of ~/Library/Logs/work-cal-sync.log. A
+//     missing log file is treated as "no log yet" rather than an
+//     error, since the file is created by launchd on first run.
+//
+// All errors are reported to stdout (next to the section they belong
+// to) rather than stderr, so users get a single coherent dump.
+// runStatus does not call os.Exit on partial failures — the goal is to
+// show whatever state we *can* observe.
+func runStatus(args []string) {
+level, args := extractVerbosity(args)
+	log := newLogger(level)
+	_ = args
+
+	printConfigStatus(log)
+	fmt.Println()
+	printLaunchdStatus(log)
+	fmt.Println()
+	printLogTail(log, statusLogTailLines)
+}
+
+// statusLogTailLines is the number of trailing log lines `status`
+// prints. Per design.md ("last ~20 lines"), 20 is enough to spot
+// recent run summaries without flooding the terminal.
+const statusLogTailLines = 20
+
+// printConfigStatus prints the config path and contents (no password —
+// the Config struct contains none).
+func printConfigStatus(log *slog.Logger) {
+	configPath, err := sync.Path()
+	if err != nil {
+		log.Error("status: resolve config path failed", "err", err)
+		return
+	}
+
+	fmt.Println("Config:")
+	fmt.Printf("  path: %s\n", configPath)
+
+	cfg, err := sync.Load()
+	if err != nil {
+		fmt.Printf("  error reading config: %v\n", err)
+		return
+	}
+	if cfg == nil {
+		fmt.Println("  (not found — run `work-cal-sync setup` to create one)")
+		return
+	}
+
+	data, err := json.MarshalIndent(cfg, "  ", "  ")
+	if err != nil {
+		// MarshalIndent on a plain struct can't realistically fail,
+		// but report it just in case rather than panicking.
+		fmt.Printf("  error formatting config: %v\n", err)
+		return
+	}
+	// Indent the first line to match the rest of the section's
+	// indentation. MarshalIndent only indents subsequent lines.
+	fmt.Printf("  %s\n", string(data))
+}
+
+// printLaunchdStatus prints the output of `launchctl list <label>`. A
+// non-zero exit from launchctl with a "not found" message is treated
+// as "not loaded" rather than an error.
+func printLaunchdStatus(log *slog.Logger) {
+	label := sync.Label()
+	fmt.Println("Launchd:")
+	fmt.Printf("  label: %s\n", label)
+
+	cmd := exec.Command("launchctl", "list", label)
+	var sout, serr bytes.Buffer
+	cmd.Stdout = &sout
+	cmd.Stderr = &serr
+	err := cmd.Run()
+
+	if err != nil {
+		// launchctl(1) prints "Could not find service" to stdout and
+		// exits 113 when the label isn't loaded. Older macOS releases
+		// use slightly different wording, so match a few variants.
+		combined := strings.ToLower(sout.String() + "\n" + serr.String())
+		switch {
+		case strings.Contains(combined, "could not find service"),
+			strings.Contains(combined, "no such process"),
+			strings.Contains(combined, "not loaded"):
+			fmt.Println("  state: not loaded")
+			return
+		}
+		fmt.Printf("  error running launchctl: %v\n", err)
+		if msg := strings.TrimSpace(sout.String()); msg != "" {
+			fmt.Printf("  stdout: %s\n", msg)
+		}
+		if msg := strings.TrimSpace(serr.String()); msg != "" {
+			fmt.Printf("  stderr: %s\n", msg)
+		}
+		return
+	}
+
+	fmt.Println("  state: loaded")
+	out := strings.TrimRight(sout.String(), "\n")
+	if out == "" {
+		return
+	}
+	// Indent the launchctl output so it visually nests under "state".
+	for _, line := range strings.Split(out, "\n") {
+		fmt.Printf("  %s\n", line)
+	}
+}
+
+// printLogTail prints the last n lines of the launchd log file. A
+// missing log file is treated as "no log yet" rather than an error;
+// the file is created by launchd on the first run.
+func printLogTail(log *slog.Logger, n int) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		log.Error("status: resolve home directory failed", "err", err)
+		return
+	}
+	logPath := filepath.Join(home, "Library", "Logs", "work-cal-sync.log")
+
+	fmt.Printf("Log (last %d lines):\n", n)
+	fmt.Printf("  path: %s\n", logPath)
+
+	data, err := os.ReadFile(logPath)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			fmt.Println("  (not found — launchd creates this on first run)")
+			return
+		}
+		fmt.Printf("  error reading log: %v\n", err)
+		return
+	}
+	if len(data) == 0 {
+		fmt.Println("  (empty)")
+		return
+	}
+
+	// Trim a single trailing newline so the split doesn't produce an
+	// empty final element. Lines beyond that are preserved.
+	trimmed := strings.TrimRight(string(data), "\n")
+	lines := strings.Split(trimmed, "\n")
+	if len(lines) > n {
+		lines = lines[len(lines)-n:]
+	}
+	for _, line := range lines {
+		fmt.Printf("  %s\n", line)
+	}
+}
+
+// printUsage prints the root command help text to stdout. `--help` is a
+// normal use of the binary (not an error), so output goes to stdout
+// rather than stderr. Per REQ-1 the text must list every subcommand.
+func printUsage() {
+	const text = `work-cal-sync syncs work Exchange/O365 calendar events to a CalDAV server.
+
+Usage:
+  work-cal-sync [subcommand] [-v]
+
+Subcommands:
+  (none)            run a sync now
+  setup             interactive configuration wizard
+  install           schedule the sync via launchd (runs setup if needed)
+  uninstall         remove the launchd job and config
+  status            show config, launchd job state, and recent log lines
+  help, -h, --help  print this help text
+
+Flags:
+  -v, --verbose     enable per-event debug logging. Implied when stderr is a
+                    terminal; pass --quiet to suppress.
+  -q, --quiet       force INFO-level logging even on a terminal.
+`
+	fmt.Print(text)
+}
+
+// extractVerbosity scans args for -v/-q flags, removes them from args,
+// and returns the chosen slog level along with the cleaned slice.
+//
+// Default: if stderr is a terminal, Debug. Otherwise Info. -v forces
+// Debug, -q forces Info regardless of TTY. The TTY default keeps the
+// launchd-driven sync quiet (only INFO summaries) while making
+// interactive runs verbose enough to show progress.
+func extractVerbosity(args []string) (slog.Level, []string) {
+	level := slog.LevelInfo
+	if term.IsTerminal(int(os.Stderr.Fd())) {
+		level = slog.LevelDebug
+	}
+	out := args[:0]
+	for _, a := range args {
+		switch a {
+		case "-v", "--verbose":
+			level = slog.LevelDebug
+		case "-q", "--quiet":
+			level = slog.LevelInfo
+		default:
+			out = append(out, a)
+		}
+	}
+	return level, out
+}
+
+// newLogger constructs a slog logger emitting text to stderr at the
+// given level. Centralised so every subcommand uses the same format
+// and respects -v/-q.
+func newLogger(level slog.Level) *slog.Logger {
+	return slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: level}))
+}
+
+// ── EventKit-via-bundle helpers ────────────────────────────────────────
+//
+// macOS attaches Calendar (TCC) permissions to a bundle id, but only
+// honors them when the process was launched via Launch Services (e.g.
+// `open Foo.app`). A plain exec from a shell of the binary inside
+// Foo.app/Contents/MacOS/foo gets attributed to the shell — same
+// binary, different attribution, no permission. To work around that
+// for interactive subcommands like `setup`, we call the EventKit
+// pieces of the work in a child process launched through `open`, and
+// pass the result back via a temp JSON file.
+
+// findBundlePath returns the absolute path to work-cal-sync.app, or
+// "" if no installed bundle is found. ~/Applications wins over
+// /Applications when both exist.
+func findBundlePath() string {
+	home, err := os.UserHomeDir()
+	if err == nil {
+		p := filepath.Join(home, "Applications", "work-cal-sync.app")
+		if _, err := os.Stat(p); err == nil {
+			return p
+		}
+	}
+	p := filepath.Join("/Applications", "work-cal-sync.app")
+	if _, err := os.Stat(p); err == nil {
+		return p
+	}
+	return ""
+}
+
+// runViaBundle invokes the work-cal-sync.app bundle via `open -W -n`
+// with the given args appended after `--args`. The child process's
+// stdout and stderr are written to the supplied paths; the caller is
+// responsible for cleaning them up. The function blocks until the
+// child exits (because of `-W`).
+func runViaBundle(args []string, stdoutPath, stderrPath string) error {
+	bundle := findBundlePath()
+	if bundle == "" {
+		return errors.New(
+			"work-cal-sync.app not found in ~/Applications or /Applications. " +
+				"Run `make install-app` to install the bundle, then re-run.")
+	}
+	openArgs := []string{
+		"-W", "-n", "-a", bundle,
+		"--stdout", stdoutPath,
+		"--stderr", stderrPath,
+		"--args",
+	}
+	openArgs = append(openArgs, args...)
+	cmd := exec.Command("open", openArgs...)
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+	return cmd.Run()
+}
+
+// listCalendarsViaBundle launches the bundle to run the
+// list-calendars-internal subcommand, then reads the JSON-encoded
+// calendar list back from the temp file the child wrote.
+func listCalendarsViaBundle() ([]eventkit.Calendar, error) {
+	resultFile, err := os.CreateTemp("", "wcs-cals-*.json")
+	if err != nil {
+		return nil, fmt.Errorf("create result temp: %w", err)
+	}
+	resultPath := resultFile.Name()
+	_ = resultFile.Close()
+	defer os.Remove(resultPath)
+
+	stdoutFile, err := os.CreateTemp("", "wcs-stdout-*")
+	if err != nil {
+		return nil, err
+	}
+	stdoutPath := stdoutFile.Name()
+	_ = stdoutFile.Close()
+	defer os.Remove(stdoutPath)
+
+	stderrFile, err := os.CreateTemp("", "wcs-stderr-*")
+	if err != nil {
+		return nil, err
+	}
+	stderrPath := stderrFile.Name()
+	_ = stderrFile.Close()
+	defer os.Remove(stderrPath)
+
+	if err := runViaBundle(
+		[]string{"list-calendars-internal", resultPath},
+		stdoutPath, stderrPath,
+	); err != nil {
+		errBytes, _ := os.ReadFile(stderrPath)
+		return nil, fmt.Errorf("bundle: %w (stderr: %s)", err, strings.TrimSpace(string(errBytes)))
+	}
+
+	data, err := os.ReadFile(resultPath)
+	if err != nil {
+		return nil, fmt.Errorf("read bundle result: %w", err)
+	}
+	if len(data) == 0 {
+		errBytes, _ := os.ReadFile(stderrPath)
+		return nil, fmt.Errorf("bundle returned no calendars (stderr: %s)", strings.TrimSpace(string(errBytes)))
+	}
+
+	var out []eventkit.Calendar
+	if err := json.Unmarshal(data, &out); err != nil {
+		return nil, fmt.Errorf("decode bundle result: %w", err)
+	}
+	return out, nil
+}
+
+// fetchEventsViaBundle is the bundle-routed variant of
+// eventkit.FetchEvents, suitable for use as Engine.FetchEventKit.
+func fetchEventsViaBundle(calendarID string, start, end time.Time) ([]eventkit.Event, error) {
+	resultFile, err := os.CreateTemp("", "wcs-events-*.json")
+	if err != nil {
+		return nil, err
+	}
+	resultPath := resultFile.Name()
+	_ = resultFile.Close()
+	defer os.Remove(resultPath)
+
+	stdoutFile, _ := os.CreateTemp("", "wcs-stdout-*")
+	stdoutPath := stdoutFile.Name()
+	_ = stdoutFile.Close()
+	defer os.Remove(stdoutPath)
+
+	stderrFile, _ := os.CreateTemp("", "wcs-stderr-*")
+	stderrPath := stderrFile.Name()
+	_ = stderrFile.Close()
+	defer os.Remove(stderrPath)
+
+	args := []string{
+		"fetch-events-internal",
+		resultPath,
+		calendarID,
+		strconv.FormatInt(start.Unix(), 10),
+		strconv.FormatInt(end.Unix(), 10),
+	}
+	if err := runViaBundle(args, stdoutPath, stderrPath); err != nil {
+		errBytes, _ := os.ReadFile(stderrPath)
+		return nil, fmt.Errorf("bundle: %w (stderr: %s)", err, strings.TrimSpace(string(errBytes)))
+	}
+
+	data, err := os.ReadFile(resultPath)
+	if err != nil {
+		return nil, err
+	}
+	if len(data) == 0 {
+		return nil, nil
+	}
+	var out []eventkit.Event
+	if err := json.Unmarshal(data, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// runListCalendarsInternal is the worker side of listCalendarsViaBundle.
+// It runs inside the .app bundle (Launch Services attributes it to the
+// bundle's id, so TCC honors the Calendar grant). It calls EventKit
+// directly, then JSON-encodes the result to args[0].
+func runListCalendarsInternal(args []string) {
+	level, args := extractVerbosity(args)
+	log := newLogger(level)
+	if len(args) < 1 {
+		log.Error("list-calendars-internal: result path required")
+		os.Exit(2)
+	}
+	resultPath := args[0]
+
+	granted, err := eventkit.RequestAccess(60 * time.Second)
+	if err != nil {
+		log.Error("list-calendars-internal: request access errored", "err", err)
+		os.Exit(1)
+	}
+	if !granted {
+		log.Error("list-calendars-internal: access denied")
+		os.Exit(2)
+	}
+
+	cals, err := eventkit.ListExchangeCalendars()
+	if err != nil {
+		log.Error("list-calendars-internal: list failed", "err", err)
+		os.Exit(1)
+	}
+
+	data, err := json.Marshal(cals)
+	if err != nil {
+		log.Error("list-calendars-internal: marshal failed", "err", err)
+		os.Exit(1)
+	}
+	if err := os.WriteFile(resultPath, data, 0o600); err != nil {
+		log.Error("list-calendars-internal: write result failed", "err", err)
+		os.Exit(1)
+	}
+}
+
+// runFetchEventsInternal is the worker side of fetchEventsViaBundle.
+// args = [resultPath, calendarID, startUnix, endUnix].
+func runFetchEventsInternal(args []string) {
+	level, args := extractVerbosity(args)
+	log := newLogger(level)
+	if len(args) < 4 {
+		log.Error("fetch-events-internal: requires resultPath calID startUnix endUnix")
+		os.Exit(2)
+	}
+	resultPath := args[0]
+	calendarID := args[1]
+	startUnix, err := strconv.ParseInt(args[2], 10, 64)
+	if err != nil {
+		log.Error("fetch-events-internal: invalid start", "err", err)
+		os.Exit(2)
+	}
+	endUnix, err := strconv.ParseInt(args[3], 10, 64)
+	if err != nil {
+		log.Error("fetch-events-internal: invalid end", "err", err)
+		os.Exit(2)
+	}
+
+	granted, err := eventkit.RequestAccess(60 * time.Second)
+	if err != nil {
+		log.Error("fetch-events-internal: request access errored", "err", err)
+		os.Exit(1)
+	}
+	if !granted {
+		log.Error("fetch-events-internal: access denied")
+		os.Exit(2)
+	}
+
+	events, err := eventkit.FetchEvents(calendarID, time.Unix(startUnix, 0), time.Unix(endUnix, 0))
+	if err != nil {
+		log.Error("fetch-events-internal: fetch failed", "err", err)
+		os.Exit(1)
+	}
+
+	data, err := json.Marshal(events)
+	if err != nil {
+		log.Error("fetch-events-internal: marshal failed", "err", err)
+		os.Exit(1)
+	}
+	if err := os.WriteFile(resultPath, data, 0o600); err != nil {
+		log.Error("fetch-events-internal: write result failed", "err", err)
+		os.Exit(1)
+	}
+}
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..5f725e6
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,251 @@
+# Architecture
+
+This document explains how `work-cal-sync` is put together: the pieces, the data flow, the macOS permission model, and the wire formats. If you want to write your own tool that reads work events from macOS Calendar.app — for example, an upcoming-meeting alerter — the [Reusing the EventKit pieces](#reusing-the-eventkit-pieces) section at the bottom is the part to read.
+
+## High level
+
+```
+┌─────────────────────┐                      ┌──────────────────────┐
+│  Calendar.app       │ ──── EventKit ────▶  │  work-cal-sync.app   │
+│  Exchange/O365      │                      │  (macOS bundle)      │
+└─────────────────────┘                      │                      │
+                                             │  ┌─ EventKit cgo ───┐ │
+                                             │  ├─ Wizard / config ┤ │
+                                             │  ├─ CalDAV client ──┤ │
+                                             │  ├─ Diff engine ────┤ │
+                                             │  └─ Sync logger ────┘ │
+                                             └──────────┬───────────┘
+                                                        │ HTTPS (CalDAV)
+                                                        ▼
+                                              ┌──────────────────┐
+                                              │  CalDAV server   │
+                                              │  (iCloud /       │
+                                              │   Radicale /     │
+                                              │   Nextcloud /    │
+                                              │   Baikal …)      │
+                                              └──────────────────┘
+```
+
+A 15-minute `launchd` job invokes the binary. It reads the configured Exchange/O365 calendar from EventKit, fetches everything currently on the target CalDAV calendar, computes a three-way diff, and publishes the changes back to CalDAV.
+
+## Components
+
+### `cmd/work-cal-sync` — main binary
+
+Single Go binary with subcommand dispatch in `main.go`:
+
+| Subcommand | Purpose |
+|---|---|
+| (no arg) | Run a single sync. Path used by `launchd`. |
+| `setup` | Interactive wizard that writes config and stores password in Keychain. |
+| `install` | Generate launchd plist, write it to `~/Library/LaunchAgents`, load the job. |
+| `uninstall` | Confirm, unload, remove plist + config. Prints Keychain removal command. |
+| `status` | Show config (no password), `launchctl list` output, last 20 log lines. |
+| `request-access` | Internal helper. Used once via `open` to make TCC attribute Calendar access to the bundle. |
+| `list-calendars-internal` | Internal helper. Same purpose, called by setup to list Exchange/O365 calendars from inside the bundle. |
+| `fetch-events-internal` | Internal helper. Same purpose, called per sync to fetch events. |
+
+The three `*-internal` subcommands exist solely to work around macOS permission attribution. See [TCC and the bundle](#tcc-and-the-bundle).
+
+Flags: `-v` / `--verbose` enables per-event debug logs. `-q` / `--quiet` suppresses them. The default level is DEBUG when stderr is a terminal, INFO otherwise — interactive runs are chatty, `launchd` log files stay tidy.
+
+### `pkg/eventkit/` — Objective-C bridge
+
+A thin Objective-C bridge to Apple's EventKit framework. The Go side uses `cgo` to call three C entry points exported from `eventkit.m`:
+
+| C function | Returns |
+|---|---|
+| `wcs_authorization_status()` | Current TCC status: NotDetermined / Restricted / Denied / FullAccess / WriteOnly. |
+| `wcs_request_access(timeoutSeconds)` | Triggers the macOS permission dialog. Blocks up to `timeout`. |
+| `wcs_list_exchange_calendars(&n)` | Returns calendars where `EKCalendar.source.sourceType == EKSourceTypeExchange`. Skips holidays and birthdays. |
+| `wcs_fetch_events(calID, startUnix, endUnix, &n)` | Returns events in the given calendar over the given window. Skips events with no `calendarItemExternalIdentifier` (those can't be tracked across syncs). |
+
+The bridge:
+
+- Uses a single `EKEventStore` shared via `dispatch_once` so permission state is stable.
+- Marshals Objective-C strings as `strdup`'d UTF-8 C strings; the Go side calls `C.GoString` and `wcs_free_*` to deallocate.
+- Marshals `NSDate` ↔ `time.Time` as a `double` of unix seconds, with `0` representing "no date".
+- Treats older `requestAccessToEntityType:` and modern `requestFullAccessToEventsWithCompletion:` (macOS 14+) as interchangeable via `respondsToSelector:`.
+
+The Info.plist embedded into the binary (via `-Wl,-sectcreate`) declares `NSCalendarsFullAccessUsageDescription`. Without that, macOS silently rejects the permission request even from a bundle.
+
+### `internal/sync/` — everything else
+
+This is most of the code. Each file is a single responsibility:
+
+| File | What it does |
+|---|---|
+| `config.go` | `Config` struct + `Load()` / `Save()` / `Path()` helpers. JSON file at `~/.config/work-cal-sync/config.json`, mode `0600`, parent `0700`. |
+| `keyring.go` | `KeyringStore` interface wrapping `github.com/zalando/go-keyring`. Service name `work-cal-sync`, account = CalDAV username. |
+| `prompt.go` | Bufio-based interactive prompts: line input, password (no echo via `golang.org/x/term`), defaults, integer prompts with retries, generic numbered-list picker. |
+| `url.go` | URL validation: must be HTTPS unless host is `localhost`/`127.0.0.1`/`::1`. |
+| `wizard.go` | Sequence the wizard: pick Exchange calendar → CalDAV server URL → username → password → pick CalDAV calendar → days back/forward. Persists via `CompleteSetup`. |
+| `caldav.go` | CalDAV client: `ListCalendars`, `FetchEvents` (hand-rolled REPORT to handle iCloud quirks), `PutEvent`, `DeleteEvent`. |
+| `ical.go` | Build a `VCALENDAR`/`VEVENT` from an `eventkit.Event`. Custom `X-WORK-CAL-ID` and `X-WORK-CAL-MODIFIED` properties. RFC 5545 text escaping. |
+| `managed.go` | Parse a CalDAV `RawEvent` slice into `map[X-WORK-CAL-ID]ManagedEvent`. Returns duplicate losers separately so the engine can clean them up. |
+| `diff.go` | Compare EventKit events against the managed map. Produces `ToCreate` / `ToUpdate` / `ToDelete` slices. |
+| `sync.go` | The `Engine` that wires everything together. `Sync(ctx, cfg)` is the entry point. |
+| `plist.go` | Generate the launchd plist from a Go template. `InstallPlist`, `LoadJob`, `UnloadJob`, `RemovePlist`. |
+
+### `cmd/ekprobe` — diagnostic tool
+
+A standalone binary that asks for EventKit permission and dumps every calendar with its source type. Used during development when "no calendars found" turns out to be a TCC issue, not a code issue. Not part of the user-facing product.
+
+## Data flow
+
+A single sync run, end to end:
+
+```
+launchd timer fires
+  → exec ~/Applications/work-cal-sync.app/Contents/MacOS/work-cal-sync
+    → load ~/.config/work-cal-sync/config.json
+    → keyring.Get("work-cal-sync", username) → password
+    → fork child via `open` for EventKit fetch (TCC requires this — see below)
+        ↳ child: EKEventStore.events(matching: predicate(calendar, start, end))
+        ↳ child: JSON-encode []eventkit.Event → temp file
+        ↳ parent: read temp file, json.Unmarshal
+    → CalDAVClient.FetchEvents(targetCalendarURL)
+        ↳ REPORT request, REPORT response → []RawEvent
+        ↳ ToManagedMap → (managed map, duplicate losers)
+    → Diff(workEvents, managed) → DiffResult
+    → append duplicates to DiffResult.ToDelete
+    → for each create:    PUT /<random>.ics (BuildVCalendar(ev, ""))
+      for each update:    PUT <existing href>  (BuildVCalendar(ev, existingUID))
+      for each delete:    DELETE <href> If-Match <etag>
+    → log summary
+```
+
+Two notable details:
+
+**Why fork via `open` for the EventKit fetch.** When you exec a binary directly from a shell, macOS attributes the process to the parent shell for TCC purposes. Direct `./work-cal-sync.app/Contents/MacOS/work-cal-sync` ⟹ "this is a child of Terminal", and Terminal has no Calendar grant. Launching via `open work-cal-sync.app` ⟹ Launch Services attaches the bundle's identity, and the bundle has the grant. The parent process still drives the wizard interactively; only the EventKit fetch (which touches Calendar) runs through the `open`-launched child.
+
+**Why hand-rolled CalDAV REPORT.** `go-webdav`'s `caldav.Client.QueryCalendar` treats any property-level `404` as fatal. iCloud responds to a REPORT on an empty calendar with a 207 multistatus where the `<calendar-data>` property has status 404 — meaning "no data" rather than "error". Our hand-rolled REPORT in `caldav.go` tolerates that response and returns an empty slice.
+
+## TCC and the bundle
+
+macOS Transparency, Consent, and Control attaches Calendar permission to the **bundle id + signing identity**, and only honors it when the process was launched by Launch Services (`open Foo.app`). Bare CLI binaries cannot acquire Calendar access; only an `.app` bundle with `NSCalendarsFullAccessUsageDescription` in its Info.plist can.
+
+`make app` produces:
+
+```
+work-cal-sync.app/
+  Contents/
+    Info.plist        — declares the bundle id, NSCalendarsFullAccessUsageDescription
+    PkgInfo           — "APPL????" so Launch Services indexes the directory as a real app
+    MacOS/work-cal-sync   — the same binary as `make build`
+    _CodeSignature/   — produced by codesign
+```
+
+Signing is done with an Apple Development certificate from the local keychain so TCC keeps the grant across rebuilds. Ad-hoc signing (`codesign --sign -`) re-prompts every build because the cdhash changes. The Makefile auto-detects an Apple Development identity; override with `CODESIGN_IDENTITY="Apple Development: you (TEAMID)"`.
+
+## Wire formats
+
+### Config
+
+`~/.config/work-cal-sync/config.json` (mode 0600):
+
+```json
+{
+  "work_calendar_id": "987A751B-C453-4B3F-A95E-E2F7898935CE",
+  "work_calendar_name": "Calendar",
+  "caldav_server": "https://caldav.icloud.com",
+  "caldav_username": "you@example.com",
+  "caldav_calendar_url": "https://caldav.icloud.com/<userid>/calendars/<calid>/",
+  "days_back": 7,
+  "days_forward": 90
+}
+```
+
+The password is in the Keychain under service `work-cal-sync`, account = `caldav_username`.
+
+### iCalendar properties on managed events
+
+Every `VEVENT` we PUT carries:
+
+- `UID` — random 32-hex-char identifier (preserved across updates).
+- `DTSTAMP` — required by RFC 5545; set to `time.Now().UTC()`.
+- `SUMMARY`, `DTSTART`, `DTEND`, `LOCATION`, `DESCRIPTION` — standard properties.
+- `X-WORK-CAL-ID` — the EventKit event's `calendarItemExternalIdentifier`. This is how we match events across syncs and detect what's already on the server.
+- `X-WORK-CAL-MODIFIED` — unix timestamp of the EventKit `lastModifiedDate`, or `0` when EventKit has none. Comparison key for "did this event change since the last sync".
+
+A managed event always has both X- properties. A user-created event in the same calendar has neither, and the sync engine ignores it.
+
+### Diff semantics
+
+For each EventKit event with a non-empty external id:
+
+- if no managed event has that id → **create**
+- if a managed event with that id exists and `EventKit.LastModified.Unix() != managed.ModifiedUnix` → **update**
+- otherwise → no-op
+
+For each managed event whose id no longer appears in EventKit → **delete**.
+
+Duplicate managed events (same `X-WORK-CAL-ID`) keep the higher `ModifiedUnix` and queue the loser(s) for deletion. This repairs server state after an interrupted run.
+
+## Reusing the EventKit pieces
+
+`pkg/eventkit` is a public Go package — anything outside this repo can `go get github.com/djdead/work-cal-sync/pkg/eventkit` and use it. It exposes:
+
+```go
+package eventkit
+
+type Calendar struct {
+    Identifier  string
+    Title       string
+    SourceTitle string
+}
+
+type Event struct {
+    ExternalID   string    // calendarItemExternalIdentifier
+    Title        string    // EKEvent.title
+    Notes        string    // EKEvent.notes
+    Location     string    // EKEvent.location
+    Start        time.Time // EKEvent.startDate
+    End          time.Time // EKEvent.endDate
+    LastModified time.Time // EKEvent.lastModifiedDate
+    AllDay       bool      // EKEvent.isAllDay
+}
+
+// Permissions
+func AuthorizationStatus() int
+func RequestAccess(timeout time.Duration) (granted bool, err error)
+
+// Reads
+func ListExchangeCalendars() ([]Calendar, error)
+func FetchEvents(calendarID string, start, end time.Time) ([]Event, error)
+
+// Change notifications
+func ChangeCount() uint64
+func WaitForChange(lastSeen uint64, timeout time.Duration) uint64
+func ObserveChanges(ctx context.Context, fn func())
+```
+
+`ObserveChanges` starts a goroutine that calls `fn()` whenever EventKit posts an `EKEventStoreChangedNotification`. The Objective-C side uses a pthread mutex+condvar so the notification can come from EventKit's arbitrary worker thread without thread-safety issues on the Go side. `ChangeCount` and `WaitForChange` give you the same signal as discrete primitives if you'd rather drive your own loop.
+
+You will need a real `.app` bundle to get past TCC. A bare CLI binary cannot prompt for Calendar access on macOS 14+. Your tool will need:
+
+- An Info.plist with `NSCalendarsFullAccessUsageDescription`
+- Embedded into the binary via `-Wl,-sectcreate __TEXT __info_plist <plist>`
+- A real bundle directory under `~/Applications` with the binary at `Contents/MacOS/<name>` and a `PkgInfo` file
+- Signed with a stable identity (Apple Development cert from your keychain works)
+- Launched via `open` from Launch Services so TCC attributes correctly
+
+The full pattern is implemented in `cmd/work-cal-sync/main.go` and a more focused example in `cmd/meeting-alerter/main.go`. The latter is also a complete reusable scaffold for any "react when EventKit changes" tool.
+
+### Worked example: `cmd/meeting-alerter`
+
+The repo includes a meeting-alerter CLI that uses the same EventKit pieces to post a macOS notification a few minutes before each upcoming meeting. It demonstrates:
+
+- Importing `pkg/eventkit` from a separate command.
+- The same bundle / TCC pattern as work-cal-sync (its own `.app`, its own bundle id `tel.dead.meeting-alerter`, its own Calendar permission grant).
+- Push-style updates via the bundle-routed `wait-for-change-internal` subcommand, plus a 60-second sweep timer for events that just enter the alert window without anything having changed.
+- A minimal config wizard (calendar pick + lookahead minutes + notify-before minutes).
+- macOS Notification Center banners via `osascript display notification`, no external libraries.
+
+`make install-app-meeting-alerter && make install-meeting-alerter` builds the bundle, installs it to `~/Applications`, and copies the CLI to `~/bin`. From there:
+
+```bash
+meeting-alerter setup    # pick calendar, set lookahead/notify-before
+meeting-alerter list     # one-shot: show upcoming meetings in the horizon
+meeting-alerter watch    # long-running: post notifications as meetings approach
+```
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..485b449
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,158 @@
+# Troubleshooting
+
+Every problem we hit while building and using these tools, in roughly the order you're likely to hit them. The fix is in bold.
+
+## Permissions and TCC
+
+### "no Exchange/O365 calendars found"
+
+You're running the bare CLI binary directly — `./work-cal-sync setup` from a fresh build path, not through the bundle. macOS attributes Calendar permission to **(bundle id + cdhash + launch method)**, and a bare binary has none of that. EventKit silently returns an empty calendar list rather than throwing an error.
+
+**Fix:** install the bundle and let the wizard fork through it. `make install-app` puts `work-cal-sync.app` in `~/Applications`; `make install` puts the CLI on your `PATH`. The CLI internally uses `open` against the bundle for any EventKit call.
+
+### "calendar access not granted" / immediate denial after a request
+
+Two possible causes:
+
+1. **Stderr is being attributed to a non-bundle parent.** If you see `RequestAccess returned: 0 (denied or timed out)` immediately, with no system dialog, the binary you ran does not have an Info.plist with `NSCalendarsFullAccessUsageDescription`. macOS 14+ silently rejects access requests from binaries without that key. **Fix:** make sure you're invoking the bundled binary (`~/Applications/work-cal-sync.app/Contents/MacOS/work-cal-sync`) or the CLI shim that forks through the bundle, not the bare `./work-cal-sync` from a fresh build root.
+
+2. **You denied access earlier.** Open System Settings → Privacy & Security → Calendars and toggle the entry on. If it's not in the list, the bundle hasn't requested access yet — see "no system dialog appears" below.
+
+### "RequestAccess timed out" with no system dialog
+
+You correctly invoked the bundle (you can verify with `codesign -dvv ~/Applications/work-cal-sync.app | grep Format`, which should say `Format=app bundle with Mach-O ...`), and the bundle has the right Info.plist, but no dialog appears.
+
+This usually means TCC is cache-confused. **Fix:**
+
+```bash
+tccutil reset Calendar tel.dead.work-cal-sync
+tccutil reset Calendar tel.dead.meeting-alerter
+```
+
+(`tccutil` will say "no such bundle identifier" if there was no record — that's fine, the next launch will trigger the dialog cleanly.)
+
+### "Applications that have requested access to your calendars will appear here."
+
+The Calendars pane is showing this empty-list message and there's no `+` button. **There is no manual add path on modern macOS.** An app has to *successfully* request access via the EventKit API before it can be in this list. A bare CLI tool can't do that. **Fix:** run the bundle.
+
+### Re-prompted for Calendar access on every rebuild
+
+Bundle was signed ad-hoc (`codesign --sign -`). TCC tracks **(bundle id + cdhash)**, and the cdhash changes every build. **Fix:** sign with a stable Apple Development identity. The Makefile auto-detects one from your keychain. If you see ad-hoc signing in `make app` output, run:
+
+```bash
+security find-identity -p codesigning -v
+```
+
+If at least one `Apple Development:` row appears, the auto-detect works on next `make app`. If none, open Xcode → Settings → Accounts and add your Apple ID; that creates the dev cert.
+
+## CalDAV
+
+### `401 Unauthorized` against iCloud
+
+You're using your Apple ID password instead of an [app-specific password](https://account.apple.com). **Fix:** generate one (Sign-In and Security → App-Specific Passwords) and re-run `work-cal-sync setup`. iCloud requires an app-specific password for any third-party CalDAV client when 2FA is on, which is everyone these days.
+
+### `400 Bad Request: invalid path '/http:/host/...'`
+
+The CalDAV client was passing an absolute calendar URL to a method that expected a server-relative path. **Fixed in current code** (see `internal/sync/caldav.go::calendarPath`). If you're seeing it on a stale build, `git pull && make install-app && make install`.
+
+### `404 Not Found` on `<calendar-data>` from iCloud
+
+iCloud responds to a CalDAV REPORT on an empty calendar with a 207 multistatus where the per-property status is 404 — meaning "no data" rather than "error". The earlier code path (using `go-webdav`'s `QueryCalendar`) treated property-level 404s as fatal. **Fixed** with a hand-rolled REPORT in `internal/sync/caldav.go::FetchEvents` that tolerates the iCloud response shape.
+
+### "ical: failed to encode property value: contains a CR or LF"
+
+Real-world Outlook events have CRLF in the meeting body / DESCRIPTION. The earlier code path passed those through unescaped to go-ical, which refused to encode them. **Fixed** with `internal/sync/ical.go::sanitizeText`, which normalises to LF and emits the RFC 5545 `\n` escape directly via `setRawText` (bypassing go-ical's value-escaping path that would have double-escaped).
+
+### Hundreds of `duplicate X-WORK-CAL-ID on CalDAV server` log lines
+
+You ran sync against a calendar that already accumulated duplicates from earlier interrupted runs. The current engine treats each duplicate as a queue-for-deletion, prints a single `duplicate managed events queued for deletion count=N` summary at INFO, and removes the duplicates as part of the same sync run. After one full sync the duplicates are gone and subsequent syncs are quiet.
+
+If you'd rather start clean: delete the destination calendar in `Calendar.app`, recreate it, re-run `work-cal-sync setup` to pick the new URL, then sync.
+
+### Sync reports `created=0 updated=N deleted=0` repeatedly
+
+The `N` is the same on every run. Cause: events with no EventKit `lastModifiedDate` were comparing the year-1 negative epoch (`time.Time{}.Unix() == -62135596800`) against the persisted `0` — never equal, always queueing an update. **Fixed** in `internal/sync/diff.go::modifiedUnix`, which now normalises both sides through a "zero time → zero" helper.
+
+## Operational
+
+### `meeting-alerter list` says `bundle: exit status 1 (stderr: )`
+
+`open -W` raced the bundle and its kqueue setup failed. Recent macOS versions return non-zero in this case even though the bundle exited cleanly. **Fixed** by treating a populated result file as proof of success regardless of `open`'s exit code (`runViaBundleWithResult` in `cmd/meeting-alerter/main.go`).
+
+If you see this with `work-cal-sync` instead, it has the same fix path (`runViaBundle` in `cmd/work-cal-sync/main.go`).
+
+### `Unable to block on application (GetProcessPID() returned …)`
+
+`open -W` complaining about the same race as above. The CLI ignores it now, but the message is printed by `open` directly to your terminal — there's no good way to suppress it without losing real `open` errors. Cosmetic only.
+
+### Sync output looks like it's hung after `diff computed`
+
+It's not — the `Apply` step is doing N HTTP PUTs against a remote server. iCloud is ~200–500 ms per PUT, so a sync with 388 creates can take 60+ seconds. The default log level on a TTY is DEBUG, which gives you a per-event line for each one; otherwise you'll only see `apply: progress action=... done=25 total_actions=388` every 25 ops.
+
+Pass `-v` to force per-event lines, `-q` to suppress them and just see the summaries.
+
+### The launchd job runs but nothing happens
+
+Check the log: `tail -f ~/Library/Logs/work-cal-sync.log`. If you see no output at all, the job isn't running — `work-cal-sync status` shows the launchctl state. If you see errors, they go in this log.
+
+Common cause: the binary path baked into the plist is now wrong because you re-installed the binary somewhere else. **Fix:** `work-cal-sync install` re-resolves the binary path via `os.Executable()` and rewrites the plist.
+
+### Many duplicate notifications from `meeting-alerter`
+
+`watch` keeps a per-process `notified` map that prevents repeated alerts. If you've been Ctrl-C-ing and restarting `watch`, the in-memory state resets each time and any meeting still in the window can re-fire.
+
+If that becomes annoying, persist the map to a small JSON file. Reasonable shape:
+
+```json
+{
+  "notified": {
+    "<X-WORK-CAL-ID>": "2026-05-20T13:00Z"
+  }
+}
+```
+
+Read on startup, write on each notification, prune entries whose timestamps are in the past. Happy to add this if you want it.
+
+## Build and codesign
+
+### `invalid flag in #cgo LDFLAGS: -sectcreate`
+
+cgo's flag whitelist doesn't include `-sectcreate`. The codebase uses `-Wl,-sectcreate,...,...,...` instead, which goes through the linker driver and is allowed. If you see this error, your build is hitting the old form — `git pull` and rebuild.
+
+### `codesign … TeamIdentifier=not set`
+
+You're signing ad-hoc and didn't notice. The Makefile picks the first `Apple Development:` cert from `security find-identity` automatically. To pin one explicitly:
+
+```bash
+make app CODESIGN_IDENTITY="Apple Development: you@example.com (XXXXXXXXXX)"
+```
+
+To check what the build actually used:
+
+```bash
+codesign -dvv ~/Applications/work-cal-sync.app
+```
+
+`Authority=Apple Development: …` and `TeamIdentifier=…` should both be populated.
+
+### `Format=bundle` instead of `Format=app bundle`
+
+The Info.plist is missing `CFBundlePackageType=APPL` and/or `CFBundleExecutable`. The Makefile fixes this for the `meeting-alerter` bundle (whose Info.plist is shared with `work-cal-sync` and patched via `plutil -replace`). If you've been hand-editing the plist, make sure both keys are present.
+
+## Diagnostics
+
+`cmd/ekprobe` is a standalone diagnostic that asks for EventKit permission and dumps every calendar with its source type. It's useful when "no calendars found" turns out to be a permission issue, not a code issue:
+
+```bash
+go build -o ekprobe ./cmd/ekprobe
+./ekprobe
+```
+
+The output tells you the current authorization status, whether the access request succeeded, and the source type of each calendar EventKit can see. Source type 1 (`Exchange`) is what `work-cal-sync` filters for; Adobe O365 reports as type 1.
+
+If the Adobe / O365 calendar isn't appearing under sourceType=1, the wizard's filter would drop it. Tell us in an issue — the filter is intentionally narrow but it can be loosened.
+
+## Where to look next
+
+- For a complete end-to-end walkthrough: [user-guide.md](user-guide.md).
+- For a deeper look at how the parts fit: [architecture.md](architecture.md).
diff --git a/docs/user-guide.md b/docs/user-guide.md
new file mode 100644
index 0000000..422d0af
--- /dev/null
+++ b/docs/user-guide.md
@@ -0,0 +1,319 @@
+# User guide
+
+This is the end-to-end walkthrough for both tools in this repo:
+
+- `work-cal-sync` — copies your work Exchange/O365 calendar to a CalDAV server.
+- `meeting-alerter` — pops a macOS notification a few minutes before each upcoming meeting.
+
+They share an underlying EventKit bridge (`pkg/eventkit`) but are otherwise independent. Install whichever you need — most people will want both.
+
+If you hit any of the friction points along the way, see [troubleshooting.md](troubleshooting.md). For the why-does-it-work-this-way story, see [architecture.md](architecture.md).
+
+## Prerequisites
+
+- **macOS 13 (Ventura) or later**, Apple Silicon or Intel.
+- **Your work Exchange/O365 account** added in **System Settings → Internet Accounts**, with Calendars enabled. If you can see your work calendar in `Calendar.app`, you're set.
+- **Go 1.22+** and **Xcode Command Line Tools**:
+
+  ```bash
+  brew install go              # if you don't already have it
+  xcode-select --install        # if you don't already have CLT
+  ```
+
+- **An Apple Development code-signing identity** in your login keychain. Open Xcode → Settings → Accounts and add your Apple ID, or use any `Apple Development:` cert that `security find-identity -p codesigning -v` reports. Without this, macOS re-prompts for Calendar access on every rebuild because ad-hoc-signed binaries get a fresh code hash each time.
+
+## Install both tools
+
+One-time. Replace any prior install (Python script, earlier Go build) before doing this so you start clean.
+
+```bash
+git clone https://github.com/djdead/work-cal-sync.git
+cd work-cal-sync
+
+make install-app                  # builds work-cal-sync.app, copies to ~/Applications
+make install                      # builds the work-cal-sync CLI, copies to ~/bin
+
+make install-app-meeting-alerter  # builds meeting-alerter.app
+make install-meeting-alerter      # builds the meeting-alerter CLI
+```
+
+Make sure `~/bin` is on your `PATH`:
+
+```bash
+echo $PATH | tr : '\n' | grep -q "$HOME/bin" || echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
+```
+
+Reload your shell, then verify:
+
+```bash
+work-cal-sync help
+meeting-alerter help
+```
+
+The first run of either tool will trigger a one-time macOS Calendar-access prompt. Click **OK**. Because both bundles are code-signed with a stable identity, you only see this once per bundle.
+
+## Using `work-cal-sync`
+
+### Pick your destination CalDAV calendar
+
+You need a dedicated calendar on your CalDAV server before you start. Don't reuse your personal calendar — even though only events tagged with `X-WORK-CAL-ID` are touched, mixing 100+ work events into your personal view is unpleasant.
+
+**iCloud:**
+
+1. Open `Calendar.app`.
+2. **File → New Calendar → in iCloud → "Work Mirror"** (or whatever you prefer).
+3. Wait a few seconds for it to sync to iCloud.
+
+**Other CalDAV servers (Radicale, Nextcloud, Baikal, etc.):** create the calendar through whatever admin UI your server provides.
+
+### Get your CalDAV credentials
+
+**iCloud:** you must use an [app-specific password](https://account.apple.com), not your Apple ID password. Apple → Sign-In and Security → App-Specific Passwords → Generate Password. Name it `work-cal-sync`. Copy the 16-character string.
+
+**Other servers:** use whatever account you set up.
+
+### Run setup
+
+```bash
+work-cal-sync setup
+```
+
+The wizard asks you, in order:
+
+1. **Which calendar contains your work events?** A numbered list of Exchange/O365 calendars from your Internet Accounts. Pick the main work one (typically `Calendar` under your work account name).
+2. **CalDAV server URL.** For iCloud: `https://caldav.icloud.com`. For other servers: whatever URL they gave you. Must be HTTPS unless on `localhost`.
+3. **CalDAV username.** For iCloud: your full Apple ID email.
+4. **CalDAV password.** Hidden input. For iCloud: the app-specific password from above.
+5. **Pick the target CalDAV calendar.** A numbered list pulled live from the server. Pick your dedicated work-mirror calendar.
+6. **Sync window** — days back / days forward. Defaults are 7 / 90; press Enter to accept.
+
+Setup writes:
+
+- `~/.config/work-cal-sync/config.json` (mode 0600) with everything except the password.
+- The password into your macOS Keychain under service `work-cal-sync`, account = your CalDAV username.
+
+### First sync (manual, to verify)
+
+```bash
+work-cal-sync
+```
+
+You'll see structured logs. The interesting lines:
+
+```
+INFO sync starting work_calendar_id=… days_back=7 days_forward=90 sync_window_start=… sync_window_end=…
+INFO diff computed work_events=388 managed_events=0 creates=388 updates=0 deletes=0
+INFO apply: progress action=create done=25 total_actions=388
+…
+INFO sync complete created=388 updated=0 deleted=0 errors=0
+```
+
+Open your destination calendar in `Calendar.app`. Work events should be there.
+
+If you run the sync a second time immediately:
+
+```bash
+work-cal-sync
+# diff computed creates=0 updates=0 deletes=0
+# sync complete created=0 updated=0 deleted=0 errors=0
+```
+
+That's the steady state. The configuration is working.
+
+### Schedule it (launchd)
+
+```bash
+work-cal-sync install
+```
+
+This generates `~/Library/LaunchAgents/tel.dead.work-cal-sync.go.plist` from a built-in template, points it at the binary you ran from, and loads the job. From here, your work calendar mirrors every 15 minutes. Output goes to `~/Library/Logs/work-cal-sync.log`.
+
+Idempotent: re-run `install` after upgrading the binary (`make install`) so the plist points at the new path.
+
+### Day-to-day
+
+```bash
+work-cal-sync status      # config (sans password), launchd state, last 20 log lines
+work-cal-sync             # force a manual sync (e.g. after a meeting was just cancelled)
+work-cal-sync setup       # change the CalDAV server, target calendar, or window
+```
+
+Verbose logging:
+
+```bash
+work-cal-sync             # default DEBUG when stderr is a TTY
+work-cal-sync -q          # only INFO summaries; useful for grepping log files
+```
+
+### Uninstall
+
+```bash
+work-cal-sync uninstall
+```
+
+Removes the launchd job, plist, and config dir. Prints the `security delete-generic-password` command for the Keychain entry. **Does not** delete events already on your CalDAV server, the binary, or the bundle. To finish the cleanup:
+
+```bash
+security delete-generic-password -s work-cal-sync -a <your-caldav-username>
+rm ~/bin/work-cal-sync
+rm -rf ~/Applications/work-cal-sync.app
+```
+
+## Using `meeting-alerter`
+
+### Setup
+
+```bash
+meeting-alerter setup
+```
+
+Three questions:
+
+1. **Which calendar should I watch?** Same calendar list as `work-cal-sync` — pick the one with your real work meetings.
+2. **How many minutes ahead should I scan?** Default 60. The watcher only knows about meetings inside this window. Larger window = fewer surprises but more EventKit work per cycle. 60 is fine for most people.
+3. **How many minutes before each meeting to notify?** Default 5.
+
+Config lands at `~/.config/meeting-alerter/config.json`. No password — there's nothing sensitive.
+
+### Preview your meetings
+
+`list` prints meetings in a window. Default window is the configured lookahead from now:
+
+```bash
+meeting-alerter list
+```
+
+Override the window with flags:
+
+```bash
+meeting-alerter list --minutes 240                       # next 4 hours
+meeting-alerter list --day today                         # rest of today
+meeting-alerter list --day tomorrow                      # all of tomorrow
+meeting-alerter list --day 2026-05-25                    # specific day, full local day
+meeting-alerter list --from 2026-05-20T13:00 \
+                    --to   2026-05-20T17:00              # explicit window
+```
+
+Output groups by local date, marks all-day events, and shows location when the event has one:
+
+```
+Meetings between 2026-05-20 09:00 and 2026-05-20 18:00:
+
+Mon 2026-05-20
+  09:30   — Standup (Zoom)
+  11:00   — Design review (no location)
+  14:00   — 1:1 with Alice (Adobe SJ)
+  all-day — On-call rotation (no location)
+```
+
+This is the easiest way to sanity-check that you picked the right calendar in `setup`.
+
+### Watch
+
+```bash
+meeting-alerter watch
+```
+
+Long-running. Posts a macOS notification a few minutes before each meeting starts. Reacts to two triggers:
+
+- A 60-second sweep timer (so meetings that simply enter the window get noticed without anything having changed).
+- An `EKEventStoreChangedNotification` from EventKit (so a meeting added or moved on the Exchange side fires immediately, no polling delay).
+
+Each meeting is notified at most once per `watch` lifetime. The state is in-memory; restart the watcher and any future meeting in the window becomes fair game again. In normal operation `watch` runs for days at a stretch, so this isn't typically an issue.
+
+To stop: Ctrl-C.
+
+### Scheduling `watch` automatically
+
+There's no `meeting-alerter install` subcommand yet, but you can run it under launchd by hand. Save this as `~/Library/LaunchAgents/tel.dead.meeting-alerter.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>tel.dead.meeting-alerter</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Users/YOU/bin/meeting-alerter</string>
+        <string>watch</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/Users/YOU/Library/Logs/meeting-alerter.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/YOU/Library/Logs/meeting-alerter.log</string>
+</dict>
+</plist>
+```
+
+Replace `/Users/YOU` with your actual home, then:
+
+```bash
+launchctl load ~/Library/LaunchAgents/tel.dead.meeting-alerter.plist
+```
+
+`KeepAlive=true` (rather than the 15-minute interval `work-cal-sync` uses) because `watch` is a long-running daemon, not a periodic one-shot. macOS restarts it if it ever crashes.
+
+If you'd like a `meeting-alerter install` subcommand that does this automatically, ask and I'll add it.
+
+### Uninstall
+
+```bash
+launchctl unload ~/Library/LaunchAgents/tel.dead.meeting-alerter.plist 2>/dev/null
+rm -f ~/Library/LaunchAgents/tel.dead.meeting-alerter.plist
+rm -rf ~/.config/meeting-alerter
+rm -f ~/bin/meeting-alerter
+rm -rf ~/Applications/meeting-alerter.app
+```
+
+## Coexistence with the preserved Python implementation
+
+The Python implementation is preserved at the repo root (`work-cal-sync.py`, `setup.sh`) for users who don't want a Go toolchain. It's functionally equivalent to the Go version but is no longer the recommended path.
+
+Both can be installed at the same time. They use different launchd labels:
+
+- Python: `tel.dead.work-cal-sync`
+- Go: `tel.dead.work-cal-sync.go`
+
+so the launchd jobs don't collide.
+
+⚠️ **Do not point both implementations at the same destination CalDAV calendar.** They each claim ownership of events via the `X-WORK-CAL-ID` property. Running them simultaneously against the same calendar produces churn, duplicates, and unexpected deletes. To run them side-by-side (e.g. for a comparison), use **different destination calendars**.
+
+The Keychain entry is shared between the two (same service name, `work-cal-sync`), so storing the password once works for either. The `~/.config/work-cal-sync/config.json` file is also shared but the formats differ — running `setup` on the Go version overwrites the Python config. Back it up if you want to be able to switch back.
+
+### Migrating from Python to Go
+
+```bash
+# 1. Stop the Python launchd job so it can't race with the Go one.
+launchctl unload ~/Library/LaunchAgents/tel.dead.work-cal-sync.plist
+
+# 2. Install the Go version.
+cd /path/to/work-cal-sync
+make install-app && make install
+
+# 3. Re-run setup. The Go format diverges from Python's, so the old
+#    config is overwritten — re-enter your CalDAV URL, username, and
+#    password when prompted. The Keychain entry is reused.
+work-cal-sync setup
+
+# 4. Schedule the Go launchd job. It uses a different label, so the
+#    Python plist remains on disk but stays unloaded.
+work-cal-sync install
+
+# 5. Optional cleanup once you're confident the Go version works.
+rm ~/Library/LaunchAgents/tel.dead.work-cal-sync.plist
+rm ~/bin/work-cal-sync.py
+```
+
+## Tested combinations
+
+- macOS 15 Sequoia, M4 Pro
+- Source: Exchange Online (Adobe O365 tenant)
+- Destinations: iCloud, Radicale 3.x
+
+Other CalDAV servers that follow RFC 4791 should work. Please open an issue if you test against another.
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..370ea48
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,17 @@
+module github.com/djdead/work-cal-sync
+
+go 1.25.0
+
+require (
+	github.com/emersion/go-ical v0.0.0-20250609112844-439c63cef608
+	github.com/emersion/go-webdav v0.7.0
+	golang.org/x/term v0.43.0
+)
+
+require (
+	github.com/danieljoos/wincred v1.2.3 // indirect
+	github.com/godbus/dbus/v5 v5.2.2 // indirect
+	github.com/teambition/rrule-go v1.8.2 // indirect
+	github.com/zalando/go-keyring v0.2.8 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..ce94b2b
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,18 @@
+github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
+github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
+github.com/emersion/go-ical v0.0.0-20240127095438-fc1c9d8fb2b6/go.mod h1:BEksegNspIkjCQfmzWgsgbu6KdeJ/4LwUZs7DMBzjzw=
+github.com/emersion/go-ical v0.0.0-20250609112844-439c63cef608 h1:5XWaET4YAcppq3l1/Yh2ay5VmQjUdq6qhJuucdGbmOY=
+github.com/emersion/go-ical v0.0.0-20250609112844-439c63cef608/go.mod h1:BEksegNspIkjCQfmzWgsgbu6KdeJ/4LwUZs7DMBzjzw=
+github.com/emersion/go-vcard v0.0.0-20230815062825-8fda7d206ec9/go.mod h1:HMJKR5wlh/ziNp+sHEDV2ltblO4JD2+IdDOWtGcQBTM=
+github.com/emersion/go-webdav v0.7.0 h1:cp6aBWXBf8Sjzguka9VJarr4XTkGc2IHxXI1Gq3TKpA=
+github.com/emersion/go-webdav v0.7.0/go.mod h1:mI8iBx3RAODwX7PJJ7qzsKAKs/vY429YfS2/9wKnDbQ=
+github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
+github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
+github.com/teambition/rrule-go v1.8.2 h1:lIjpjvWTj9fFUZCmuoVDrKVOtdiyzbzc93qTmRVe/J8=
+github.com/teambition/rrule-go v1.8.2/go.mod h1:Ieq5AbrKGciP1V//Wq8ktsTXwSwJHDD5mD/wLBGl3p4=
+github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
+github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
diff --git a/internal/sync/caldav.go b/internal/sync/caldav.go
new file mode 100644
index 0000000..8e389bd
--- /dev/null
+++ b/internal/sync/caldav.go
@@ -0,0 +1,415 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"path"
+	"strconv"
+	"strings"
+
+	"github.com/emersion/go-ical"
+	"github.com/emersion/go-webdav"
+	"github.com/emersion/go-webdav/caldav"
+)
+
+// CalendarInfo describes a single calendar collection on the CalDAV server.
+type CalendarInfo struct {
+	Name string
+	URL  string
+}
+
+// RawEvent is a single calendar resource as it lives on the CalDAV server:
+// the resource href (relative path), the raw VCALENDAR bytes, and the
+// server-assigned ETag.
+type RawEvent struct {
+	Href string
+	Data []byte
+	ETag string
+}
+
+// CalDAVClient is a thin wrapper around go-webdav's caldav.Client. It adds
+// HTTP basic auth, a configurable target calendar URL, and helpers for
+// PUT/DELETE that operate on raw VCALENDAR bytes (so the iCalendar
+// encoding/decoding logic can live in a separate file).
+type CalDAVClient struct {
+	client      *caldav.Client
+	httpClient  webdav.HTTPClient
+	baseURL     *url.URL
+	calendarURL string
+}
+
+// NewCalDAVClient constructs a CalDAVClient with HTTP basic auth.
+//
+// serverURL may be either a server base URL (e.g. https://cal.example.com)
+// or a specific calendar collection URL (e.g.
+// https://cal.example.com/calendars/user/work/). The value is stored as-is;
+// callers can refine the target later via SetCalendarURL or by listing
+// calendars and selecting one.
+//
+// The constructor performs no network I/O — it only validates that the URL
+// parses. Connectivity is verified lazily on the first request.
+func NewCalDAVClient(serverURL, username, password string) (*CalDAVClient, error) {
+	if serverURL == "" {
+		return nil, errors.New("caldav: server URL is required")
+	}
+	u, err := url.Parse(serverURL)
+	if err != nil {
+		return nil, fmt.Errorf("caldav: parse server URL: %w", err)
+	}
+	if u.Scheme == "" || u.Host == "" {
+		return nil, fmt.Errorf("caldav: server URL must be absolute, got %q", serverURL)
+	}
+
+	httpClient := webdav.HTTPClientWithBasicAuth(http.DefaultClient, username, password)
+
+	cc, err := caldav.NewClient(httpClient, serverURL)
+	if err != nil {
+		return nil, fmt.Errorf("caldav: new client: %w", err)
+	}
+
+	return &CalDAVClient{
+		client:      cc,
+		httpClient:  httpClient,
+		baseURL:     u,
+		calendarURL: serverURL,
+	}, nil
+}
+
+// SetCalendarURL points subsequent FetchEvents/PutEvent/DeleteEvent calls at
+// a specific calendar collection. The value may be an absolute URL or a
+// path relative to the server.
+func (c *CalDAVClient) SetCalendarURL(u string) {
+	c.calendarURL = u
+}
+
+// CalendarURL returns the currently configured target calendar URL.
+func (c *CalDAVClient) CalendarURL() string {
+	return c.calendarURL
+}
+
+// ListCalendars discovers the calendars accessible to the authenticated
+// principal. It chains current-user-principal → calendar-home-set →
+// FindCalendars, which is the standard CalDAV discovery flow described in
+// RFC 4791 §6 and RFC 5397.
+func (c *CalDAVClient) ListCalendars(ctx context.Context) ([]CalendarInfo, error) {
+	principal, err := c.client.FindCurrentUserPrincipal(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("caldav: find current user principal: %w", err)
+	}
+	homeSet, err := c.client.FindCalendarHomeSet(ctx, principal)
+	if err != nil {
+		return nil, fmt.Errorf("caldav: find calendar home set: %w", err)
+	}
+	cals, err := c.client.FindCalendars(ctx, homeSet)
+	if err != nil {
+		return nil, fmt.Errorf("caldav: find calendars: %w", err)
+	}
+
+	out := make([]CalendarInfo, 0, len(cals))
+	for _, cal := range cals {
+		out = append(out, CalendarInfo{
+			Name: cal.Name,
+			URL:  c.absoluteURL(cal.Path),
+		})
+	}
+	return out, nil
+}
+
+// FetchEvents returns all VEVENT-bearing resources in the configured
+// target calendar.
+//
+// We hand-roll the REPORT request rather than delegating to go-webdav's
+// caldav.Client.QueryCalendar because iCloud has a particular quirk:
+// when the calendar is empty, iCloud responds with a 207 multistatus
+// containing one <response> for the collection itself, in which the
+// <calendar-data> property has status 404 Not Found. go-webdav treats
+// any property-level 404 as a fatal error, which it isn't in this case
+// — the calendar is simply empty. A hand-rolled implementation lets us
+// skip <response> entries that lack calendar-data (instead of erroring)
+// and skip the collection's own href (since it isn't an event).
+func (c *CalDAVClient) FetchEvents(ctx context.Context) ([]RawEvent, error) {
+	if c.calendarURL == "" {
+		return nil, errors.New("caldav: no calendar URL configured")
+	}
+	calPath := c.calendarPath()
+	resolved := c.absoluteURL(calPath)
+
+	const reportBody = `<?xml version="1.0" encoding="utf-8"?>
+<C:calendar-query xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">
+  <D:prop>
+    <D:getetag/>
+    <C:calendar-data/>
+  </D:prop>
+  <C:filter>
+    <C:comp-filter name="VCALENDAR">
+      <C:comp-filter name="VEVENT"/>
+    </C:comp-filter>
+  </C:filter>
+</C:calendar-query>`
+
+	req, err := http.NewRequestWithContext(ctx, "REPORT", resolved, strings.NewReader(reportBody))
+	if err != nil {
+		return nil, fmt.Errorf("caldav: build REPORT request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/xml; charset=utf-8")
+	req.Header.Set("Depth", "1")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("caldav: REPORT %s: %w", calPath, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusMultiStatus {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+		return nil, fmt.Errorf("caldav: REPORT %s: HTTP %s: %s",
+			calPath, resp.Status, strings.TrimSpace(string(body)))
+	}
+
+	var ms multiStatusResponse
+	if err := xml.NewDecoder(resp.Body).Decode(&ms); err != nil {
+		return nil, fmt.Errorf("caldav: decode REPORT response from %s: %w", calPath, err)
+	}
+
+	collectionPath := strings.TrimSuffix(calPath, "/")
+	out := make([]RawEvent, 0, len(ms.Responses))
+	for _, r := range ms.Responses {
+		// Skip the collection's own href (iCloud includes it as a
+		// "response" with calendar-data missing when the calendar is
+		// empty).
+		if strings.TrimSuffix(r.Href, "/") == collectionPath {
+			continue
+		}
+		etag, data := r.flatten()
+		// Skip entries with no event data (defensive).
+		if strings.TrimSpace(data) == "" {
+			continue
+		}
+		out = append(out, RawEvent{
+			Href: r.Href,
+			Data: []byte(data),
+			ETag: strings.Trim(etag, `"`),
+		})
+	}
+	return out, nil
+}
+
+// multiStatusResponse is the minimal subset of a CalDAV REPORT response
+// we need: a list of <response> elements each carrying an href, an
+// etag, and the calendar-data body. Property-level statuses are
+// ignored on purpose — see the comment on FetchEvents for why.
+type multiStatusResponse struct {
+	XMLName   xml.Name              `xml:"DAV: multistatus"`
+	Responses []multiStatusResource `xml:"response"`
+}
+
+// multiStatusResource captures one <response> in the REPORT result.
+// CalDAV servers return propstat groups in different shapes (everything
+// in one prop, or one prop per status), and the namespaced
+// calendar-data child can't be addressed via Go's `>`-path syntax. The
+// ETag and CalendarData fields are walked manually in flatten() below.
+type multiStatusResource struct {
+	Href     string             `xml:"href"`
+	Propstat []multiStatusPstat `xml:"propstat"`
+}
+
+type multiStatusPstat struct {
+	Prop   multiStatusProp `xml:"prop"`
+	Status string          `xml:"status"`
+}
+
+type multiStatusProp struct {
+	ETag         string             `xml:"getetag"`
+	CalendarData calendarDataInline `xml:"urn:ietf:params:xml:ns:caldav calendar-data"`
+}
+
+// calendarDataInline captures the inner XML of <calendar-data>. Using
+// InnerXML rather than CharData preserves whitespace and any nested
+// (escaped) content the iCalendar text might contain.
+type calendarDataInline struct {
+	Value string `xml:",chardata"`
+}
+
+// flatten reduces a multiStatusResource to (etag, calendar-data) by
+// scanning all propstat blocks and returning the first non-empty value
+// for each.
+func (r multiStatusResource) flatten() (etag, data string) {
+	for _, ps := range r.Propstat {
+		if etag == "" {
+			etag = ps.Prop.ETag
+		}
+		if data == "" {
+			data = ps.Prop.CalendarData.Value
+		}
+	}
+	return etag, data
+}
+
+// PutEvent uploads a VCALENDAR resource via HTTP PUT. If href is empty, a
+// random UUID-named .ics path inside the target calendar is generated. The
+// returned etag is taken from the response headers when the server provides
+// one (it may be empty for servers that omit it).
+func (c *CalDAVClient) PutEvent(ctx context.Context, href string, data []byte) (string, error) {
+	if len(data) == 0 {
+		return "", errors.New("caldav: empty event data")
+	}
+
+	target := href
+	if target == "" {
+		name, err := randomICSName()
+		if err != nil {
+			return "", err
+		}
+		target = joinCalendarPath(c.calendarURL, name)
+	}
+
+	resolved := c.absoluteURL(target)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, resolved, bytes.NewReader(data))
+	if err != nil {
+		return "", fmt.Errorf("caldav: build PUT request: %w", err)
+	}
+	req.Header.Set("Content-Type", ical.MIMEType)
+	req.ContentLength = int64(len(data))
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("caldav: PUT %s: %w", target, err)
+	}
+	defer resp.Body.Close()
+	if err := drainAndCheck(resp); err != nil {
+		return "", fmt.Errorf("caldav: PUT %s: %w", target, err)
+	}
+
+	etag := resp.Header.Get("ETag")
+	if unquoted, err := strconv.Unquote(etag); err == nil {
+		etag = unquoted
+	}
+	return etag, nil
+}
+
+// DeleteEvent removes a VCALENDAR resource. If etag is non-empty it is sent
+// in an If-Match header so the server can reject the delete if the resource
+// has changed since the caller last saw it.
+func (c *CalDAVClient) DeleteEvent(ctx context.Context, href, etag string) error {
+	if href == "" {
+		return errors.New("caldav: href is required for delete")
+	}
+	resolved := c.absoluteURL(href)
+	req, err := http.NewRequestWithContext(ctx, http.MethodDelete, resolved, nil)
+	if err != nil {
+		return fmt.Errorf("caldav: build DELETE request: %w", err)
+	}
+	if etag != "" {
+		req.Header.Set("If-Match", quoteETag(etag))
+	}
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("caldav: DELETE %s: %w", href, err)
+	}
+	defer resp.Body.Close()
+	if err := drainAndCheck(resp); err != nil {
+		return fmt.Errorf("caldav: DELETE %s: %w", href, err)
+	}
+	return nil
+}
+
+// calendarPath returns the path component of the configured calendar URL,
+// suitable for passing to go-webdav's caldav.Client methods (which expect
+// server-relative paths). If the configured value is already a relative
+// path it is returned unchanged. An empty configured value returns "".
+//
+// go-webdav builds request URLs by joining its endpoint base with the
+// supplied path; if an absolute URL is passed it gets pasted on verbatim,
+// producing a malformed request like "/http:/host/...". This helper
+// strips the scheme/host so the resulting path is well-formed.
+func (c *CalDAVClient) calendarPath() string {
+	if c.calendarURL == "" {
+		return ""
+	}
+	u, err := url.Parse(c.calendarURL)
+	if err != nil || !u.IsAbs() {
+		return c.calendarURL
+	}
+	if u.Path == "" {
+		return "/"
+	}
+	return u.Path
+}
+
+// absoluteURL resolves p (which may be a path or absolute URL) against the
+// server base URL. Absolute inputs are returned unchanged.
+func (c *CalDAVClient) absoluteURL(p string) string {
+	if p == "" {
+		return ""
+	}
+	u, err := url.Parse(p)
+	if err == nil && u.IsAbs() {
+		return p
+	}
+	if c.baseURL == nil {
+		return p
+	}
+	resolved := *c.baseURL
+	resolved.Path = p
+	resolved.RawQuery = ""
+	resolved.Fragment = ""
+	return resolved.String()
+}
+
+// joinCalendarPath appends a filename to a calendar URL or path, preserving
+// the URL's scheme/host (if any).
+func joinCalendarPath(calendarURL, name string) string {
+	if calendarURL == "" {
+		return name
+	}
+	if u, err := url.Parse(calendarURL); err == nil && u.IsAbs() {
+		u.Path = path.Join(u.Path, name)
+		return u.String()
+	}
+	if strings.HasSuffix(calendarURL, "/") {
+		return calendarURL + name
+	}
+	return calendarURL + "/" + name
+}
+
+// randomICSName returns a 16-byte hex-encoded filename ending in .ics.
+func randomICSName() (string, error) {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", fmt.Errorf("caldav: generate event name: %w", err)
+	}
+	return hex.EncodeToString(b[:]) + ".ics", nil
+}
+
+// quoteETag returns the ETag wrapped in double quotes if it isn't already.
+func quoteETag(etag string) string {
+	if strings.HasPrefix(etag, "\"") && strings.HasSuffix(etag, "\"") {
+		return etag
+	}
+	if strings.HasPrefix(etag, "W/") {
+		return etag
+	}
+	return "\"" + etag + "\""
+}
+
+// drainAndCheck consumes the response body and converts non-2xx statuses
+// into errors. The body is included in the error for easier debugging.
+func drainAndCheck(resp *http.Response) error {
+	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+		_, _ = io.Copy(io.Discard, resp.Body)
+		return nil
+	}
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+	return fmt.Errorf("HTTP %s: %s", resp.Status, strings.TrimSpace(string(body)))
+}
diff --git a/internal/sync/caldav_test.go b/internal/sync/caldav_test.go
new file mode 100644
index 0000000..f6af4d4
--- /dev/null
+++ b/internal/sync/caldav_test.go
@@ -0,0 +1,231 @@
+//go:build darwin
+
+package sync
+
+import (
+	"encoding/xml"
+	"strings"
+	"testing"
+)
+
+func TestNewCalDAVClient_ValidURL(t *testing.T) {
+	c, err := NewCalDAVClient("https://cal.example.com", "user", "pw")
+	if err != nil {
+		t.Fatalf("NewCalDAVClient error: %v", err)
+	}
+	if c == nil {
+		t.Fatal("NewCalDAVClient returned nil client")
+	}
+	if c.client == nil {
+		t.Error("internal caldav.Client is nil")
+	}
+	if got := c.CalendarURL(); got != "https://cal.example.com" {
+		t.Errorf("CalendarURL() = %q, want server URL stored as-is", got)
+	}
+}
+
+func TestNewCalDAVClient_AcceptsCalendarURL(t *testing.T) {
+	const calURL = "https://cal.example.com/calendars/user/work/"
+	c, err := NewCalDAVClient(calURL, "user", "pw")
+	if err != nil {
+		t.Fatalf("NewCalDAVClient error: %v", err)
+	}
+	if c.CalendarURL() != calURL {
+		t.Errorf("CalendarURL() = %q, want %q", c.CalendarURL(), calURL)
+	}
+}
+
+func TestNewCalDAVClient_RejectsInvalid(t *testing.T) {
+	cases := []struct {
+		name string
+		url  string
+	}{
+		{"empty", ""},
+		{"no scheme", "cal.example.com"},
+		{"scheme only", "https://"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := NewCalDAVClient(tc.url, "u", "p"); err == nil {
+				t.Errorf("NewCalDAVClient(%q) succeeded, want error", tc.url)
+			}
+		})
+	}
+}
+
+func TestSetCalendarURL(t *testing.T) {
+	c, err := NewCalDAVClient("https://cal.example.com", "u", "p")
+	if err != nil {
+		t.Fatalf("NewCalDAVClient error: %v", err)
+	}
+	c.SetCalendarURL("/calendars/user/work/")
+	if got := c.CalendarURL(); got != "/calendars/user/work/" {
+		t.Errorf("CalendarURL() = %q, want updated value", got)
+	}
+}
+
+func TestCalendarPath(t *testing.T) {
+	c, err := NewCalDAVClient("https://cal.example.com", "u", "p")
+	if err != nil {
+		t.Fatalf("NewCalDAVClient error: %v", err)
+	}
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"absolute http URL with path", "http://127.0.0.1:5232/testuser/work-mirror/", "/testuser/work-mirror/"},
+		{"absolute https URL with path", "https://cal.example.com/calendars/user/work/", "/calendars/user/work/"},
+		{"absolute URL no trailing slash", "https://cal.example.com/calendars/user/work", "/calendars/user/work"},
+		{"absolute URL bare host", "https://cal.example.com", "/"},
+		{"absolute URL bare host with slash", "https://cal.example.com/", "/"},
+		{"already path-relative", "/testuser/work-mirror/", "/testuser/work-mirror/"},
+		{"relative without leading slash", "calendars/user/work/", "calendars/user/work/"},
+		{"empty", "", ""},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c.SetCalendarURL(tc.in)
+			if got := c.calendarPath(); got != tc.want {
+				t.Errorf("calendarPath() with %q = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
+func TestJoinCalendarPath(t *testing.T) {
+	cases := []struct {
+		calURL, name, want string
+	}{
+		{"https://cal.example.com/calendars/u/work/", "abc.ics", "https://cal.example.com/calendars/u/work/abc.ics"},
+		{"https://cal.example.com/calendars/u/work", "abc.ics", "https://cal.example.com/calendars/u/work/abc.ics"},
+		{"/calendars/u/work/", "abc.ics", "/calendars/u/work/abc.ics"},
+		{"/calendars/u/work", "abc.ics", "/calendars/u/work/abc.ics"},
+	}
+	for _, tc := range cases {
+		got := joinCalendarPath(tc.calURL, tc.name)
+		if got != tc.want {
+			t.Errorf("joinCalendarPath(%q, %q) = %q, want %q", tc.calURL, tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestRandomICSName(t *testing.T) {
+	a, err := randomICSName()
+	if err != nil {
+		t.Fatalf("randomICSName error: %v", err)
+	}
+	b, err := randomICSName()
+	if err != nil {
+		t.Fatalf("randomICSName error: %v", err)
+	}
+	if a == b {
+		t.Error("randomICSName returned the same value twice")
+	}
+	if !strings.HasSuffix(a, ".ics") {
+		t.Errorf("randomICSName = %q, want .ics suffix", a)
+	}
+	// 16 bytes hex-encoded = 32 chars + .ics = 36
+	if len(a) != 36 {
+		t.Errorf("randomICSName length = %d, want 36", len(a))
+	}
+}
+
+func TestQuoteETag(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"abc", "\"abc\""},
+		{"\"abc\"", "\"abc\""},
+		{"W/\"abc\"", "W/\"abc\""},
+	}
+	for _, tc := range cases {
+		if got := quoteETag(tc.in); got != tc.want {
+			t.Errorf("quoteETag(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}
+
+// TestFetchEventsResponseDecoding_iCloudEmptyCalendar confirms that an
+// iCloud-style 207 multistatus where the only <response> entry is the
+// collection itself (with calendar-data status=404) decodes into zero
+// events without errors. Real iCloud sends this whenever a Work Mirror
+// calendar is empty, and go-webdav's QueryCalendar treats the
+// property-level 404 as fatal — which is why FetchEvents now hand-rolls
+// the REPORT.
+func TestFetchEventsResponseDecoding_iCloudEmptyCalendar(t *testing.T) {
+	const body = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<multistatus xmlns="DAV:">
+  <response>
+    <href>/173375826/calendars/D156D591-659C-47FC-8338-07F9FEEED35F/</href>
+    <propstat>
+      <prop><getetag xmlns="DAV:">"mp7qdh5s"</getetag></prop>
+      <status>HTTP/1.1 200 OK</status>
+    </propstat>
+    <propstat>
+      <prop><calendar-data xmlns="urn:ietf:params:xml:ns:caldav"/></prop>
+      <status>HTTP/1.1 404 Not Found</status>
+    </propstat>
+  </response>
+</multistatus>`
+
+	var ms multiStatusResponse
+	if err := xml.Unmarshal([]byte(body), &ms); err != nil {
+		t.Fatalf("decode iCloud empty-calendar response: %v", err)
+	}
+	if len(ms.Responses) != 1 {
+		t.Fatalf("got %d responses, want 1", len(ms.Responses))
+	}
+	r := ms.Responses[0]
+	if r.Href != "/173375826/calendars/D156D591-659C-47FC-8338-07F9FEEED35F/" {
+		t.Errorf("Href = %q, want collection path", r.Href)
+	}
+	_, data := r.flatten()
+	if strings.TrimSpace(data) != "" {
+		t.Errorf("calendar-data = %q, want empty (status was 404)", data)
+	}
+}
+
+// TestFetchEventsResponseDecoding_TypicalEvent confirms a normal
+// "got one event" response decodes its href, etag, and calendar-data.
+func TestFetchEventsResponseDecoding_TypicalEvent(t *testing.T) {
+	const body = `<?xml version="1.0" encoding="UTF-8"?>
+<multistatus xmlns="DAV:">
+  <response>
+    <href>/cal/work/abc.ics</href>
+    <propstat>
+      <prop>
+        <getetag>"etag-1"</getetag>
+        <calendar-data xmlns="urn:ietf:params:xml:ns:caldav">BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//x//y
+BEGIN:VEVENT
+UID:abc
+DTSTAMP:20240515T120000Z
+SUMMARY:Hi
+END:VEVENT
+END:VCALENDAR
+</calendar-data>
+      </prop>
+      <status>HTTP/1.1 200 OK</status>
+    </propstat>
+  </response>
+</multistatus>`
+
+	var ms multiStatusResponse
+	if err := xml.Unmarshal([]byte(body), &ms); err != nil {
+		t.Fatalf("decode typical response: %v", err)
+	}
+	if len(ms.Responses) != 1 {
+		t.Fatalf("got %d responses, want 1", len(ms.Responses))
+	}
+	r := ms.Responses[0]
+	if r.Href != "/cal/work/abc.ics" {
+		t.Errorf("Href = %q, want %q", r.Href, "/cal/work/abc.ics")
+	}
+	etag, data := r.flatten()
+	if strings.Trim(etag, `"`) != "etag-1" {
+		t.Errorf("ETag = %q, want etag-1", etag)
+	}
+	if !strings.Contains(data, "BEGIN:VEVENT") {
+		t.Errorf("calendar-data missing VEVENT: %q", data)
+	}
+}
diff --git a/internal/sync/config.go b/internal/sync/config.go
new file mode 100644
index 0000000..387beca
--- /dev/null
+++ b/internal/sync/config.go
@@ -0,0 +1,124 @@
+//go:build darwin
+
+package sync
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+)
+
+// Config holds the persistent settings for work-cal-sync. It is stored as
+// JSON at the path returned by Path().
+type Config struct {
+	WorkCalendarID    string `json:"work_calendar_id"`
+	WorkCalendarName  string `json:"work_calendar_name"`
+	CalDAVServer      string `json:"caldav_server"`
+	CalDAVUsername    string `json:"caldav_username"`
+	CalDAVCalendarURL string `json:"caldav_calendar_url"`
+	DaysBack          int    `json:"days_back"`
+	DaysForward       int    `json:"days_forward"`
+}
+
+// File-system permissions for the config directory and file. The directory
+// is restricted to the user (0700) and the file likewise (0600) since it
+// is a per-user configuration file that lives under the user's home.
+const (
+	DirPerm  os.FileMode = 0o700
+	FilePerm os.FileMode = 0o600
+)
+
+// Path returns the absolute path to the config file:
+//
+//	~/.config/work-cal-sync/config.json
+//
+// It returns an error if the user's home directory cannot be determined.
+func Path() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolve home directory: %w", err)
+	}
+	return filepath.Join(home, ".config", "work-cal-sync", "config.json"), nil
+}
+
+// Load reads and decodes the config file. If the file does not exist it
+// returns (nil, nil) so callers can treat that as a "first run" signal
+// without ambiguity.
+func Load() (*Config, error) {
+	p, err := Path()
+	if err != nil {
+		return nil, err
+	}
+
+	data, err := os.ReadFile(p)
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("read config %s: %w", p, err)
+	}
+
+	var cfg Config
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return nil, fmt.Errorf("decode config %s: %w", p, err)
+	}
+	return &cfg, nil
+}
+
+// Save writes the config to disk atomically. It ensures the parent
+// directory exists with mode DirPerm, writes the JSON (indented with two
+// spaces) to a temp file in the same directory, sets the file mode to
+// FilePerm, and renames it over the destination so a crash mid-write
+// cannot leave behind a partial file.
+func Save(cfg *Config) error {
+	if cfg == nil {
+		return errors.New("save config: cfg is nil")
+	}
+
+	p, err := Path()
+	if err != nil {
+		return err
+	}
+	dir := filepath.Dir(p)
+
+	if err := os.MkdirAll(dir, DirPerm); err != nil {
+		return fmt.Errorf("create config dir %s: %w", dir, err)
+	}
+	// MkdirAll does not adjust permissions when the directory already
+	// exists, so chmod explicitly to enforce DirPerm.
+	if err := os.Chmod(dir, DirPerm); err != nil {
+		return fmt.Errorf("chmod config dir %s: %w", dir, err)
+	}
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return fmt.Errorf("encode config: %w", err)
+	}
+
+	tmp, err := os.CreateTemp(dir, "config-*.json.tmp")
+	if err != nil {
+		return fmt.Errorf("create temp config: %w", err)
+	}
+	tmpPath := tmp.Name()
+	// Best-effort cleanup: if anything below fails before the rename, the
+	// temp file is removed. After a successful rename, removal is a no-op.
+	defer func() { _ = os.Remove(tmpPath) }()
+
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("write temp config %s: %w", tmpPath, err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close temp config %s: %w", tmpPath, err)
+	}
+	if err := os.Chmod(tmpPath, FilePerm); err != nil {
+		return fmt.Errorf("chmod temp config %s: %w", tmpPath, err)
+	}
+	if err := os.Rename(tmpPath, p); err != nil {
+		return fmt.Errorf("rename temp config to %s: %w", p, err)
+	}
+	return nil
+}
diff --git a/internal/sync/config_test.go b/internal/sync/config_test.go
new file mode 100644
index 0000000..e02fcfd
--- /dev/null
+++ b/internal/sync/config_test.go
@@ -0,0 +1,118 @@
+//go:build darwin
+
+package sync
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestPath_ReturnsExpectedLocation(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	got, err := Path()
+	if err != nil {
+		t.Fatalf("Path() error: %v", err)
+	}
+	want := filepath.Join(home, ".config", "work-cal-sync", "config.json")
+	if got != want {
+		t.Errorf("Path() = %q, want %q", got, want)
+	}
+}
+
+func TestLoad_ReturnsNilWhenFileMissing(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if cfg != nil {
+		t.Errorf("Load() = %+v, want nil for missing file", cfg)
+	}
+}
+
+func TestSaveLoad_RoundTrip(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	want := &Config{
+		WorkCalendarID:    "cal-id-123",
+		WorkCalendarName:  "Work",
+		CalDAVServer:      "https://caldav.example.com",
+		CalDAVUsername:    "user@example.com",
+		CalDAVCalendarURL: "https://caldav.example.com/calendars/user/work/",
+		DaysBack:          7,
+		DaysForward:       30,
+	}
+	if err := Save(want); err != nil {
+		t.Fatalf("Save() error: %v", err)
+	}
+
+	got, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if got == nil {
+		t.Fatal("Load() returned nil after Save()")
+	}
+	if *got != *want {
+		t.Errorf("round-trip mismatch:\n got = %+v\nwant = %+v", *got, *want)
+	}
+}
+
+func TestSave_EnforcesPermissions(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	if err := Save(&Config{DaysBack: 1, DaysForward: 1}); err != nil {
+		t.Fatalf("Save() error: %v", err)
+	}
+
+	p, err := Path()
+	if err != nil {
+		t.Fatalf("Path() error: %v", err)
+	}
+
+	dirInfo, err := os.Stat(filepath.Dir(p))
+	if err != nil {
+		t.Fatalf("stat dir: %v", err)
+	}
+	if got := dirInfo.Mode().Perm(); got != DirPerm {
+		t.Errorf("dir perm = %o, want %o", got, DirPerm)
+	}
+
+	fileInfo, err := os.Stat(p)
+	if err != nil {
+		t.Fatalf("stat file: %v", err)
+	}
+	if got := fileInfo.Mode().Perm(); got != FilePerm {
+		t.Errorf("file perm = %o, want %o", got, FilePerm)
+	}
+}
+
+func TestSave_OverwritesExistingDirWithLooserPerms(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+
+	// Pre-create the directory with overly-loose permissions to confirm
+	// Save() tightens them via os.Chmod.
+	dir := filepath.Join(home, ".config", "work-cal-sync")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+
+	if err := Save(&Config{DaysBack: 7, DaysForward: 30}); err != nil {
+		t.Fatalf("Save() error: %v", err)
+	}
+
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("stat dir: %v", err)
+	}
+	if got := info.Mode().Perm(); got != DirPerm {
+		t.Errorf("dir perm = %o, want %o", got, DirPerm)
+	}
+}
diff --git a/internal/sync/diff.go b/internal/sync/diff.go
new file mode 100644
index 0000000..37d917c
--- /dev/null
+++ b/internal/sync/diff.go
@@ -0,0 +1,98 @@
+//go:build darwin
+
+package sync
+
+import (
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// DiffPair groups a work event with the managed CalDAV event it replaces.
+// Apply uses this to PUT the new VCALENDAR bytes onto the existing href so
+// a CalDAV update keeps its server-side identity (and therefore any
+// subscribers' references to it) intact.
+type DiffPair struct {
+	Work    eventkit.Event
+	Managed ManagedEvent
+}
+
+// DiffResult enumerates the three rsync-delete actions the sync engine
+// will take during Apply: creates for events that exist on the macOS side
+// but not on CalDAV, updates for events that exist on both but whose
+// EventKit LastModified timestamp is newer than the X-WORK-CAL-MODIFIED
+// recorded on the server, and deletes for managed events whose
+// X-WORK-CAL-ID no longer appears in the macOS calendar.
+//
+// All slices are nil when empty; Apply tolerates nil slices.
+type DiffResult struct {
+	ToCreate []eventkit.Event
+	ToUpdate []DiffPair
+	ToDelete []ManagedEvent
+}
+
+// Diff compares the events fetched from EventKit against the map of
+// managed events on the CalDAV server and returns the actions needed to
+// bring CalDAV in line with EventKit.
+//
+// Matching is by ExternalID ↔ ManagedEvent.WorkID. An event is considered
+// changed when its EventKit LastModified (in unix seconds) differs from
+// the managed.ModifiedUnix recorded in the CalDAV X-WORK-CAL-MODIFIED
+// property. Equality (==) is used rather than > so that any divergence in
+// either direction triggers a re-upload — the macOS side is always the
+// source of truth, so a clock skew or manual server edit that lowers the
+// timestamp should still be corrected.
+//
+// REQ-2 calls this rsync-delete semantics: anything in managed that the
+// macOS side no longer knows about ends up in ToDelete.
+//
+// Work events with an empty ExternalID are skipped: they cannot be tracked
+// across syncs and would otherwise create duplicate CalDAV resources on
+// every run.
+// modifiedUnix returns the EventKit LastModified expressed as unix
+// seconds, with the zero time mapped to 0 instead of the year-1
+// negative epoch. This matches modifiedUnixString in ical.go (which
+// stores "0" for the zero time) so a round trip through CalDAV does
+// not appear to be a modification.
+func modifiedUnix(t time.Time) int64 {
+	if t.IsZero() {
+		return 0
+	}
+	return t.Unix()
+}
+
+func Diff(workEvents []eventkit.Event, managed map[string]ManagedEvent) DiffResult {
+	var (
+		toCreate []eventkit.Event
+		toUpdate []DiffPair
+	)
+	seen := make(map[string]struct{}, len(workEvents))
+
+	for _, ev := range workEvents {
+		if ev.ExternalID == "" {
+			continue
+		}
+		seen[ev.ExternalID] = struct{}{}
+		me, ok := managed[ev.ExternalID]
+		if !ok {
+			toCreate = append(toCreate, ev)
+			continue
+		}
+		if modifiedUnix(ev.LastModified) != me.ModifiedUnix {
+			toUpdate = append(toUpdate, DiffPair{Work: ev, Managed: me})
+		}
+	}
+
+	var toDelete []ManagedEvent
+	for id, me := range managed {
+		if _, kept := seen[id]; !kept {
+			toDelete = append(toDelete, me)
+		}
+	}
+
+	return DiffResult{
+		ToCreate: toCreate,
+		ToUpdate: toUpdate,
+		ToDelete: toDelete,
+	}
+}
diff --git a/internal/sync/diff_test.go b/internal/sync/diff_test.go
new file mode 100644
index 0000000..c76feb8
--- /dev/null
+++ b/internal/sync/diff_test.go
@@ -0,0 +1,414 @@
+//go:build darwin
+
+package sync
+
+import (
+	"context"
+	"errors"
+	"sort"
+	"testing"
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// makeWork is a small helper that builds an EventKit event with the
+// minimum fields the diff cares about.
+func makeWork(extID string, modUnix int64) eventkit.Event {
+	return eventkit.Event{
+		ExternalID:   extID,
+		Title:        "T " + extID,
+		Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+		LastModified: time.Unix(modUnix, 0),
+	}
+}
+
+// makeManaged builds a ManagedEvent with the fields the diff inspects.
+func makeManaged(extID string, modUnix int64) ManagedEvent {
+	return ManagedEvent{
+		Href:         "/cal/work/" + extID + ".ics",
+		ETag:         "etag-" + extID,
+		UID:          "uid-" + extID,
+		WorkID:       extID,
+		ModifiedUnix: modUnix,
+	}
+}
+
+func TestDiff_ClassifiesCreateUpdateDelete(t *testing.T) {
+	work := []eventkit.Event{
+		makeWork("ek-create", 1000), // not in managed → create
+		makeWork("ek-same", 2000),   // unchanged → no-op
+		makeWork("ek-change", 3000), // modified differs → update
+	}
+	managed := map[string]ManagedEvent{
+		"ek-same":   makeManaged("ek-same", 2000),
+		"ek-change": makeManaged("ek-change", 2999), // older modified
+		"ek-stale":  makeManaged("ek-stale", 1234),  // gone from EventKit → delete
+	}
+
+	got := Diff(work, managed)
+
+	if len(got.ToCreate) != 1 || got.ToCreate[0].ExternalID != "ek-create" {
+		t.Errorf("ToCreate = %+v, want one entry for ek-create", got.ToCreate)
+	}
+	if len(got.ToUpdate) != 1 ||
+		got.ToUpdate[0].Work.ExternalID != "ek-change" ||
+		got.ToUpdate[0].Managed.WorkID != "ek-change" {
+		t.Errorf("ToUpdate = %+v, want one pair for ek-change", got.ToUpdate)
+	}
+	if len(got.ToDelete) != 1 || got.ToDelete[0].WorkID != "ek-stale" {
+		t.Errorf("ToDelete = %+v, want one entry for ek-stale", got.ToDelete)
+	}
+}
+
+func TestDiff_NoChangesProducesEmptyResult(t *testing.T) {
+	work := []eventkit.Event{
+		makeWork("a", 100),
+		makeWork("b", 200),
+	}
+	managed := map[string]ManagedEvent{
+		"a": makeManaged("a", 100),
+		"b": makeManaged("b", 200),
+	}
+	got := Diff(work, managed)
+	if len(got.ToCreate) != 0 || len(got.ToUpdate) != 0 || len(got.ToDelete) != 0 {
+		t.Errorf("expected empty diff, got %+v", got)
+	}
+}
+
+func TestDiff_AllCreatesWhenManagedEmpty(t *testing.T) {
+	work := []eventkit.Event{makeWork("a", 1), makeWork("b", 2)}
+	got := Diff(work, map[string]ManagedEvent{})
+
+	if len(got.ToCreate) != 2 {
+		t.Fatalf("ToCreate len = %d, want 2", len(got.ToCreate))
+	}
+	if len(got.ToUpdate) != 0 || len(got.ToDelete) != 0 {
+		t.Errorf("expected only creates, got update=%v delete=%v", got.ToUpdate, got.ToDelete)
+	}
+}
+
+func TestDiff_AllDeletesWhenWorkEmpty(t *testing.T) {
+	managed := map[string]ManagedEvent{
+		"a": makeManaged("a", 1),
+		"b": makeManaged("b", 2),
+	}
+	got := Diff(nil, managed)
+
+	if len(got.ToDelete) != 2 {
+		t.Fatalf("ToDelete len = %d, want 2", len(got.ToDelete))
+	}
+	if len(got.ToCreate) != 0 || len(got.ToUpdate) != 0 {
+		t.Errorf("expected only deletes, got create=%v update=%v", got.ToCreate, got.ToUpdate)
+	}
+	// Map iteration order is unspecified, so sort the deletes by WorkID
+	// before asserting membership.
+	ids := []string{got.ToDelete[0].WorkID, got.ToDelete[1].WorkID}
+	sort.Strings(ids)
+	if ids[0] != "a" || ids[1] != "b" {
+		t.Errorf("ToDelete WorkIDs = %v, want [a b]", ids)
+	}
+}
+
+// TestDiff_UpdateTriggeredEvenWhenServerNewer confirms the diff treats
+// any divergence between EventKit's LastModified and the server-recorded
+// X-WORK-CAL-MODIFIED as an update, not just "EventKit is newer". The
+// macOS calendar is the source of truth, so a server-side timestamp drift
+// must still be corrected on the next sync.
+func TestDiff_UpdateTriggeredEvenWhenServerNewer(t *testing.T) {
+	work := []eventkit.Event{makeWork("a", 100)}
+	managed := map[string]ManagedEvent{
+		"a": makeManaged("a", 999), // server newer than EventKit
+	}
+	got := Diff(work, managed)
+	if len(got.ToUpdate) != 1 || got.ToUpdate[0].Work.ExternalID != "a" {
+		t.Errorf("expected update for a, got %+v", got.ToUpdate)
+	}
+}
+
+// TestDiff_SkipsWorkEventsWithoutExternalID makes sure events EventKit
+// hands us without an external identifier are dropped instead of being
+// re-created on every sync.
+func TestDiff_SkipsWorkEventsWithoutExternalID(t *testing.T) {
+	work := []eventkit.Event{
+		{ExternalID: "", Title: "no id"},
+		makeWork("a", 1),
+	}
+	managed := map[string]ManagedEvent{
+		"a": makeManaged("a", 1),
+	}
+	got := Diff(work, managed)
+	if len(got.ToCreate) != 0 || len(got.ToUpdate) != 0 || len(got.ToDelete) != 0 {
+		t.Errorf("expected empty diff (id-less event ignored, a unchanged), got %+v", got)
+	}
+}
+
+// fakePutter records each PUT call and returns canned ETags so tests can
+// assert how Apply drives its dependency.
+type fakePutter struct {
+	calls []putCall
+	err   error
+}
+type putCall struct {
+	href string
+	data []byte
+}
+
+func (f *fakePutter) Put(_ context.Context, href string, data []byte) (string, error) {
+	// Copy the data slice so later test assertions aren't fooled by a
+	// caller reusing the same buffer.
+	cp := make([]byte, len(data))
+	copy(cp, data)
+	f.calls = append(f.calls, putCall{href: href, data: cp})
+	if f.err != nil {
+		return "", f.err
+	}
+	return "etag-" + href, nil
+}
+
+// fakeDeleter records each DELETE call.
+type fakeDeleter struct {
+	calls []deleteCall
+	err   error
+}
+type deleteCall struct {
+	href string
+	etag string
+}
+
+func (f *fakeDeleter) Delete(_ context.Context, href, etag string) error {
+	f.calls = append(f.calls, deleteCall{href: href, etag: etag})
+	return f.err
+}
+
+func TestApply_DispatchesAllThreeKinds(t *testing.T) {
+	work := []eventkit.Event{
+		makeWork("ek-create", 1000),
+		makeWork("ek-change", 3000),
+	}
+	create := work[0]
+	updatePair := DiffPair{
+		Work:    work[1],
+		Managed: makeManaged("ek-change", 2999),
+	}
+	deleteMe := makeManaged("ek-stale", 1234)
+	diff := DiffResult{
+		ToCreate: []eventkit.Event{create},
+		ToUpdate: []DiffPair{updatePair},
+		ToDelete: []ManagedEvent{deleteMe},
+	}
+
+	put := &fakePutter{}
+	del := &fakeDeleter{}
+	e := &Engine{
+		Now:          time.Now,
+		PutCalDAV:    put.Put,
+		DeleteCalDAV: del.Delete,
+	}
+
+	res, err := e.Apply(context.Background(), diff)
+	if err != nil {
+		t.Fatalf("Apply: %v", err)
+	}
+	if res.Created != 1 || res.Updated != 1 || res.Deleted != 1 {
+		t.Errorf("counts = create:%d update:%d delete:%d, want 1/1/1",
+			res.Created, res.Updated, res.Deleted)
+	}
+	if len(res.Errors) != 0 {
+		t.Errorf("res.Errors = %v, want empty", res.Errors)
+	}
+
+	if len(put.calls) != 2 {
+		t.Fatalf("put calls = %d, want 2", len(put.calls))
+	}
+	// First call is the create: empty href, fresh VCALENDAR.
+	if put.calls[0].href != "" {
+		t.Errorf("create href = %q, want empty (server picks path)", put.calls[0].href)
+	}
+	// Second call is the update: targets the existing managed href and
+	// reuses the managed UID so the resource keeps its identity.
+	if put.calls[1].href != updatePair.Managed.Href {
+		t.Errorf("update href = %q, want %q", put.calls[1].href, updatePair.Managed.Href)
+	}
+	gotID, _, gotUID, perr := ParseVCalendar(put.calls[1].data)
+	if perr != nil {
+		t.Fatalf("ParseVCalendar(update payload): %v", perr)
+	}
+	if gotID != "ek-change" {
+		t.Errorf("update X-WORK-CAL-ID = %q, want ek-change", gotID)
+	}
+	if gotUID != updatePair.Managed.UID {
+		t.Errorf("update UID = %q, want %q (reuse managed UID)", gotUID, updatePair.Managed.UID)
+	}
+
+	if len(del.calls) != 1 {
+		t.Fatalf("delete calls = %d, want 1", len(del.calls))
+	}
+	if del.calls[0].href != deleteMe.Href || del.calls[0].etag != deleteMe.ETag {
+		t.Errorf("delete call = %+v, want href=%q etag=%q",
+			del.calls[0], deleteMe.Href, deleteMe.ETag)
+	}
+}
+
+func TestApply_EmptyDiffNoCalls(t *testing.T) {
+	put := &fakePutter{}
+	del := &fakeDeleter{}
+	// PutCalDAV/DeleteCalDAV deliberately left nil to confirm Apply
+	// doesn't demand them when there's nothing to do.
+	e := &Engine{Now: time.Now}
+
+	res, err := e.Apply(context.Background(), DiffResult{})
+	if err != nil {
+		t.Fatalf("Apply: %v", err)
+	}
+	if res.Created != 0 || res.Updated != 0 || res.Deleted != 0 || len(res.Errors) != 0 {
+		t.Errorf("expected zero result, got %+v", res)
+	}
+	if len(put.calls) != 0 || len(del.calls) != 0 {
+		t.Errorf("unexpected calls: put=%v del=%v", put.calls, del.calls)
+	}
+}
+
+// TestApply_CollectsErrorsAndContinues confirms a failing put or delete
+// doesn't strand the rest of the diff. Each successful action still
+// increments its counter; failures land in res.Errors.
+func TestApply_CollectsErrorsAndContinues(t *testing.T) {
+	work := []eventkit.Event{
+		makeWork("ek-1", 100),
+		makeWork("ek-2", 200),
+	}
+	diff := DiffResult{
+		ToCreate: []eventkit.Event{work[0], work[1]},
+		ToDelete: []ManagedEvent{
+			makeManaged("ek-d1", 1),
+			makeManaged("ek-d2", 2),
+		},
+	}
+
+	putErr := errors.New("server boom")
+	delErr := errors.New("server splat")
+
+	// Put fails on the first call, succeeds on the second.
+	putCount := 0
+	putFn := func(_ context.Context, href string, data []byte) (string, error) {
+		putCount++
+		if putCount == 1 {
+			return "", putErr
+		}
+		return "etag", nil
+	}
+	// Delete fails on the second call, succeeds on the first.
+	delCount := 0
+	delFn := func(_ context.Context, href, etag string) error {
+		delCount++
+		if delCount == 2 {
+			return delErr
+		}
+		return nil
+	}
+
+	e := &Engine{Now: time.Now, PutCalDAV: putFn, DeleteCalDAV: delFn}
+	res, err := e.Apply(context.Background(), diff)
+	if err != nil {
+		t.Fatalf("Apply returned err = %v, want nil (errors are collected, not returned)", err)
+	}
+	if res.Created != 1 {
+		t.Errorf("Created = %d, want 1 (one of two creates succeeded)", res.Created)
+	}
+	if res.Deleted != 1 {
+		t.Errorf("Deleted = %d, want 1 (one of two deletes succeeded)", res.Deleted)
+	}
+	if len(res.Errors) != 2 {
+		t.Fatalf("len(Errors) = %d, want 2", len(res.Errors))
+	}
+	// Confirm the wrapped errors include the underlying server failures.
+	if !errors.Is(res.Errors[0], putErr) {
+		t.Errorf("Errors[0] = %v, want chain to include %v", res.Errors[0], putErr)
+	}
+	if !errors.Is(res.Errors[1], delErr) {
+		t.Errorf("Errors[1] = %v, want chain to include %v", res.Errors[1], delErr)
+	}
+}
+
+func TestApply_RejectsBadInputs(t *testing.T) {
+	put := func(_ context.Context, _ string, _ []byte) (string, error) { return "", nil }
+	del := func(_ context.Context, _, _ string) error { return nil }
+
+	cases := []struct {
+		name string
+		eng  *Engine
+		ctx  context.Context
+		diff DiffResult
+	}{
+		{
+			name: "nil ctx",
+			eng:  &Engine{PutCalDAV: put, DeleteCalDAV: del},
+			ctx:  nil,
+			diff: DiffResult{ToCreate: []eventkit.Event{makeWork("a", 1)}},
+		},
+		{
+			name: "missing PutCalDAV with creates",
+			eng:  &Engine{DeleteCalDAV: del},
+			ctx:  context.Background(),
+			diff: DiffResult{ToCreate: []eventkit.Event{makeWork("a", 1)}},
+		},
+		{
+			name: "missing PutCalDAV with updates",
+			eng:  &Engine{DeleteCalDAV: del},
+			ctx:  context.Background(),
+			diff: DiffResult{ToUpdate: []DiffPair{{Work: makeWork("a", 2), Managed: makeManaged("a", 1)}}},
+		},
+		{
+			name: "missing DeleteCalDAV with deletes",
+			eng:  &Engine{PutCalDAV: put},
+			ctx:  context.Background(),
+			diff: DiffResult{ToDelete: []ManagedEvent{makeManaged("a", 1)}},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := tc.eng.Apply(tc.ctx, tc.diff); err == nil {
+				t.Error("expected error, got nil")
+			}
+		})
+	}
+}
+
+// TestDiff_ZeroLastModifiedRoundTrips covers the regression where
+// EventKit events with no recorded LastModified (e.g. older Exchange
+// events Outlook never re-touched) showed up as "modified" on every
+// run forever.
+//
+// The bug: BuildVCalendar serialises the zero time as "0" in the
+// X-WORK-CAL-MODIFIED property, so the parsed managed event has
+// ModifiedUnix == 0. But time.Time{}.Unix() returns the year-1
+// negative epoch (-62135596800), so the original Diff comparison
+// `ev.LastModified.Unix() != me.ModifiedUnix` was -62135596800 != 0,
+// always truthy, always queueing an update. Diff now normalises both
+// sides through modifiedUnix(), which maps the zero time to 0.
+func TestDiff_ZeroLastModifiedRoundTrips(t *testing.T) {
+	work := []eventkit.Event{
+		{
+			ExternalID:   "ek-no-modified",
+			Title:        "Old event with no modified date",
+			LastModified: time.Time{},
+		},
+	}
+	managed := map[string]ManagedEvent{
+		"ek-no-modified": {
+			Href:         "/cal/work/x.ics",
+			UID:          "uid-x",
+			WorkID:       "ek-no-modified",
+			ModifiedUnix: 0, // matches what BuildVCalendar persists
+		},
+	}
+	got := Diff(work, managed)
+	if len(got.ToUpdate) != 0 {
+		t.Errorf("expected no updates for round-tripped zero LastModified, got %d: %+v",
+			len(got.ToUpdate), got.ToUpdate)
+	}
+	if len(got.ToCreate) != 0 || len(got.ToDelete) != 0 {
+		t.Errorf("expected empty diff, got %+v", got)
+	}
+}
diff --git a/internal/sync/doc.go b/internal/sync/doc.go
new file mode 100644
index 0000000..2f78730
--- /dev/null
+++ b/internal/sync/doc.go
@@ -0,0 +1,9 @@
+//go:build darwin
+
+// Package sync implements the calendar sync engine, configuration,
+// CalDAV client, setup wizard, and launchd plist management for
+// work-cal-sync.
+//
+// This package is macOS-only because it depends on the eventkit package
+// and on launchd for scheduling.
+package sync
diff --git a/internal/sync/ical.go b/internal/sync/ical.go
new file mode 100644
index 0000000..923ced2
--- /dev/null
+++ b/internal/sync/ical.go
@@ -0,0 +1,227 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+	"github.com/emersion/go-ical"
+)
+
+// Custom iCalendar properties used to identify events that originated in the
+// macOS work calendar and to detect when they need updating. These are the
+// same X- property names used by the Python implementation so the two can,
+// in principle, read each other's events.
+const (
+	PropWorkCalID       = "X-WORK-CAL-ID"
+	PropWorkCalModified = "X-WORK-CAL-MODIFIED"
+	ProductID           = "-//work-cal-sync//EN"
+)
+
+// BuildVCalendar produces a VCALENDAR containing exactly one VEVENT for the
+// given EventKit event.
+//
+// The mapping mirrors the Python make_ical helper:
+//   - PRODID is set to the package-level ProductID, VERSION to "2.0".
+//   - SUMMARY defaults to "(No title)" when ev.Title is empty.
+//   - All-day events encode DTSTART/DTEND as DATE values; otherwise as
+//     DATE-TIME values normalised to UTC.
+//   - DESCRIPTION/LOCATION are omitted when empty.
+//   - X-WORK-CAL-ID carries the EventKit external identifier; X-WORK-CAL-
+//     MODIFIED carries the last-modified timestamp in unix seconds (or "0"
+//     when LastModified is the zero time, matching the Python sentinel for
+//     a missing date).
+//   - DTSTAMP is set to the current UTC time. RFC 5545 requires it on every
+//     VEVENT and go-ical's encoder enforces that requirement.
+//
+// uid lets the caller preserve an existing UID across updates. When uid is
+// empty a fresh 32-hex-char random identifier is generated; per RFC 5545
+// the UID just has to be globally unique, not a UUID, so a 128-bit random
+// hex string is sufficient.
+func BuildVCalendar(ev eventkit.Event, uid string) ([]byte, error) {
+	if uid == "" {
+		generated, err := newUID()
+		if err != nil {
+			return nil, err
+		}
+		uid = generated
+	}
+
+	event := ical.NewEvent()
+	event.Props.SetText(ical.PropUID, uid)
+	event.Props.SetDateTime(ical.PropDateTimeStamp, time.Now().UTC())
+
+	title := ev.Title
+	if title == "" {
+		title = "(No title)"
+	}
+	setRawText(event, ical.PropSummary, sanitizeText(title))
+
+	setEventDate(event, ical.PropDateTimeStart, ev.Start, ev.AllDay)
+	setEventDate(event, ical.PropDateTimeEnd, ev.End, ev.AllDay)
+
+	if ev.Notes != "" {
+		setRawText(event, ical.PropDescription, sanitizeText(ev.Notes))
+	}
+	if ev.Location != "" {
+		setRawText(event, ical.PropLocation, sanitizeText(ev.Location))
+	}
+
+	// Set X- properties without a value-type parameter. SetText would
+	// stamp them with VALUE=TEXT (since X- props have no default in
+	// go-ical's table), and that extra parameter doesn't appear in the
+	// Python output we're matching. For our purposes the values are
+	// opaque ASCII identifiers and integers, so no escaping is needed.
+	setRawText(event, PropWorkCalID, ev.ExternalID)
+	setRawText(event, PropWorkCalModified, modifiedUnixString(ev.LastModified))
+
+	cal := ical.NewCalendar()
+	cal.Props.SetText(ical.PropProductID, ProductID)
+	cal.Props.SetText(ical.PropVersion, "2.0")
+	cal.Children = append(cal.Children, event.Component)
+
+	var buf bytes.Buffer
+	if err := ical.NewEncoder(&buf).Encode(cal); err != nil {
+		return nil, fmt.Errorf("ical: encode calendar: %w", err)
+	}
+	return buf.Bytes(), nil
+}
+
+// ParseVCalendar walks data, finds the first VEVENT, and returns the values
+// of X-WORK-CAL-ID, X-WORK-CAL-MODIFIED (as integer unix seconds), and UID.
+//
+// Missing properties produce zero values for the corresponding return field
+// rather than an error. An error is returned only when the bytes don't
+// parse as iCalendar at all, or when X-WORK-CAL-MODIFIED is present but
+// not an integer.
+func ParseVCalendar(data []byte) (workID string, modifiedUnix int64, uid string, err error) {
+	dec := ical.NewDecoder(bytes.NewReader(data))
+	cal, err := dec.Decode()
+	if err != nil {
+		return "", 0, "", fmt.Errorf("ical: decode calendar: %w", err)
+	}
+
+	events := cal.Events()
+	if len(events) == 0 {
+		return "", 0, "", nil
+	}
+	ev := events[0]
+
+	if v, terr := ev.Props.Text(PropWorkCalID); terr == nil {
+		workID = v
+	}
+	if v, terr := ev.Props.Text(ical.PropUID); terr == nil {
+		uid = v
+	}
+	if raw, terr := ev.Props.Text(PropWorkCalModified); terr == nil && raw != "" {
+		n, perr := strconv.ParseInt(raw, 10, 64)
+		if perr != nil {
+			return workID, 0, uid, fmt.Errorf("ical: parse %s: %w", PropWorkCalModified, perr)
+		}
+		modifiedUnix = n
+	}
+	return workID, modifiedUnix, uid, nil
+}
+
+// setRawText sets a property to a literal text value without recording a
+// VALUE=TEXT parameter. go-ical's Prop.SetText helper always tags X-
+// properties with their value type (since they aren't in the default-types
+// table), but our X- properties are simple opaque ASCII strings/integers
+// that don't need that annotation, and omitting it keeps the output
+// byte-identical to what the Python implementation emits.
+func setRawText(event *ical.Event, name, value string) {
+	prop := ical.NewProp(name)
+	prop.Value = value
+	event.Props.Set(prop)
+}
+
+// sanitizeText prepares a free-form string (event title, location, notes)
+// for use as a value passed to setRawText, bypassing go-ical's
+// SetText. SetText cannot encode literal CR/LF — it errors with
+// "contains a CR or LF" — and it escapes backslashes, so we cannot
+// pre-escape CRLF as the literal "\\n" sequence and let SetText handle
+// it.
+//
+// This helper produces an iCalendar TEXT value per RFC 5545 §3.3.11:
+// CR/LF/CRLF become the two-character sequence "\\n", and
+// pre-existing backslash, comma, and semicolon characters are
+// escaped. The result is suitable for direct assignment to
+// prop.Value via setRawText.
+func sanitizeText(s string) string {
+	if s == "" {
+		return s
+	}
+	var b strings.Builder
+	b.Grow(len(s))
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		switch c {
+		case '\r':
+			// Skip CR; an immediately-following LF will emit the
+			// "\\n" itself. A bare CR (no LF) still maps to "\\n".
+			if i+1 < len(s) && s[i+1] == '\n' {
+				continue
+			}
+			b.WriteString(`\n`)
+		case '\n':
+			b.WriteString(`\n`)
+		case '\\':
+			b.WriteString(`\\`)
+		case ',':
+			b.WriteString(`\,`)
+		case ';':
+			b.WriteString(`\;`)
+		default:
+			b.WriteByte(c)
+		}
+	}
+	return b.String()
+}
+
+// setEventDate adds a DTSTART/DTEND property to event using DATE form for
+// all-day events and DATE-TIME (UTC) form otherwise. Zero times are skipped
+// — RFC 5545 makes DTSTART optional when METHOD is set, and DTEND is always
+// optional, so omitting them is preferable to encoding the time.Time zero
+// value as "00010101T000000Z".
+func setEventDate(event *ical.Event, name string, t time.Time, allDay bool) {
+	if t.IsZero() {
+		return
+	}
+	prop := ical.NewProp(name)
+	if allDay {
+		prop.SetDate(t)
+	} else {
+		prop.SetDateTime(t.UTC())
+	}
+	event.Props.Set(prop)
+}
+
+// modifiedUnixString renders the X-WORK-CAL-MODIFIED value. The zero
+// time.Time maps to "0" rather than time.Time{}.Unix() (which is a large
+// negative number for year 1) so the wire format matches the Python
+// implementation, where a missing NSDate is reported as 0.
+func modifiedUnixString(t time.Time) string {
+	if t.IsZero() {
+		return "0"
+	}
+	return strconv.FormatInt(t.Unix(), 10)
+}
+
+// newUID returns a 32-character hex string suitable for use as a VEVENT
+// UID. RFC 5545 only requires global uniqueness, so 128 random bits is more
+// than enough; using crypto/rand keeps the dependency footprint smaller
+// than pulling in a UUID package.
+func newUID() (string, error) {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		return "", fmt.Errorf("ical: generate uid: %w", err)
+	}
+	return hex.EncodeToString(b[:]), nil
+}
diff --git a/internal/sync/ical_test.go b/internal/sync/ical_test.go
new file mode 100644
index 0000000..cfefcc3
--- /dev/null
+++ b/internal/sync/ical_test.go
@@ -0,0 +1,263 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+	"github.com/emersion/go-ical"
+)
+
+// TestBuildVCalendarRoundTrip builds a VCALENDAR from a representative
+// EventKit event and parses it back, asserting that the X- properties and
+// UID survive the encode/decode cycle. This is the most important guarantee
+// for the sync engine: the work ID and modified timestamp must be readable
+// from CalDAV resources written by BuildVCalendar.
+func TestBuildVCalendarRoundTrip(t *testing.T) {
+	ev := eventkit.Event{
+		ExternalID:   "ek-external-id-123",
+		Title:        "Standup",
+		Notes:        "Daily sync\nwith line break",
+		Location:     "Zoom",
+		Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+		LastModified: time.Date(2024, 5, 14, 12, 0, 0, 0, time.UTC),
+	}
+	const wantUID = "uid-1234"
+
+	data, err := BuildVCalendar(ev, wantUID)
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+
+	gotID, gotMod, gotUID, err := ParseVCalendar(data)
+	if err != nil {
+		t.Fatalf("ParseVCalendar: %v", err)
+	}
+	if gotID != ev.ExternalID {
+		t.Errorf("workID = %q, want %q", gotID, ev.ExternalID)
+	}
+	if gotMod != ev.LastModified.Unix() {
+		t.Errorf("modifiedUnix = %d, want %d", gotMod, ev.LastModified.Unix())
+	}
+	if gotUID != wantUID {
+		t.Errorf("uid = %q, want %q", gotUID, wantUID)
+	}
+}
+
+// TestBuildVCalendarEmptyTitle confirms the Python "(No title)" fallback
+// is preserved. The wizard and sync engine rely on this default so events
+// without a subject still render usefully on the CalDAV side.
+func TestBuildVCalendarEmptyTitle(t *testing.T) {
+	ev := eventkit.Event{
+		ExternalID: "id",
+		Start:      time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 1, 1, 13, 0, 0, 0, time.UTC),
+	}
+	data, err := BuildVCalendar(ev, "uid-empty")
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+	if !bytes.Contains(data, []byte("SUMMARY:(No title)")) {
+		t.Errorf("expected SUMMARY:(No title) in output, got:\n%s", data)
+	}
+}
+
+// TestBuildVCalendarAllDay verifies that all-day events use DATE values
+// (no time component). RFC 5545 §3.6.1 requires this for events that span
+// whole days; without it, CalDAV clients render them at midnight UTC in
+// the local time zone and they appear on the wrong day.
+func TestBuildVCalendarAllDay(t *testing.T) {
+	ev := eventkit.Event{
+		ExternalID: "id-allday",
+		Title:      "Conference",
+		Start:      time.Date(2024, 6, 1, 0, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 6, 3, 0, 0, 0, 0, time.UTC),
+		AllDay:     true,
+	}
+	data, err := BuildVCalendar(ev, "uid-allday")
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+
+	cal, err := ical.NewDecoder(bytes.NewReader(data)).Decode()
+	if err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	events := cal.Events()
+	if len(events) != 1 {
+		t.Fatalf("got %d events, want 1", len(events))
+	}
+	dtstart := events[0].Props.Get(ical.PropDateTimeStart)
+	if dtstart == nil {
+		t.Fatal("missing DTSTART")
+	}
+	if dtstart.ValueType() != ical.ValueDate {
+		t.Errorf("DTSTART value type = %q, want %q (all-day events must be DATE)",
+			dtstart.ValueType(), ical.ValueDate)
+	}
+	// Sanity: DATE values are 8 chars (YYYYMMDD), with no "T".
+	if strings.Contains(dtstart.Value, "T") {
+		t.Errorf("DTSTART value %q contains a time component, want DATE only",
+			dtstart.Value)
+	}
+}
+
+// TestParseVCalendarBadInput confirms that obviously non-iCal bytes cause
+// ParseVCalendar to return an error rather than silently returning zero
+// values. Missing X- properties are not errors (covered separately), but
+// undecodable input should be surfaced.
+func TestParseVCalendarBadInput(t *testing.T) {
+	cases := [][]byte{
+		[]byte(""),
+		[]byte("not a calendar at all"),
+		[]byte("BEGIN:VCALENDAR\r\n"), // truncated, missing END
+	}
+	for i, data := range cases {
+		if _, _, _, err := ParseVCalendar(data); err == nil {
+			t.Errorf("case %d: ParseVCalendar succeeded on bad input %q, want error", i, data)
+		}
+	}
+}
+
+// TestParseVCalendarMissingProps verifies that missing X-WORK-CAL-ID and
+// X-WORK-CAL-MODIFIED produce zero-valued returns instead of errors. The
+// sync engine uses this behaviour to detect events on the CalDAV server
+// that were not created by work-cal-sync (and should therefore be skipped).
+func TestParseVCalendarMissingProps(t *testing.T) {
+	const minimal = "BEGIN:VCALENDAR\r\n" +
+		"VERSION:2.0\r\n" +
+		"PRODID:-//test//EN\r\n" +
+		"BEGIN:VEVENT\r\n" +
+		"UID:only-uid\r\n" +
+		"DTSTAMP:20240515T120000Z\r\n" +
+		"END:VEVENT\r\n" +
+		"END:VCALENDAR\r\n"
+
+	id, mod, uid, err := ParseVCalendar([]byte(minimal))
+	if err != nil {
+		t.Fatalf("ParseVCalendar: %v", err)
+	}
+	if id != "" {
+		t.Errorf("workID = %q, want empty", id)
+	}
+	if mod != 0 {
+		t.Errorf("modifiedUnix = %d, want 0", mod)
+	}
+	if uid != "only-uid" {
+		t.Errorf("uid = %q, want %q", uid, "only-uid")
+	}
+}
+
+// TestBuildVCalendarZeroModified confirms the Python sentinel: a zero
+// LastModified time renders as "0", not as a stringified large negative
+// year-1 unix timestamp. This is what the Python implementation emits and
+// what ParseVCalendar expects to round-trip cleanly.
+func TestBuildVCalendarZeroModified(t *testing.T) {
+	ev := eventkit.Event{
+		ExternalID: "id",
+		Title:      "Some event",
+		Start:      time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 1, 1, 13, 0, 0, 0, time.UTC),
+	}
+	data, err := BuildVCalendar(ev, "uid")
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+	if !bytes.Contains(data, []byte("X-WORK-CAL-MODIFIED:0")) {
+		t.Errorf("expected X-WORK-CAL-MODIFIED:0, got:\n%s", data)
+	}
+}
+
+// TestBuildVCalendar_MultilineNotes covers the regression where Outlook
+// /Exchange events carrying CRLF inside DESCRIPTION made BuildVCalendar
+// fail with "ical: failed to encode property value: contains a CR or LF".
+// All variants of vertical whitespace must round-trip through encode and
+// decode cleanly, with the parsed DESCRIPTION rejoining the original
+// lines using LF.
+func TestBuildVCalendar_MultilineNotes(t *testing.T) {
+	cases := []struct {
+		name  string
+		notes string
+	}{
+		{"crlf", "line one\r\nline two\r\nline three"},
+		{"lf", "line one\nline two\nline three"},
+		{"cr", "line one\rline two\rline three"},
+		{"mixed", "one\r\ntwo\nthree\rfour"},
+		{"trailing crlf", "single\r\n"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			ev := eventkit.Event{
+				ExternalID: "id-multiline-" + tc.name,
+				Title:      "Subj",
+				Notes:      tc.notes,
+				Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+				End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+			}
+			data, err := BuildVCalendar(ev, "")
+			if err != nil {
+				t.Fatalf("BuildVCalendar with %s notes: %v", tc.name, err)
+			}
+
+			cal, err := ical.NewDecoder(bytes.NewReader(data)).Decode()
+			if err != nil {
+				t.Fatalf("decode round-trip: %v", err)
+			}
+			events := cal.Events()
+			if len(events) != 1 {
+				t.Fatalf("got %d events, want 1", len(events))
+			}
+			desc, _ := events[0].Props.Text(ical.PropDescription)
+			// After decoding, RFC 5545's "\\n" should turn back into
+			// LF. We don't require CRLF preservation — RFC 5545
+			// canonicalises to LF.
+			lfNotes := strings.ReplaceAll(strings.ReplaceAll(tc.notes, "\r\n", "\n"), "\r", "\n")
+			if desc != lfNotes {
+				t.Errorf("decoded DESCRIPTION = %q, want %q", desc, lfNotes)
+			}
+		})
+	}
+}
+
+// TestBuildVCalendar_MultilineSummaryAndLocation guards against the same
+// CR/LF bug for SUMMARY and LOCATION. Outlook events have been seen with
+// embedded newlines in titles (rare) and locations (when an address has
+// been pasted with line breaks).
+func TestBuildVCalendar_MultilineSummaryAndLocation(t *testing.T) {
+	ev := eventkit.Event{
+		ExternalID: "id-newlines-everywhere",
+		Title:      "Multi\r\nLine\r\nTitle",
+		Location:   "123 Main St\r\nSuite 100\r\nAnytown, USA",
+		Notes:      "body line 1\r\nbody line 2",
+		Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}
+	data, err := BuildVCalendar(ev, "")
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+	cal, err := ical.NewDecoder(bytes.NewReader(data)).Decode()
+	if err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+	events := cal.Events()
+	if len(events) != 1 {
+		t.Fatalf("got %d events, want 1", len(events))
+	}
+	got := events[0]
+	for prop, want := range map[string]string{
+		ical.PropSummary:     "Multi\nLine\nTitle",
+		ical.PropLocation:    "123 Main St\nSuite 100\nAnytown, USA",
+		ical.PropDescription: "body line 1\nbody line 2",
+	} {
+		v, _ := got.Props.Text(prop)
+		if v != want {
+			t.Errorf("%s = %q, want %q", prop, v, want)
+		}
+	}
+}
diff --git a/internal/sync/keyring.go b/internal/sync/keyring.go
new file mode 100644
index 0000000..9184eaa
--- /dev/null
+++ b/internal/sync/keyring.go
@@ -0,0 +1,54 @@
+//go:build darwin
+
+package sync
+
+import (
+	"github.com/zalando/go-keyring"
+)
+
+// KeyringService is the service name registered with the macOS Keychain.
+// All work-cal-sync credentials are filed under this name; the per-user
+// account name is the CalDAV username from Config.
+const KeyringService = "work-cal-sync"
+
+// KeyringStore abstracts password storage so the wizard and sync engine
+// can run against an in-memory fake in tests instead of touching the
+// real Keychain.
+type KeyringStore interface {
+	Get(account string) (string, error)
+	Set(account, password string) error
+	Delete(account string) error
+}
+
+// realKeyringStore wraps github.com/zalando/go-keyring and stores all
+// secrets under the KeyringService service name.
+//
+// On macOS this resolves to a generic password entry in the user's
+// login.keychain (Keychain Access shows it under "Passwords"). The
+// underlying library uses the Security.framework SecKeychain* APIs, so
+// access prompts behave the same as any other native Keychain client.
+type realKeyringStore struct{}
+
+// NewKeyringStore returns a KeyringStore backed by the real macOS
+// Keychain via go-keyring. Use this in production; tests should
+// substitute a fake to avoid prompting the user or polluting their
+// Keychain.
+func NewKeyringStore() KeyringStore {
+	return realKeyringStore{}
+}
+
+// Get retrieves the password stored for account under KeyringService.
+func (realKeyringStore) Get(account string) (string, error) {
+	return keyring.Get(KeyringService, account)
+}
+
+// Set stores password for account under KeyringService, replacing any
+// existing entry.
+func (realKeyringStore) Set(account, password string) error {
+	return keyring.Set(KeyringService, account, password)
+}
+
+// Delete removes the entry for account under KeyringService.
+func (realKeyringStore) Delete(account string) error {
+	return keyring.Delete(KeyringService, account)
+}
diff --git a/internal/sync/keyring_test.go b/internal/sync/keyring_test.go
new file mode 100644
index 0000000..2b6cc9c
--- /dev/null
+++ b/internal/sync/keyring_test.go
@@ -0,0 +1,111 @@
+//go:build darwin
+
+package sync
+
+import (
+	"errors"
+	"sync"
+	"testing"
+)
+
+// fakeKeyringStore is an in-memory KeyringStore used by tests so they
+// never touch the real macOS Keychain. It is concurrency-safe so a
+// single instance can be shared across goroutines without surprises.
+type fakeKeyringStore struct {
+	mu      sync.Mutex
+	entries map[string]string
+}
+
+// newFakeKeyringStore returns an empty fakeKeyringStore.
+func newFakeKeyringStore() *fakeKeyringStore {
+	return &fakeKeyringStore{entries: map[string]string{}}
+}
+
+// Compile-time assertion: fakeKeyringStore satisfies KeyringStore.
+var _ KeyringStore = (*fakeKeyringStore)(nil)
+
+// errKeyringEntryNotFound is returned by Get/Delete when no entry exists
+// for the requested account. It mirrors go-keyring's ErrNotFound
+// semantics closely enough for tests without dragging in the dependency.
+var errKeyringEntryNotFound = errors.New("keyring: entry not found")
+
+func (f *fakeKeyringStore) Get(account string) (string, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	v, ok := f.entries[account]
+	if !ok {
+		return "", errKeyringEntryNotFound
+	}
+	return v, nil
+}
+
+func (f *fakeKeyringStore) Set(account, password string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	f.entries[account] = password
+	return nil
+}
+
+func (f *fakeKeyringStore) Delete(account string) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if _, ok := f.entries[account]; !ok {
+		return errKeyringEntryNotFound
+	}
+	delete(f.entries, account)
+	return nil
+}
+
+func TestFakeKeyringStore_RoundTrip(t *testing.T) {
+	ks := newFakeKeyringStore()
+
+	if _, err := ks.Get("alice"); !errors.Is(err, errKeyringEntryNotFound) {
+		t.Errorf("Get on empty store err = %v, want errKeyringEntryNotFound", err)
+	}
+
+	if err := ks.Set("alice", "hunter2"); err != nil {
+		t.Fatalf("Set() error: %v", err)
+	}
+	got, err := ks.Get("alice")
+	if err != nil {
+		t.Fatalf("Get() error: %v", err)
+	}
+	if got != "hunter2" {
+		t.Errorf("Get() = %q, want %q", got, "hunter2")
+	}
+
+	// Set should replace the existing value.
+	if err := ks.Set("alice", "newpass"); err != nil {
+		t.Fatalf("Set() replace error: %v", err)
+	}
+	got, err = ks.Get("alice")
+	if err != nil {
+		t.Fatalf("Get() after replace error: %v", err)
+	}
+	if got != "newpass" {
+		t.Errorf("Get() after replace = %q, want %q", got, "newpass")
+	}
+
+	if err := ks.Delete("alice"); err != nil {
+		t.Fatalf("Delete() error: %v", err)
+	}
+	if _, err := ks.Get("alice"); !errors.Is(err, errKeyringEntryNotFound) {
+		t.Errorf("Get after Delete err = %v, want errKeyringEntryNotFound", err)
+	}
+	if err := ks.Delete("alice"); !errors.Is(err, errKeyringEntryNotFound) {
+		t.Errorf("Delete on missing err = %v, want errKeyringEntryNotFound", err)
+	}
+}
+
+func TestNewKeyringStore_ReturnsRealStore(t *testing.T) {
+	// Sanity-check that the production constructor wires up a non-nil
+	// implementation. We deliberately do NOT call Get/Set/Delete on it
+	// because that would hit the user's real Keychain.
+	ks := NewKeyringStore()
+	if ks == nil {
+		t.Fatal("NewKeyringStore() returned nil")
+	}
+	if _, ok := ks.(realKeyringStore); !ok {
+		t.Errorf("NewKeyringStore() returned %T, want realKeyringStore", ks)
+	}
+}
diff --git a/internal/sync/managed.go b/internal/sync/managed.go
new file mode 100644
index 0000000..c082355
--- /dev/null
+++ b/internal/sync/managed.go
@@ -0,0 +1,96 @@
+//go:build darwin
+
+package sync
+
+import (
+	"log/slog"
+)
+
+// ManagedEvent represents an event on the CalDAV server that was previously
+// created by work-cal-sync (i.e., it has an X-WORK-CAL-ID property). The
+// diff stage uses these as the "what's already there" side of the rsync-
+// delete computation.
+type ManagedEvent struct {
+	Href         string
+	ETag         string
+	UID          string
+	WorkID       string
+	ModifiedUnix int64
+}
+
+// ToManagedMap converts a slice of RawEvents into a map keyed by the
+// X-WORK-CAL-ID property value, along with a list of "loser" hrefs:
+// resources that share an X-WORK-CAL-ID with a kept event and are
+// therefore duplicates that should be deleted from the server. The
+// engine appends these to the diff's ToDelete so a sync run repairs the
+// state by removing duplicates instead of just logging about them.
+//
+// Behaviour:
+//   - Events that fail to parse log a warning and are skipped.
+//   - Events without an X-WORK-CAL-ID are skipped silently.
+//   - When two events share an X-WORK-CAL-ID, the one with the higher
+//     ModifiedUnix wins. The losing event's href + etag is added to the
+//     duplicates slice. A debug-level line records the choice.
+//   - A single info-level summary is emitted at the end when any
+//     duplicates were found, so operators see the cleanup activity at
+//     the default log level without per-event spam.
+//
+// A nil logger is replaced with slog.Default() so callers don't have
+// to construct one for simple cases.
+func ToManagedMap(raw []RawEvent, log *slog.Logger) (map[string]ManagedEvent, []ManagedEvent) {
+	if log == nil {
+		log = slog.Default()
+	}
+
+	out := make(map[string]ManagedEvent, len(raw))
+	var duplicates []ManagedEvent
+	for _, r := range raw {
+		workID, modifiedUnix, uid, err := ParseVCalendar(r.Data)
+		if err != nil {
+			log.Warn("skipping unparseable CalDAV event",
+				"href", r.Href,
+				"err", err,
+			)
+			continue
+		}
+		if workID == "" {
+			// Not one of ours; leave it alone.
+			continue
+		}
+
+		candidate := ManagedEvent{
+			Href:         r.Href,
+			ETag:         r.ETag,
+			UID:          uid,
+			WorkID:       workID,
+			ModifiedUnix: modifiedUnix,
+		}
+
+		if existing, ok := out[workID]; ok {
+			winner := candidate
+			loser := existing
+			if existing.ModifiedUnix >= candidate.ModifiedUnix {
+				winner = existing
+				loser = candidate
+			}
+			log.Debug("duplicate X-WORK-CAL-ID on CalDAV server; keeping later event",
+				"work_id", workID,
+				"kept_href", winner.Href,
+				"kept_modified_unix", winner.ModifiedUnix,
+				"discarded_href", loser.Href,
+				"discarded_modified_unix", loser.ModifiedUnix,
+			)
+			duplicates = append(duplicates, loser)
+			out[workID] = winner
+			continue
+		}
+		out[workID] = candidate
+	}
+
+	if len(duplicates) > 0 {
+		log.Info("duplicate managed events queued for deletion",
+			"count", len(duplicates))
+	}
+
+	return out, duplicates
+}
diff --git a/internal/sync/managed_test.go b/internal/sync/managed_test.go
new file mode 100644
index 0000000..446b3e7
--- /dev/null
+++ b/internal/sync/managed_test.go
@@ -0,0 +1,266 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"io"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// discardLogger returns a slog.Logger that throws away its output. Most of
+// these tests don't care about log output and just want a non-nil logger
+// to avoid spamming stderr.
+func discardLogger() *slog.Logger {
+	return slog.New(slog.NewTextHandler(io.Discard, nil))
+}
+
+// buildRawEvent is a small helper that produces a RawEvent from an
+// eventkit.Event by routing through BuildVCalendar. Keeping the helper
+// here means the tests exercise the same encoding path the sync engine
+// will use in production.
+func buildRawEvent(t *testing.T, ev eventkit.Event, uid, href, etag string) RawEvent {
+	t.Helper()
+	data, err := BuildVCalendar(ev, uid)
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+	return RawEvent{Href: href, Data: data, ETag: etag}
+}
+
+// TestToManagedMap_KeysByWorkID confirms the happy path: several distinct
+// events round-trip into a map keyed by their X-WORK-CAL-ID and each entry
+// preserves the href, etag, UID, and modified timestamp.
+func TestToManagedMap_KeysByWorkID(t *testing.T) {
+	mod := time.Date(2024, 5, 15, 10, 0, 0, 0, time.UTC)
+	events := []struct {
+		extID, uid, href, etag string
+	}{
+		{"ek-1", "uid-1", "/cal/work/1.ics", "etag-1"},
+		{"ek-2", "uid-2", "/cal/work/2.ics", "etag-2"},
+		{"ek-3", "uid-3", "/cal/work/3.ics", "etag-3"},
+	}
+
+	raws := make([]RawEvent, 0, len(events))
+	for _, e := range events {
+		raws = append(raws, buildRawEvent(t, eventkit.Event{
+			ExternalID:   e.extID,
+			Title:        "Title " + e.extID,
+			Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+			End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+			LastModified: mod,
+		}, e.uid, "", ""))
+		raws[len(raws)-1].Href = e.href
+		raws[len(raws)-1].ETag = e.etag
+	}
+
+	got, _ := ToManagedMap(raws, discardLogger())
+	if len(got) != len(events) {
+		t.Fatalf("len(map) = %d, want %d", len(got), len(events))
+	}
+	for _, e := range events {
+		me, ok := got[e.extID]
+		if !ok {
+			t.Errorf("missing key %q", e.extID)
+			continue
+		}
+		if me.Href != e.href {
+			t.Errorf("%s: Href = %q, want %q", e.extID, me.Href, e.href)
+		}
+		if me.ETag != e.etag {
+			t.Errorf("%s: ETag = %q, want %q", e.extID, me.ETag, e.etag)
+		}
+		if me.UID != e.uid {
+			t.Errorf("%s: UID = %q, want %q", e.extID, me.UID, e.uid)
+		}
+		if me.WorkID != e.extID {
+			t.Errorf("%s: WorkID = %q, want %q", e.extID, me.WorkID, e.extID)
+		}
+		if me.ModifiedUnix != mod.Unix() {
+			t.Errorf("%s: ModifiedUnix = %d, want %d", e.extID, me.ModifiedUnix, mod.Unix())
+		}
+	}
+}
+
+// TestToManagedMap_SkipsEventsWithoutWorkID confirms that VCALENDARs we
+// didn't author (no X-WORK-CAL-ID) are dropped from the map. Without this
+// guard, the sync engine would treat foreign events as managed and delete
+// them on the next pass.
+func TestToManagedMap_SkipsEventsWithoutWorkID(t *testing.T) {
+	const foreign = "BEGIN:VCALENDAR\r\n" +
+		"VERSION:2.0\r\n" +
+		"PRODID:-//someone-else//EN\r\n" +
+		"BEGIN:VEVENT\r\n" +
+		"UID:not-ours\r\n" +
+		"DTSTAMP:20240515T120000Z\r\n" +
+		"SUMMARY:User-created event\r\n" +
+		"END:VEVENT\r\n" +
+		"END:VCALENDAR\r\n"
+
+	managed := buildRawEvent(t, eventkit.Event{
+		ExternalID: "ek-managed",
+		Title:      "Managed",
+		Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-managed", "/cal/work/managed.ics", "etag-m")
+
+	raws := []RawEvent{
+		{Href: "/cal/work/foreign.ics", Data: []byte(foreign), ETag: "etag-f"},
+		managed,
+	}
+
+	got, _ := ToManagedMap(raws, discardLogger())
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1 (foreign event should be skipped)", len(got))
+	}
+	if _, ok := got["ek-managed"]; !ok {
+		t.Errorf("expected key ek-managed in map, got %v", got)
+	}
+}
+
+// TestToManagedMap_DuplicateWorkIDLaterWins covers the duplicate-detection
+// branch: two CalDAV resources with the same X-WORK-CAL-ID resolve to the
+// one with the higher ModifiedUnix and the loser gets logged at info level.
+func TestToManagedMap_DuplicateWorkIDLaterWins(t *testing.T) {
+	const sharedID = "ek-dup"
+	older := buildRawEvent(t, eventkit.Event{
+		ExternalID:   sharedID,
+		Title:        "Older",
+		Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+		LastModified: time.Date(2024, 5, 14, 8, 0, 0, 0, time.UTC),
+	}, "uid-older", "/cal/work/older.ics", "etag-older")
+	newer := buildRawEvent(t, eventkit.Event{
+		ExternalID:   sharedID,
+		Title:        "Newer",
+		Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+		LastModified: time.Date(2024, 5, 16, 8, 0, 0, 0, time.UTC),
+	}, "uid-newer", "/cal/work/newer.ics", "etag-newer")
+
+	// Capture log output so we can assert the duplicate message fires.
+	var logBuf bytes.Buffer
+	log := slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelInfo}))
+
+	// Insert older first so we exercise the "candidate is newer than
+	// existing" replacement branch.
+	got, _ := ToManagedMap([]RawEvent{older, newer}, log)
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1", len(got))
+	}
+	winner, ok := got[sharedID]
+	if !ok {
+		t.Fatalf("missing key %q", sharedID)
+	}
+	if winner.Href != "/cal/work/newer.ics" {
+		t.Errorf("winner.Href = %q, want /cal/work/newer.ics", winner.Href)
+	}
+
+	// Now flip the order; the existing-is-newer branch should also
+	// produce the newer event and emit the same duplicate warning.
+	logBuf.Reset()
+	got, _ = ToManagedMap([]RawEvent{newer, older}, log)
+	if winner, ok := got[sharedID]; !ok || winner.Href != "/cal/work/newer.ics" {
+		t.Errorf("after flip, winner = %+v, want href /cal/work/newer.ics", winner)
+	}
+
+	if !strings.Contains(logBuf.String(), "duplicate managed events queued for deletion") {
+		t.Errorf("expected duplicate summary in log, got:\n%s", logBuf.String())
+	}
+}
+
+// TestToManagedMap_BadDataSkipped confirms unparseable bytes log a warning
+// and are skipped without panicking. The well-formed entry following them
+// must still appear in the resulting map.
+func TestToManagedMap_BadDataSkipped(t *testing.T) {
+	good := buildRawEvent(t, eventkit.Event{
+		ExternalID: "ek-good",
+		Title:      "Good",
+		Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-good", "/cal/work/good.ics", "etag-good")
+
+	bad := []RawEvent{
+		{Href: "/cal/work/empty.ics", Data: []byte(""), ETag: "etag-empty"},
+		{Href: "/cal/work/garbage.ics", Data: []byte("not a calendar"), ETag: "etag-garbage"},
+		{Href: "/cal/work/truncated.ics", Data: []byte("BEGIN:VCALENDAR\r\n"), ETag: "etag-trunc"},
+	}
+
+	var logBuf bytes.Buffer
+	log := slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelWarn}))
+
+	raws := append([]RawEvent{}, bad...)
+	raws = append(raws, good)
+
+	got, _ := ToManagedMap(raws, log)
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1 (only the good event)", len(got))
+	}
+	if _, ok := got["ek-good"]; !ok {
+		t.Errorf("expected key ek-good in map, got %v", got)
+	}
+	if !strings.Contains(logBuf.String(), "skipping unparseable CalDAV event") {
+		t.Errorf("expected warning about unparseable event in log, got:\n%s", logBuf.String())
+	}
+}
+
+// TestToManagedMap_NilLoggerUsesDefault confirms the nil-logger fallback
+// works without panicking. The function should silently substitute
+// slog.Default() rather than crash, since callers may pass nil for
+// brevity in simple cases.
+func TestToManagedMap_NilLoggerUsesDefault(t *testing.T) {
+	good := buildRawEvent(t, eventkit.Event{
+		ExternalID: "ek-x",
+		Title:      "X",
+		Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-x", "/cal/work/x.ics", "etag-x")
+
+	got, _ := ToManagedMap([]RawEvent{good}, nil)
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1", len(got))
+	}
+	if _, ok := got["ek-x"]; !ok {
+		t.Errorf("expected key ek-x in map")
+	}
+}
+
+// TestToManagedMap_ReturnsDuplicates confirms the second return value
+// surfaces the loser of each X-WORK-CAL-ID collision so the caller can
+// queue them for deletion. Prior versions only logged about the
+// duplicate without acting on it, leaving server-side cruft to
+// accumulate across interrupted runs.
+func TestToManagedMap_ReturnsDuplicates(t *testing.T) {
+	const sharedID = "ek-dup-1"
+
+	older := buildRawEvent(t, eventkit.Event{
+		ExternalID:   sharedID,
+		Title:        "older copy",
+		LastModified: time.Unix(1000, 0),
+		Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-older", "/cal/work/older.ics", "etag-older")
+	newer := buildRawEvent(t, eventkit.Event{
+		ExternalID:   sharedID,
+		Title:        "newer copy",
+		LastModified: time.Unix(2000, 0),
+		Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-newer", "/cal/work/newer.ics", "etag-newer")
+
+	got, dups := ToManagedMap([]RawEvent{older, newer}, discardLogger())
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1", len(got))
+	}
+	if len(dups) != 1 {
+		t.Fatalf("len(dups) = %d, want 1", len(dups))
+	}
+	if dups[0].Href != "/cal/work/older.ics" {
+		t.Errorf("dup href = %q, want /cal/work/older.ics", dups[0].Href)
+	}
+}
diff --git a/internal/sync/plist.go b/internal/sync/plist.go
new file mode 100644
index 0000000..36345cc
--- /dev/null
+++ b/internal/sync/plist.go
@@ -0,0 +1,265 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"html"
+	"io/fs"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"text/template"
+)
+
+// plistLabel is the launchd label for the Go implementation. It is
+// intentionally distinct from the Python implementation's label
+// (`tel.dead.work-cal-sync`) so the two versions can coexist on the
+// same machine during migration.
+const plistLabel = "tel.dead.work-cal-sync.go"
+
+// PlistDirPerm is the file mode for the LaunchAgents directory. launchd
+// needs to read it, so 0o755 is the conventional choice.
+const PlistDirPerm os.FileMode = 0o755
+
+// PlistFilePerm is the file mode for the installed plist. launchd needs
+// to read it; the file contains no secrets so 0o644 is appropriate.
+const PlistFilePerm os.FileMode = 0o644
+
+// plistTemplate is the source template used by Generate. The template
+// executes against a struct with Label, BinaryPath, and LogPath fields;
+// each field is passed through the `xml` template function so callers
+// don't have to pre-escape values containing XML metacharacters.
+//
+// Configuration choices (per design.md):
+//   - StartInterval: 900 (run every 15 minutes)
+//   - RunAtLoad:     false (defer first run to the interval)
+//   - KeepAlive:     false (one-shot per interval, not a daemon)
+const plistTemplate = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>{{.Label | xml}}</string>
+
+	<key>ProgramArguments</key>
+	<array>
+		<string>{{.BinaryPath | xml}}</string>
+	</array>
+
+	<key>StartInterval</key>
+	<integer>900</integer>
+
+	<key>RunAtLoad</key>
+	<false/>
+
+	<key>KeepAlive</key>
+	<false/>
+
+	<key>StandardOutPath</key>
+	<string>{{.LogPath | xml}}</string>
+
+	<key>StandardErrorPath</key>
+	<string>{{.LogPath | xml}}</string>
+</dict>
+</plist>
+`
+
+// compiledPlistTemplate is parsed once at package init so Generate is a
+// pure formatter at call time and any template error surfaces during
+// development rather than at runtime.
+var compiledPlistTemplate = template.Must(
+	template.New("plist").Funcs(template.FuncMap{
+		"xml": html.EscapeString,
+	}).Parse(plistTemplate),
+)
+
+// Generate renders the launchd plist for the work-cal-sync Go binary.
+//
+// binaryPath is the absolute path to the `work-cal-sync` executable
+// (typically obtained via os.Executable). logPath is the file launchd
+// should redirect stdout and stderr to (typically
+// ~/Library/Logs/work-cal-sync.log resolved to an absolute path by the
+// caller). XML metacharacters in either argument are escaped, so values
+// like `Tom & Jerry` are safe to embed.
+//
+// The template and its inputs are fixed at compile time, so rendering
+// cannot fail at runtime; Generate panics in the impossible case that
+// it does, since that would indicate a programming error.
+func Generate(binaryPath, logPath string) []byte {
+	data := struct {
+		Label      string
+		BinaryPath string
+		LogPath    string
+	}{
+		Label:      plistLabel,
+		BinaryPath: binaryPath,
+		LogPath:    logPath,
+	}
+
+	var buf bytes.Buffer
+	if err := compiledPlistTemplate.Execute(&buf, data); err != nil {
+		// The template is parsed at init and the data shape is fixed,
+		// so Execute returning an error here means a developer broke
+		// the template. Fail loudly rather than silently.
+		panic("plist: render template: " + err.Error())
+	}
+	return buf.Bytes()
+}
+
+// PlistPath returns the absolute path where the launchd plist is
+// installed: ~/Library/LaunchAgents/<label>.plist. Other commands (e.g.
+// status) need this path to query launchctl, so it's exported.
+func PlistPath() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolve home directory: %w", err)
+	}
+	return filepath.Join(home, "Library", "LaunchAgents", plistLabel+".plist"), nil
+}
+
+// Label returns the launchd label used by this binary. Exposed so the
+// status subcommand can pass it to `launchctl list`.
+func Label() string { return plistLabel }
+
+// InstallPlist writes data (typically the output of Generate) to PlistPath
+// with appropriate permissions. The write is atomic: data goes to a
+// sibling temp file which is renamed over the destination, so launchd
+// never sees a partial plist.
+//
+// InstallPlist creates ~/Library/LaunchAgents if it doesn't already
+// exist and overwrites any existing plist at the destination —
+// re-running install to update the binary path is the expected use
+// case.
+func InstallPlist(data []byte) error {
+	p, err := PlistPath()
+	if err != nil {
+		return err
+	}
+	dir := filepath.Dir(p)
+
+	if err := os.MkdirAll(dir, PlistDirPerm); err != nil {
+		return fmt.Errorf("create LaunchAgents dir %s: %w", dir, err)
+	}
+
+	tmp, err := os.CreateTemp(dir, "plist-*.tmp")
+	if err != nil {
+		return fmt.Errorf("create temp plist in %s: %w", dir, err)
+	}
+	tmpPath := tmp.Name()
+	// Best-effort cleanup: if anything below fails before the rename,
+	// the temp file is removed. After a successful rename, the temp
+	// file no longer exists and Remove returns ErrNotExist (ignored).
+	defer func() { _ = os.Remove(tmpPath) }()
+
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("write temp plist %s: %w", tmpPath, err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close temp plist %s: %w", tmpPath, err)
+	}
+	if err := os.Chmod(tmpPath, PlistFilePerm); err != nil {
+		return fmt.Errorf("chmod temp plist %s: %w", tmpPath, err)
+	}
+	if err := os.Rename(tmpPath, p); err != nil {
+		return fmt.Errorf("rename temp plist to %s: %w", p, err)
+	}
+	return nil
+}
+
+// runLaunchctl is the hook used by Load and Unload to invoke
+// launchctl(1). Tests replace this with a stub so they can run without
+// touching the user's launchd state. The default implementation shells
+// out to /usr/bin/env launchctl and captures stdout and stderr so
+// callers can include them in error messages.
+var runLaunchctl = defaultRunLaunchctl
+
+func defaultRunLaunchctl(args ...string) (stdout, stderr string, err error) {
+	cmd := exec.Command("launchctl", args...)
+	var sout, serr bytes.Buffer
+	cmd.Stdout = &sout
+	cmd.Stderr = &serr
+	err = cmd.Run()
+	return sout.String(), serr.String(), err
+}
+
+// LoadJob runs `launchctl load <plist>` to register the launchd job.
+// It is not idempotent on its own (launchctl errors if the job is
+// already loaded); callers that want re-runnable installs should call
+// UnloadJob first.
+func LoadJob() error {
+	p, err := PlistPath()
+	if err != nil {
+		return err
+	}
+	sout, serr, runErr := runLaunchctl("load", p)
+	if runErr != nil {
+		return fmt.Errorf("launchctl load %s: %w (stdout=%q stderr=%q)",
+			p, runErr, strings.TrimSpace(sout), strings.TrimSpace(serr))
+	}
+	return nil
+}
+
+// UnloadJob runs `launchctl unload <plist>`. It is idempotent: if the
+// plist file is missing or the job is not currently loaded, UnloadJob
+// returns nil. Other failures are surfaced with stdout/stderr context.
+func UnloadJob() error {
+	p, err := PlistPath()
+	if err != nil {
+		return err
+	}
+	// If the plist doesn't exist, there's nothing for launchctl to
+	// unload — and launchctl would error with "No such file or
+	// directory". Short-circuit to keep the happy path quiet.
+	if _, err := os.Stat(p); errors.Is(err, fs.ErrNotExist) {
+		return nil
+	}
+
+	sout, serr, runErr := runLaunchctl("unload", p)
+	if runErr == nil {
+		return nil
+	}
+	if isNotLoadedMessage(sout + "\n" + serr) {
+		return nil
+	}
+	return fmt.Errorf("launchctl unload %s: %w (stdout=%q stderr=%q)",
+		p, runErr, strings.TrimSpace(sout), strings.TrimSpace(serr))
+}
+
+// RemovePlist deletes the installed plist file. It is idempotent:
+// missing file returns nil. Removing the file is independent of whether
+// the job is currently loaded; callers that want a clean uninstall
+// should call UnloadJob first.
+func RemovePlist() error {
+	p, err := PlistPath()
+	if err != nil {
+		return err
+	}
+	if err := os.Remove(p); err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return fmt.Errorf("remove plist %s: %w", p, err)
+	}
+	return nil
+}
+
+// isNotLoadedMessage reports whether a launchctl error message
+// indicates the job simply wasn't loaded — the case Unload swallows.
+// launchctl's wording has varied between macOS versions, so we match a
+// handful of common phrases case-insensitively.
+func isNotLoadedMessage(s string) bool {
+	s = strings.ToLower(s)
+	switch {
+	case strings.Contains(s, "could not find specified service"):
+		return true
+	case strings.Contains(s, "no such process"):
+		return true
+	case strings.Contains(s, "not loaded"):
+		return true
+	case strings.Contains(s, "service is not loaded"):
+		return true
+	}
+	return false
+}
diff --git a/internal/sync/plist_test.go b/internal/sync/plist_test.go
new file mode 100644
index 0000000..bef7f80
--- /dev/null
+++ b/internal/sync/plist_test.go
@@ -0,0 +1,428 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"encoding/xml"
+	"errors"
+	"io/fs"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// plistDoc mirrors the subset of the launchd plist we want to assert on
+// in tests. The XML Plist <dict> is decoded as alternating <key> /
+// value elements, so we capture the key-value pairs in order.
+type plistDoc struct {
+	XMLName xml.Name  `xml:"plist"`
+	Dict    plistDict `xml:"dict"`
+}
+
+type plistDict struct {
+	Keys     []string  `xml:"key"`
+	Strings  []string  `xml:"string"`
+	Integers []int     `xml:"integer"`
+	Trues    []xmlBool `xml:"true"`
+	Falses   []xmlBool `xml:"false"`
+}
+
+type xmlBool struct{}
+
+func TestGenerate_IsValidXML(t *testing.T) {
+	out := Generate("/usr/local/bin/work-cal-sync", "/Users/me/Library/Logs/work-cal-sync.log")
+
+	var doc plistDoc
+	if err := xml.Unmarshal(out, &doc); err != nil {
+		t.Fatalf("Generate output is not valid XML: %v\n---\n%s", err, out)
+	}
+	if len(doc.Dict.Keys) == 0 {
+		t.Fatal("plist <dict> has no <key> entries")
+	}
+}
+
+func TestGenerate_ContainsExpectedKeys(t *testing.T) {
+	out := string(Generate("/opt/work-cal-sync", "/tmp/wcs.log"))
+
+	wants := []string{
+		"<key>Label</key>",
+		"<string>tel.dead.work-cal-sync.go</string>",
+		"<key>ProgramArguments</key>",
+		"<string>/opt/work-cal-sync</string>",
+		"<key>StartInterval</key>",
+		"<integer>900</integer>",
+		"<key>RunAtLoad</key>",
+		"<false/>",
+		"<key>KeepAlive</key>",
+		"<key>StandardOutPath</key>",
+		"<string>/tmp/wcs.log</string>",
+		"<key>StandardErrorPath</key>",
+	}
+	for _, w := range wants {
+		if !strings.Contains(out, w) {
+			t.Errorf("Generate output missing %q\n---\n%s", w, out)
+		}
+	}
+}
+
+func TestGenerate_RunAtLoadAndKeepAliveAreFalse(t *testing.T) {
+	out := string(Generate("/bin/wcs", "/var/log/wcs.log"))
+
+	// Both keys must be followed by <false/> rather than <true/>. We
+	// look for the substring `<key>NAME</key>\n\t<false/>` rather than
+	// just any false element so a stray <false/> elsewhere doesn't
+	// satisfy the assertion.
+	for _, key := range []string{"RunAtLoad", "KeepAlive"} {
+		needle := "<key>" + key + "</key>"
+		idx := strings.Index(out, needle)
+		if idx < 0 {
+			t.Errorf("missing key %s", key)
+			continue
+		}
+		after := out[idx+len(needle):]
+		// The next non-whitespace tag should be <false/>.
+		trimmed := strings.TrimLeft(after, " \t\r\n")
+		if !strings.HasPrefix(trimmed, "<false/>") {
+			t.Errorf("%s should be <false/>, got prefix %q", key, firstLine(trimmed))
+		}
+	}
+}
+
+func TestGenerate_StartIntervalIs900(t *testing.T) {
+	out := string(Generate("/bin/wcs", "/var/log/wcs.log"))
+
+	needle := "<key>StartInterval</key>"
+	idx := strings.Index(out, needle)
+	if idx < 0 {
+		t.Fatal("missing StartInterval key")
+	}
+	after := strings.TrimLeft(out[idx+len(needle):], " \t\r\n")
+	want := "<integer>900</integer>"
+	if !strings.HasPrefix(after, want) {
+		t.Errorf("StartInterval value = %q, want %q", firstLine(after), want)
+	}
+}
+
+func TestGenerate_EscapesXMLMetacharacters(t *testing.T) {
+	// A path containing & and < must come out escaped, not raw.
+	out := string(Generate("/bin/Tom & Jerry", "/tmp/<log>.log"))
+
+	if strings.Contains(out, "/bin/Tom & Jerry") {
+		t.Errorf("ampersand in binary path was not escaped:\n%s", out)
+	}
+	if strings.Contains(out, "<log>.log") {
+		t.Errorf("angle brackets in log path were not escaped:\n%s", out)
+	}
+	if !strings.Contains(out, "/bin/Tom &amp; Jerry") {
+		t.Errorf("expected &amp; in escaped output:\n%s", out)
+	}
+	if !strings.Contains(out, "&lt;log&gt;.log") {
+		t.Errorf("expected &lt;...&gt; in escaped output:\n%s", out)
+	}
+
+	// Escaped output must still be valid XML.
+	var doc plistDoc
+	if err := xml.Unmarshal([]byte(out), &doc); err != nil {
+		t.Fatalf("escaped plist is not valid XML: %v", err)
+	}
+}
+
+func TestGenerate_StdoutAndStderrPointAtSameLog(t *testing.T) {
+	logPath := "/Users/me/Library/Logs/work-cal-sync.log"
+	out := string(Generate("/bin/wcs", logPath))
+
+	for _, key := range []string{"StandardOutPath", "StandardErrorPath"} {
+		needle := "<key>" + key + "</key>"
+		idx := strings.Index(out, needle)
+		if idx < 0 {
+			t.Errorf("missing key %s", key)
+			continue
+		}
+		after := strings.TrimLeft(out[idx+len(needle):], " \t\r\n")
+		want := "<string>" + logPath + "</string>"
+		if !strings.HasPrefix(after, want) {
+			t.Errorf("%s value = %q, want %q", key, firstLine(after), want)
+		}
+	}
+}
+
+func firstLine(s string) string {
+	if i := strings.IndexByte(s, '\n'); i >= 0 {
+		return s[:i]
+	}
+	return s
+}
+
+// --- PlistPath / Install / Load / Unload / Remove ---
+
+// withHome temporarily swaps HOME so PlistPath resolves into a temp
+// directory, isolating tests from the user's real LaunchAgents folder.
+func withHome(t *testing.T, dir string) {
+	t.Helper()
+	prev, hadPrev := os.LookupEnv("HOME")
+	if err := os.Setenv("HOME", dir); err != nil {
+		t.Fatalf("set HOME: %v", err)
+	}
+	t.Cleanup(func() {
+		if hadPrev {
+			_ = os.Setenv("HOME", prev)
+		} else {
+			_ = os.Unsetenv("HOME")
+		}
+	})
+}
+
+// withLaunchctl swaps in a fake runLaunchctl for the duration of a
+// single test and records the calls it received.
+func withLaunchctl(t *testing.T, fn func(args ...string) (string, string, error)) *[][]string {
+	t.Helper()
+	calls := &[][]string{}
+	prev := runLaunchctl
+	runLaunchctl = func(args ...string) (string, string, error) {
+		dup := append([]string(nil), args...)
+		*calls = append(*calls, dup)
+		return fn(args...)
+	}
+	t.Cleanup(func() { runLaunchctl = prev })
+	return calls
+}
+
+func TestPlistPath_UsesHomeAndLabel(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+
+	got, err := PlistPath()
+	if err != nil {
+		t.Fatalf("PlistPath: %v", err)
+	}
+	want := filepath.Join(dir, "Library", "LaunchAgents", "tel.dead.work-cal-sync.go.plist")
+	if got != want {
+		t.Errorf("PlistPath = %q, want %q", got, want)
+	}
+}
+
+func TestLabel_IsExpected(t *testing.T) {
+	if Label() != "tel.dead.work-cal-sync.go" {
+		t.Errorf("Label() = %q, want %q", Label(), "tel.dead.work-cal-sync.go")
+	}
+}
+
+func TestInstall_WritesFileWithCorrectPermissions(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+
+	data := Generate("/usr/local/bin/work-cal-sync", "/tmp/wcs.log")
+	if err := InstallPlist(data); err != nil {
+		t.Fatalf("InstallPlist: %v", err)
+	}
+
+	p, _ := PlistPath()
+	got, err := os.ReadFile(p)
+	if err != nil {
+		t.Fatalf("read installed plist: %v", err)
+	}
+	if !bytes.Equal(got, data) {
+		t.Errorf("installed plist contents differ from generated bytes")
+	}
+
+	info, err := os.Stat(p)
+	if err != nil {
+		t.Fatalf("stat plist: %v", err)
+	}
+	if info.Mode().Perm() != PlistFilePerm {
+		t.Errorf("plist mode = %v, want %v", info.Mode().Perm(), PlistFilePerm)
+	}
+}
+
+func TestInstall_OverwritesExistingFile(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+
+	if err := InstallPlist([]byte("first")); err != nil {
+		t.Fatalf("first InstallPlist: %v", err)
+	}
+	if err := InstallPlist([]byte("second")); err != nil {
+		t.Fatalf("second InstallPlist: %v", err)
+	}
+
+	p, _ := PlistPath()
+	got, err := os.ReadFile(p)
+	if err != nil {
+		t.Fatalf("read plist: %v", err)
+	}
+	if string(got) != "second" {
+		t.Errorf("plist contents = %q, want %q", got, "second")
+	}
+}
+
+func TestInstall_CreatesLaunchAgentsDirectory(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+
+	// Sanity check: dir does not exist yet.
+	la := filepath.Join(dir, "Library", "LaunchAgents")
+	if _, err := os.Stat(la); !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("LaunchAgents dir should not pre-exist: %v", err)
+	}
+
+	if err := InstallPlist([]byte("data")); err != nil {
+		t.Fatalf("InstallPlist: %v", err)
+	}
+	if _, err := os.Stat(la); err != nil {
+		t.Errorf("expected LaunchAgents dir created: %v", err)
+	}
+}
+
+func TestLoad_InvokesLaunchctlLoad(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	calls := withLaunchctl(t, func(args ...string) (string, string, error) {
+		return "", "", nil
+	})
+
+	if err := LoadJob(); err != nil {
+		t.Fatalf("LoadJob: %v", err)
+	}
+	if len(*calls) != 1 {
+		t.Fatalf("expected 1 launchctl call, got %d", len(*calls))
+	}
+	got := (*calls)[0]
+	p, _ := PlistPath()
+	want := []string{"load", p}
+	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+		t.Errorf("launchctl args = %v, want %v", got, want)
+	}
+}
+
+func TestLoad_PropagatesError(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	withLaunchctl(t, func(args ...string) (string, string, error) {
+		return "", "boom", &exec.ExitError{}
+	})
+
+	err := LoadJob()
+	if err == nil {
+		t.Fatal("LoadJob: expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "launchctl load") {
+		t.Errorf("error should mention launchctl load: %v", err)
+	}
+}
+
+func TestUnload_NoPlistIsNoOp(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	calls := withLaunchctl(t, func(args ...string) (string, string, error) {
+		t.Fatalf("launchctl should not be invoked when plist is missing")
+		return "", "", nil
+	})
+
+	if err := UnloadJob(); err != nil {
+		t.Errorf("UnloadJob with missing plist: %v", err)
+	}
+	if len(*calls) != 0 {
+		t.Errorf("expected no launchctl calls, got %d", len(*calls))
+	}
+}
+
+func TestUnload_InvokesLaunchctlUnloadWhenPlistExists(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	if err := InstallPlist([]byte("data")); err != nil {
+		t.Fatalf("InstallPlist: %v", err)
+	}
+	calls := withLaunchctl(t, func(args ...string) (string, string, error) {
+		return "", "", nil
+	})
+
+	if err := UnloadJob(); err != nil {
+		t.Fatalf("UnloadJob: %v", err)
+	}
+	if len(*calls) != 1 || (*calls)[0][0] != "unload" {
+		t.Errorf("expected unload call, got %v", *calls)
+	}
+}
+
+func TestUnload_SwallowsNotLoadedError(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	if err := InstallPlist([]byte("data")); err != nil {
+		t.Fatalf("InstallPlist: %v", err)
+	}
+	withLaunchctl(t, func(args ...string) (string, string, error) {
+		return "", "Could not find specified service", &exec.ExitError{}
+	})
+
+	if err := UnloadJob(); err != nil {
+		t.Errorf("UnloadJob should swallow 'not loaded' errors, got: %v", err)
+	}
+}
+
+func TestUnload_ReturnsOtherErrors(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	if err := InstallPlist([]byte("data")); err != nil {
+		t.Fatalf("InstallPlist: %v", err)
+	}
+	withLaunchctl(t, func(args ...string) (string, string, error) {
+		return "", "permission denied", &exec.ExitError{}
+	})
+
+	err := UnloadJob()
+	if err == nil {
+		t.Fatal("UnloadJob: expected error for unrelated launchctl failure")
+	}
+	if !strings.Contains(err.Error(), "permission denied") {
+		t.Errorf("error should include launchctl stderr: %v", err)
+	}
+}
+
+func TestRemove_DeletesPlist(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+	if err := InstallPlist([]byte("data")); err != nil {
+		t.Fatalf("InstallPlist: %v", err)
+	}
+
+	if err := RemovePlist(); err != nil {
+		t.Fatalf("RemovePlist: %v", err)
+	}
+	p, _ := PlistPath()
+	if _, err := os.Stat(p); !errors.Is(err, fs.ErrNotExist) {
+		t.Errorf("plist still present after RemovePlist: %v", err)
+	}
+}
+
+func TestRemove_MissingFileIsIdempotent(t *testing.T) {
+	dir := t.TempDir()
+	withHome(t, dir)
+
+	if err := RemovePlist(); err != nil {
+		t.Errorf("RemovePlist on missing file should be nil, got %v", err)
+	}
+	// Running it again should still be a no-op.
+	if err := RemovePlist(); err != nil {
+		t.Errorf("second RemovePlist: %v", err)
+	}
+}
+
+func TestIsNotLoadedMessage_KnownPhrases(t *testing.T) {
+	cases := map[string]bool{
+		"Could not find specified service":             true,
+		"launchctl: no such process":                   true,
+		"Service is not loaded":                        true,
+		"some other unrelated error":                   false,
+		"":                                             false,
+		"Bootstrap failed: 5: Input/output error":      false,
+		"NOT LOADED":                                   true, // case-insensitive
+	}
+	for msg, want := range cases {
+		if got := isNotLoadedMessage(msg); got != want {
+			t.Errorf("isNotLoadedMessage(%q) = %v, want %v", msg, got, want)
+		}
+	}
+}
diff --git a/internal/sync/prompt.go b/internal/sync/prompt.go
new file mode 100644
index 0000000..6906ec2
--- /dev/null
+++ b/internal/sync/prompt.go
@@ -0,0 +1,217 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bufio"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+
+	"golang.org/x/term"
+)
+
+// promptScannerBufferSize is the maximum line length the prompt scanner
+// will accept. The default bufio.Scanner buffer (64 KiB) is too small for
+// users who paste long URLs or tokens, so we raise it to 1 MiB.
+const promptScannerBufferSize = 1024 * 1024
+
+// Prompter is a small helper for interactive command-line prompts. It
+// reads lines from an io.Reader (wrapped in a bufio.Scanner) and writes
+// prompts to an io.Writer, which lets tests inject canned input/output
+// streams without touching the real stdin/stdout.
+type Prompter struct {
+	in  *bufio.Scanner
+	out io.Writer
+	// readPassword reads a password without echoing. It is a function so
+	// tests can replace it with a stub.
+	readPassword func(prompt string) (string, error)
+}
+
+// NewPrompter returns a Prompter that reads from in and writes to out.
+// The default password reader uses golang.org/x/term.ReadPassword when
+// stdin is a terminal, falling back to a plain scanner read otherwise so
+// the wizard remains usable in piped/scripted contexts.
+func NewPrompter(in io.Reader, out io.Writer) *Prompter {
+	scanner := bufio.NewScanner(in)
+	// Allow long pasted lines without truncation.
+	scanner.Buffer(make([]byte, 0, 64*1024), promptScannerBufferSize)
+
+	p := &Prompter{
+		in:  scanner,
+		out: out,
+	}
+	p.readPassword = p.defaultReadPassword
+	return p
+}
+
+// WithPasswordReader replaces the password reader. It is intended for
+// tests that need to feed canned passwords without touching the
+// terminal.
+func (p *Prompter) WithPasswordReader(fn func(prompt string) (string, error)) *Prompter {
+	p.readPassword = fn
+	return p
+}
+
+// defaultReadPassword reads a password. When stdin is a real terminal it
+// uses term.ReadPassword (so the password is not echoed). Otherwise it
+// reads a single line from the scanner so piped input still works.
+func (p *Prompter) defaultReadPassword(prompt string) (string, error) {
+	if _, err := fmt.Fprint(p.out, prompt); err != nil {
+		return "", err
+	}
+	fd := int(os.Stdin.Fd())
+	if term.IsTerminal(fd) {
+		b, err := term.ReadPassword(fd)
+		// ReadPassword swallows the trailing newline; emit one so the
+		// next prompt starts on its own line.
+		_, _ = fmt.Fprintln(p.out)
+		if err != nil {
+			return "", fmt.Errorf("read password: %w", err)
+		}
+		return string(b), nil
+	}
+	return p.readLine()
+}
+
+// readLine reads a single line from the underlying scanner and returns
+// it with surrounding whitespace trimmed. It distinguishes EOF from
+// other read errors and surfaces both to the caller.
+func (p *Prompter) readLine() (string, error) {
+	if !p.in.Scan() {
+		if err := p.in.Err(); err != nil {
+			return "", fmt.Errorf("read input: %w", err)
+		}
+		return "", io.EOF
+	}
+	return strings.TrimSpace(p.in.Text()), nil
+}
+
+// Line writes the prompt and returns the next line of input with
+// surrounding whitespace trimmed.
+func (p *Prompter) Line(prompt string) (string, error) {
+	if _, err := fmt.Fprint(p.out, prompt); err != nil {
+		return "", err
+	}
+	return p.readLine()
+}
+
+// LineDefault writes "<prompt> [default <def>]: " and returns the user's
+// response, falling back to def when the user just hits enter.
+func (p *Prompter) LineDefault(prompt, def string) (string, error) {
+	full := fmt.Sprintf("%s [default %s]: ", prompt, def)
+	s, err := p.Line(full)
+	if err != nil {
+		return "", err
+	}
+	if s == "" {
+		return def, nil
+	}
+	return s, nil
+}
+
+// Int reads an integer. Empty input returns def. On non-numeric input it
+// reprompts up to three times and then returns the last parse error.
+func (p *Prompter) Int(prompt string, def int) (int, error) {
+	full := fmt.Sprintf("%s [default %d]: ", prompt, def)
+	const maxAttempts = 3
+	var lastErr error
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		s, err := p.Line(full)
+		if err != nil {
+			return 0, err
+		}
+		if s == "" {
+			return def, nil
+		}
+		n, err := strconv.Atoi(s)
+		if err == nil {
+			return n, nil
+		}
+		lastErr = err
+		if _, werr := fmt.Fprintf(p.out, "Not a number: %q. Try again.\n", s); werr != nil {
+			return 0, werr
+		}
+	}
+	if lastErr == nil {
+		lastErr = errors.New("invalid integer input")
+	}
+	return 0, lastErr
+}
+
+// Password reads a password without echoing using the configured
+// password reader.
+func (p *Prompter) Password(prompt string) (string, error) {
+	return p.readPassword(prompt)
+}
+
+// Confirm prompts for a yes/no answer. Empty input returns def. The
+// strings y, yes, n, no are accepted (case-insensitive); anything else
+// causes a re-prompt up to three times.
+func (p *Prompter) Confirm(prompt string, def bool) (bool, error) {
+	suffix := "[y/N]"
+	if def {
+		suffix = "[Y/n]"
+	}
+	full := fmt.Sprintf("%s %s: ", prompt, suffix)
+	const maxAttempts = 3
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		s, err := p.Line(full)
+		if err != nil {
+			return false, err
+		}
+		switch strings.ToLower(s) {
+		case "":
+			return def, nil
+		case "y", "yes":
+			return true, nil
+		case "n", "no":
+			return false, nil
+		}
+		if _, werr := fmt.Fprintf(p.out, "Please answer yes or no (got %q).\n", s); werr != nil {
+			return false, werr
+		}
+	}
+	return false, fmt.Errorf("no valid yes/no answer after %d attempts", maxAttempts)
+}
+
+// Pick presents options as a numbered list and returns the selected
+// option. labelFn produces the human-readable label for each option. The
+// helper retries on invalid input and uses Go generics so the caller can
+// supply any slice type.
+func Pick[T any](p *Prompter, prompt string, options []T, labelFn func(T) string) (T, error) {
+	var zero T
+	if len(options) == 0 {
+		return zero, errors.New("pick: no options provided")
+	}
+
+	if _, err := fmt.Fprintln(p.out); err != nil {
+		return zero, err
+	}
+	if _, err := fmt.Fprintln(p.out, prompt); err != nil {
+		return zero, err
+	}
+	for i, opt := range options {
+		if _, err := fmt.Fprintf(p.out, "  %d) %s\n", i+1, labelFn(opt)); err != nil {
+			return zero, err
+		}
+	}
+
+	const maxAttempts = 3
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		s, err := p.Line("Enter number: ")
+		if err != nil {
+			return zero, err
+		}
+		if n, err := strconv.Atoi(s); err == nil && n >= 1 && n <= len(options) {
+			return options[n-1], nil
+		}
+		if _, werr := fmt.Fprintf(p.out, "  Please enter a number between 1 and %d.\n", len(options)); werr != nil {
+			return zero, werr
+		}
+	}
+	return zero, fmt.Errorf("no valid selection after %d attempts", maxAttempts)
+}
diff --git a/internal/sync/prompt_test.go b/internal/sync/prompt_test.go
new file mode 100644
index 0000000..1696cef
--- /dev/null
+++ b/internal/sync/prompt_test.go
@@ -0,0 +1,335 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+func newTestPrompter(input string) (*Prompter, *bytes.Buffer) {
+	out := &bytes.Buffer{}
+	return NewPrompter(strings.NewReader(input), out), out
+}
+
+func TestPrompter_Line_ReadsSingleLine(t *testing.T) {
+	p, out := newTestPrompter("hello world\nignored\n")
+
+	got, err := p.Line("name: ")
+	if err != nil {
+		t.Fatalf("Line() error: %v", err)
+	}
+	if got != "hello world" {
+		t.Errorf("Line() = %q, want %q", got, "hello world")
+	}
+	if !strings.Contains(out.String(), "name: ") {
+		t.Errorf("expected prompt written to out, got %q", out.String())
+	}
+}
+
+func TestPrompter_Line_TrimsSurroundingWhitespace(t *testing.T) {
+	p, _ := newTestPrompter("  spaced  \n")
+
+	got, err := p.Line("> ")
+	if err != nil {
+		t.Fatalf("Line() error: %v", err)
+	}
+	if got != "spaced" {
+		t.Errorf("Line() = %q, want %q", got, "spaced")
+	}
+}
+
+func TestPrompter_Line_EOFReturnsErr(t *testing.T) {
+	p, _ := newTestPrompter("")
+
+	if _, err := p.Line("> "); !errors.Is(err, io.EOF) {
+		t.Errorf("Line() err = %v, want io.EOF", err)
+	}
+}
+
+func TestPrompter_LineDefault_EmptyReturnsDefault(t *testing.T) {
+	p, out := newTestPrompter("\n")
+
+	got, err := p.LineDefault("server", "https://example.com")
+	if err != nil {
+		t.Fatalf("LineDefault() error: %v", err)
+	}
+	if got != "https://example.com" {
+		t.Errorf("LineDefault() = %q, want default", got)
+	}
+	if !strings.Contains(out.String(), "[default https://example.com]") {
+		t.Errorf("expected default in prompt, got %q", out.String())
+	}
+}
+
+func TestPrompter_LineDefault_NonEmptyReturnsInput(t *testing.T) {
+	p, _ := newTestPrompter("https://other.example.com\n")
+
+	got, err := p.LineDefault("server", "https://example.com")
+	if err != nil {
+		t.Fatalf("LineDefault() error: %v", err)
+	}
+	if got != "https://other.example.com" {
+		t.Errorf("LineDefault() = %q, want user input", got)
+	}
+}
+
+func TestPrompter_Int_EmptyReturnsDefault(t *testing.T) {
+	p, _ := newTestPrompter("\n")
+
+	got, err := p.Int("days back", 7)
+	if err != nil {
+		t.Fatalf("Int() error: %v", err)
+	}
+	if got != 7 {
+		t.Errorf("Int() = %d, want 7 (default)", got)
+	}
+}
+
+func TestPrompter_Int_ParsesValidNumber(t *testing.T) {
+	p, _ := newTestPrompter("42\n")
+
+	got, err := p.Int("days back", 7)
+	if err != nil {
+		t.Fatalf("Int() error: %v", err)
+	}
+	if got != 42 {
+		t.Errorf("Int() = %d, want 42", got)
+	}
+}
+
+func TestPrompter_Int_RetriesOnBadInput(t *testing.T) {
+	// Two invalid attempts followed by a valid one.
+	p, out := newTestPrompter("nope\nstill bad\n12\n")
+
+	got, err := p.Int("days back", 7)
+	if err != nil {
+		t.Fatalf("Int() error: %v", err)
+	}
+	if got != 12 {
+		t.Errorf("Int() = %d, want 12", got)
+	}
+	if !strings.Contains(out.String(), "Not a number") {
+		t.Errorf("expected retry message in out, got %q", out.String())
+	}
+}
+
+func TestPrompter_Int_ReturnsErrorAfterThreeBadAttempts(t *testing.T) {
+	p, _ := newTestPrompter("a\nb\nc\n")
+
+	_, err := p.Int("days back", 7)
+	if err == nil {
+		t.Fatal("Int() expected error after 3 bad attempts, got nil")
+	}
+}
+
+func TestPrompter_Confirm_AcceptsYesVariants(t *testing.T) {
+	cases := []string{"y", "Y", "yes", "YES", "Yes"}
+	for _, c := range cases {
+		p, _ := newTestPrompter(c + "\n")
+		got, err := p.Confirm("ok?", false)
+		if err != nil {
+			t.Fatalf("Confirm(%q) error: %v", c, err)
+		}
+		if !got {
+			t.Errorf("Confirm(%q) = false, want true", c)
+		}
+	}
+}
+
+func TestPrompter_Confirm_AcceptsNoVariants(t *testing.T) {
+	cases := []string{"n", "N", "no", "NO", "No"}
+	for _, c := range cases {
+		p, _ := newTestPrompter(c + "\n")
+		got, err := p.Confirm("ok?", true)
+		if err != nil {
+			t.Fatalf("Confirm(%q) error: %v", c, err)
+		}
+		if got {
+			t.Errorf("Confirm(%q) = true, want false", c)
+		}
+	}
+}
+
+func TestPrompter_Confirm_EmptyUsesDefault(t *testing.T) {
+	t.Run("default true", func(t *testing.T) {
+		p, _ := newTestPrompter("\n")
+		got, err := p.Confirm("ok?", true)
+		if err != nil {
+			t.Fatalf("Confirm() error: %v", err)
+		}
+		if !got {
+			t.Errorf("Confirm() = false, want true (default)")
+		}
+	})
+	t.Run("default false", func(t *testing.T) {
+		p, _ := newTestPrompter("\n")
+		got, err := p.Confirm("ok?", false)
+		if err != nil {
+			t.Fatalf("Confirm() error: %v", err)
+		}
+		if got {
+			t.Errorf("Confirm() = true, want false (default)")
+		}
+	})
+}
+
+func TestPrompter_Confirm_RetriesOnInvalid(t *testing.T) {
+	p, out := newTestPrompter("maybe\nyes\n")
+
+	got, err := p.Confirm("ok?", false)
+	if err != nil {
+		t.Fatalf("Confirm() error: %v", err)
+	}
+	if !got {
+		t.Errorf("Confirm() = false, want true")
+	}
+	if !strings.Contains(out.String(), "yes or no") {
+		t.Errorf("expected reprompt message, got %q", out.String())
+	}
+}
+
+func TestPrompter_Password_UsesInjectedReader(t *testing.T) {
+	p, _ := newTestPrompter("")
+	p.WithPasswordReader(func(prompt string) (string, error) {
+		if prompt != "password: " {
+			t.Errorf("password reader got prompt %q, want %q", prompt, "password: ")
+		}
+		return "s3cret", nil
+	})
+
+	got, err := p.Password("password: ")
+	if err != nil {
+		t.Fatalf("Password() error: %v", err)
+	}
+	if got != "s3cret" {
+		t.Errorf("Password() = %q, want %q", got, "s3cret")
+	}
+}
+
+func TestPrompter_Line_AcceptsLongPastedInput(t *testing.T) {
+	// Simulate a pasted URL longer than the default scanner buffer (64 KiB)
+	// to ensure the buffer-size override actually applies.
+	long := strings.Repeat("a", 200*1024)
+	p, _ := newTestPrompter(long + "\n")
+
+	got, err := p.Line("> ")
+	if err != nil {
+		t.Fatalf("Line() error: %v", err)
+	}
+	if got != long {
+		t.Errorf("Line() truncated long input: got %d bytes, want %d", len(got), len(long))
+	}
+}
+
+func TestPick_ReturnsSelectedOption(t *testing.T) {
+	p, out := newTestPrompter("2\n")
+
+	options := []string{"alpha", "beta", "gamma"}
+	got, err := Pick(p, "Choose one:", options, func(s string) string { return s })
+	if err != nil {
+		t.Fatalf("Pick() error: %v", err)
+	}
+	if got != "beta" {
+		t.Errorf("Pick() = %q, want %q", got, "beta")
+	}
+
+	// Verify the prompt and numbered list were written.
+	written := out.String()
+	for _, want := range []string{"Choose one:", "1) alpha", "2) beta", "3) gamma", "Enter number: "} {
+		if !strings.Contains(written, want) {
+			t.Errorf("expected output to contain %q, got %q", want, written)
+		}
+	}
+}
+
+func TestPick_RetriesOnOutOfRangeInput(t *testing.T) {
+	p, out := newTestPrompter("0\n2\n")
+
+	options := []string{"alpha", "beta", "gamma"}
+	got, err := Pick(p, "Choose one:", options, func(s string) string { return s })
+	if err != nil {
+		t.Fatalf("Pick() error: %v", err)
+	}
+	if got != "beta" {
+		t.Errorf("Pick() = %q, want %q", got, "beta")
+	}
+	if !strings.Contains(out.String(), "Please enter a number between 1 and 3") {
+		t.Errorf("expected reprompt message, got %q", out.String())
+	}
+}
+
+func TestPick_RetriesOnTooLargeInput(t *testing.T) {
+	p, _ := newTestPrompter("5\n1\n")
+
+	options := []string{"alpha", "beta", "gamma"}
+	got, err := Pick(p, "Choose one:", options, func(s string) string { return s })
+	if err != nil {
+		t.Fatalf("Pick() error: %v", err)
+	}
+	if got != "alpha" {
+		t.Errorf("Pick() = %q, want %q", got, "alpha")
+	}
+}
+
+func TestPick_RetriesOnNonNumericInput(t *testing.T) {
+	p, out := newTestPrompter("abc\n2\n")
+
+	options := []string{"alpha", "beta", "gamma"}
+	got, err := Pick(p, "Choose one:", options, func(s string) string { return s })
+	if err != nil {
+		t.Fatalf("Pick() error: %v", err)
+	}
+	if got != "beta" {
+		t.Errorf("Pick() = %q, want %q (second valid input should win)", got, "beta")
+	}
+	if !strings.Contains(out.String(), "Please enter a number between 1 and 3") {
+		t.Errorf("expected reprompt message, got %q", out.String())
+	}
+}
+
+func TestPick_EmptyOptionsReturnsError(t *testing.T) {
+	p, _ := newTestPrompter("")
+
+	_, err := Pick(p, "Choose:", []string{}, func(s string) string { return s })
+	if err == nil {
+		t.Fatal("Pick() with empty options expected error, got nil")
+	}
+}
+
+func TestPick_ReturnsErrorAfterThreeBadAttempts(t *testing.T) {
+	p, _ := newTestPrompter("a\nb\nc\n")
+
+	options := []string{"alpha", "beta"}
+	_, err := Pick(p, "Choose:", options, func(s string) string { return s })
+	if err == nil {
+		t.Fatal("Pick() expected error after 3 bad attempts, got nil")
+	}
+}
+
+func TestPick_UsesLabelFn(t *testing.T) {
+	type cal struct {
+		Name, Account string
+	}
+	p, out := newTestPrompter("1\n")
+
+	options := []cal{
+		{Name: "Work", Account: "alice@example.com"},
+		{Name: "Home", Account: "alice@home.example"},
+	}
+	got, err := Pick(p, "Pick a calendar:", options, func(c cal) string {
+		return c.Name + "  (" + c.Account + ")"
+	})
+	if err != nil {
+		t.Fatalf("Pick() error: %v", err)
+	}
+	if got.Name != "Work" {
+		t.Errorf("Pick() = %+v, want Work", got)
+	}
+	if !strings.Contains(out.String(), "Work  (alice@example.com)") {
+		t.Errorf("expected labelFn output in prompt, got %q", out.String())
+	}
+}
diff --git a/internal/sync/sync.go b/internal/sync/sync.go
new file mode 100644
index 0000000..fc7d1f2
--- /dev/null
+++ b/internal/sync/sync.go
@@ -0,0 +1,347 @@
+//go:build darwin
+
+package sync
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// EventKitFetcher fetches events from a macOS calendar by identifier over a
+// time range. It mirrors the signature of eventkit.FetchEvents so the real
+// implementation can be plugged in directly while tests substitute a fake.
+type EventKitFetcher func(calendarID string, start, end time.Time) ([]eventkit.Event, error)
+
+// CalDAVEventFetcher fetches every VEVENT-bearing resource from the
+// configured CalDAV calendar collection. It mirrors the signature of
+// CalDAVClient.FetchEvents so a configured client plugs straight in while
+// tests substitute a fake that returns canned RawEvents.
+type CalDAVEventFetcher func(ctx context.Context) ([]RawEvent, error)
+
+// CalDAVEventPutter uploads (or replaces) a VCALENDAR resource at href and
+// returns the server-assigned ETag. An empty href means "create at a new
+// path"; the implementation chooses the path. Mirrors
+// CalDAVClient.PutEvent so a configured client plugs in directly while
+// tests substitute a fake.
+type CalDAVEventPutter func(ctx context.Context, href string, data []byte) (string, error)
+
+// CalDAVEventDeleter removes the VCALENDAR resource at href. The etag
+// argument is forwarded as an If-Match precondition when non-empty.
+// Mirrors CalDAVClient.DeleteEvent.
+type CalDAVEventDeleter func(ctx context.Context, href, etag string) error
+
+// Engine carries the dependencies the sync logic needs. The zero value is
+// not useful: use NewEngine for a production engine, or construct one
+// directly with stub dependencies in tests.
+//
+// Subsequent pieces of the sync pipeline (diff, logging) will attach
+// themselves to this struct so the whole flow can be exercised without
+// touching the real Calendar.app or a real CalDAV server.
+type Engine struct {
+	// Now returns the current time. Defaults to time.Now in NewEngine; tests
+	// override it to make sync windows deterministic.
+	Now func() time.Time
+	// FetchEventKit fetches events from EventKit. Defaults to
+	// eventkit.FetchEvents in NewEngine.
+	FetchEventKit EventKitFetcher
+	// FetchCalDAV fetches every event currently on the target CalDAV
+	// calendar. NewEngine leaves this nil because it depends on a
+	// per-deployment CalDAVClient with credentials and a target URL; the
+	// caller is expected to construct a CalDAVClient and assign
+	// client.FetchEvents to this field before invoking sync operations
+	// that need it.
+	FetchCalDAV CalDAVEventFetcher
+	// PutCalDAV writes or replaces a VCALENDAR resource. NewEngine leaves
+	// this nil for the same reason as FetchCalDAV: a real CalDAVClient is
+	// required to PUT against a server. Tests substitute a fake.
+	PutCalDAV CalDAVEventPutter
+	// DeleteCalDAV removes a VCALENDAR resource. Likewise nil from
+	// NewEngine; the caller wires it up.
+	DeleteCalDAV CalDAVEventDeleter
+	// Log receives structured log output from the engine. Defaults to
+	// slog.Default in NewEngine. ToManagedMap-style helpers fall back to
+	// slog.Default themselves when this is nil, so leaving it unset is
+	// safe but undesirable.
+	Log *slog.Logger
+}
+
+// NewEngine returns an Engine wired to time.Now, the real EventKit bridge,
+// and slog.Default. FetchCalDAV must be set by the caller once a
+// CalDAVClient has been constructed and pointed at the target calendar
+// collection.
+func NewEngine() *Engine {
+	return &Engine{
+		Now:           time.Now,
+		FetchEventKit: eventkit.FetchEvents,
+		Log:           slog.Default(),
+	}
+}
+
+// SyncWindow returns the [start, end) time range the sync engine considers,
+// based on cfg.DaysBack and cfg.DaysForward and the Engine's clock. The
+// window is anchored at the current time rather than calendar-day
+// boundaries; that matches the Python version and avoids surprises around
+// timezone/DST boundaries near midnight.
+func (e *Engine) SyncWindow(cfg *Config) (start, end time.Time) {
+	now := e.Now()
+	start = now.AddDate(0, 0, -cfg.DaysBack)
+	end = now.AddDate(0, 0, cfg.DaysForward)
+	return start, end
+}
+
+// FetchWorkEvents returns the events from the configured macOS work
+// calendar that fall within the sync window. Returns a nil slice when the
+// calendar is empty.
+func (e *Engine) FetchWorkEvents(cfg *Config) ([]eventkit.Event, error) {
+	if cfg == nil {
+		return nil, errors.New("sync: cfg is nil")
+	}
+	if cfg.WorkCalendarID == "" {
+		return nil, errors.New("sync: cfg.WorkCalendarID is empty")
+	}
+	if e.FetchEventKit == nil {
+		return nil, errors.New("sync: FetchEventKit dependency is nil")
+	}
+	if e.Now == nil {
+		return nil, errors.New("sync: Now dependency is nil")
+	}
+
+	start, end := e.SyncWindow(cfg)
+	events, err := e.FetchEventKit(cfg.WorkCalendarID, start, end)
+	if err != nil {
+		return nil, fmt.Errorf("sync: fetch work events from %s: %w", cfg.WorkCalendarID, err)
+	}
+	return events, nil
+}
+
+// FetchManagedEvents pulls every event currently on the target CalDAV
+// calendar via the configured CalDAVEventFetcher, parses each resource's
+// X-WORK-CAL-ID metadata, and returns a map keyed by that work id so the
+// diff stage can match macOS events against their CalDAV counterparts in
+// O(1). A second return value lists managed events that were dropped as
+// duplicates (same X-WORK-CAL-ID); callers should queue those for
+// deletion to repair server-side state created by interrupted runs.
+//
+// Resources without an X-WORK-CAL-ID (events the user created directly in
+// the target calendar) are skipped silently — work-cal-sync only manages
+// the events it created. Unparseable resources log a warning and are
+// likewise skipped so a single bad item can't abort the whole sync.
+//
+// A nil ctx is rejected eagerly to avoid the silent-pass behaviour of
+// http.NewRequestWithContext when the fetcher is the real CalDAV client.
+func (e *Engine) FetchManagedEvents(ctx context.Context) (map[string]ManagedEvent, []ManagedEvent, error) {
+	if ctx == nil {
+		return nil, nil, errors.New("sync: ctx is nil")
+	}
+	if e.FetchCalDAV == nil {
+		return nil, nil, errors.New("sync: FetchCalDAV dependency is nil")
+	}
+
+	raws, err := e.FetchCalDAV(ctx)
+	if err != nil {
+		return nil, nil, fmt.Errorf("sync: fetch managed events: %w", err)
+	}
+	managed, dups := ToManagedMap(raws, e.Log)
+	return managed, dups, nil
+}
+
+// ApplyResult records the per-action counts and error tally produced by
+// Apply. It exists so callers (and the structured-logging step in task
+// 7.4) can report progress without re-walking the input slices.
+type ApplyResult struct {
+	Created int
+	Updated int
+	Deleted int
+	Errors  []error
+}
+
+// Apply executes the diff against the CalDAV server using the engine's
+// PutCalDAV and DeleteCalDAV dependencies.
+//
+// Behaviour:
+//   - For each event in diff.ToCreate, BuildVCalendar produces a fresh
+//     VCALENDAR with a generated UID and PutCalDAV is called with an
+//     empty href so the server (or the client helper) chooses a path.
+//   - For each pair in diff.ToUpdate, BuildVCalendar reuses the existing
+//     UID so the resource keeps its identity, and PutCalDAV is called
+//     with the existing href to overwrite the same resource.
+//   - For each entry in diff.ToDelete, DeleteCalDAV is called with the
+//     stored href and ETag so a server-side change made between fetch and
+//     apply can reject the delete via If-Match.
+//
+// Apply does not abort on the first error: every action is attempted, and
+// the encountered errors are collected into ApplyResult.Errors so the
+// caller can decide what to do with partial failures (one bad event
+// shouldn't strand a hundred good ones). The counts in the result reflect
+// only successful actions.
+//
+// A nil ctx, missing PutCalDAV (when there are creates or updates), or
+// missing DeleteCalDAV (when there are deletes) is rejected eagerly.
+func (e *Engine) Apply(ctx context.Context, diff DiffResult) (ApplyResult, error) {
+	var res ApplyResult
+	if ctx == nil {
+		return res, errors.New("sync: ctx is nil")
+	}
+	needPut := len(diff.ToCreate) > 0 || len(diff.ToUpdate) > 0
+	needDel := len(diff.ToDelete) > 0
+	if needPut && e.PutCalDAV == nil {
+		return res, errors.New("sync: PutCalDAV dependency is nil")
+	}
+	if needDel && e.DeleteCalDAV == nil {
+		return res, errors.New("sync: DeleteCalDAV dependency is nil")
+	}
+
+	log := e.logger()
+	totalActions := len(diff.ToCreate) + len(diff.ToUpdate) + len(diff.ToDelete)
+	const progressEvery = 25
+	progress := func(action string, n int) {
+		if totalActions > progressEvery && n%progressEvery == 0 {
+			log.Info("apply: progress",
+				"action", action,
+				"done", n,
+				"total_actions", totalActions)
+		}
+	}
+
+	for i, ev := range diff.ToCreate {
+		data, err := BuildVCalendar(ev, "")
+		if err != nil {
+			wrapped := fmt.Errorf("sync: build create for %s: %w", ev.ExternalID, err)
+			log.Error("apply: build create failed", "action", "create", "work_id", ev.ExternalID, "err", err)
+			res.Errors = append(res.Errors, wrapped)
+			continue
+		}
+		log.Debug("apply: create", "work_id", ev.ExternalID, "title", ev.Title)
+		if _, err := e.PutCalDAV(ctx, "", data); err != nil {
+			wrapped := fmt.Errorf("sync: create %s: %w", ev.ExternalID, err)
+			log.Error("apply: create failed", "action", "create", "work_id", ev.ExternalID, "err", err)
+			res.Errors = append(res.Errors, wrapped)
+			continue
+		}
+		res.Created++
+		progress("create", i+1)
+	}
+
+	for i, p := range diff.ToUpdate {
+		data, err := BuildVCalendar(p.Work, p.Managed.UID)
+		if err != nil {
+			wrapped := fmt.Errorf("sync: build update for %s: %w", p.Work.ExternalID, err)
+			log.Error("apply: build update failed", "action", "update", "work_id", p.Work.ExternalID, "href", p.Managed.Href, "err", err)
+			res.Errors = append(res.Errors, wrapped)
+			continue
+		}
+		log.Debug("apply: update", "work_id", p.Work.ExternalID, "title", p.Work.Title, "href", p.Managed.Href)
+		if _, err := e.PutCalDAV(ctx, p.Managed.Href, data); err != nil {
+			wrapped := fmt.Errorf("sync: update %s: %w", p.Work.ExternalID, err)
+			log.Error("apply: update failed", "action", "update", "work_id", p.Work.ExternalID, "href", p.Managed.Href, "err", err)
+			res.Errors = append(res.Errors, wrapped)
+			continue
+		}
+		res.Updated++
+		progress("update", i+1)
+	}
+
+	for i, m := range diff.ToDelete {
+		log.Debug("apply: delete", "work_id", m.WorkID, "href", m.Href)
+		if err := e.DeleteCalDAV(ctx, m.Href, m.ETag); err != nil {
+			wrapped := fmt.Errorf("sync: delete %s: %w", m.WorkID, err)
+			log.Error("apply: delete failed", "action", "delete", "work_id", m.WorkID, "href", m.Href, "err", err)
+			res.Errors = append(res.Errors, wrapped)
+			continue
+		}
+		res.Deleted++
+		progress("delete", i+1)
+	}
+
+	return res, nil
+}
+
+// logger returns e.Log when set, falling back to slog.Default so callers
+// can rely on a non-nil logger without each method having to guard.
+func (e *Engine) logger() *slog.Logger {
+	if e.Log != nil {
+		return e.Log
+	}
+	return slog.Default()
+}
+
+// Sync orchestrates a full sync cycle: fetch from EventKit, fetch managed
+// events from CalDAV, compute the diff, and apply the resulting actions.
+// It threads e.Log through each step so an operator inspecting the
+// launchd log gets a clear picture of what the run did:
+//
+//   - "sync starting"  with work_calendar_id, days_back, days_forward,
+//     sync_window_start, sync_window_end
+//   - "diff computed"  with creates, updates, deletes
+//   - per-action error logs from Apply (also collected into the result)
+//   - "sync complete"  with created, updated, deleted, errors
+//
+// Sync does not return Apply's collected errors as the top-level error;
+// partial failures are surfaced through ApplyResult.Errors. A non-nil
+// error from Sync indicates the run could not even produce a diff
+// (missing dependency, fetch failure, nil cfg/ctx).
+func (e *Engine) Sync(ctx context.Context, cfg *Config) (ApplyResult, error) {
+	var zero ApplyResult
+	if ctx == nil {
+		return zero, errors.New("sync: ctx is nil")
+	}
+	if cfg == nil {
+		return zero, errors.New("sync: cfg is nil")
+	}
+
+	log := e.logger()
+	start, end := e.SyncWindow(cfg)
+	log.Info("sync starting",
+		"work_calendar_id", cfg.WorkCalendarID,
+		"days_back", cfg.DaysBack,
+		"days_forward", cfg.DaysForward,
+		"sync_window_start", start,
+		"sync_window_end", end,
+	)
+
+	work, err := e.FetchWorkEvents(cfg)
+	if err != nil {
+		log.Error("sync: fetch work events failed", "err", err)
+		return zero, err
+	}
+
+	managed, dups, err := e.FetchManagedEvents(ctx)
+	if err != nil {
+		log.Error("sync: fetch managed events failed", "err", err)
+		return zero, err
+	}
+
+	diff := Diff(work, managed)
+	// Append duplicate managed events to the deletion queue so a sync
+	// run also repairs server-side duplication (e.g. from interrupted
+	// previous runs).
+	if len(dups) > 0 {
+		diff.ToDelete = append(diff.ToDelete, dups...)
+	}
+	log.Info("diff computed",
+		"work_events", len(work),
+		"managed_events", len(managed),
+		"creates", len(diff.ToCreate),
+		"updates", len(diff.ToUpdate),
+		"deletes", len(diff.ToDelete),
+	)
+
+	res, err := e.Apply(ctx, diff)
+	if err != nil {
+		log.Error("sync: apply failed", "err", err)
+		return res, err
+	}
+
+	log.Info("sync complete",
+		"created", res.Created,
+		"updated", res.Updated,
+		"deleted", res.Deleted,
+		"errors", len(res.Errors),
+	)
+	return res, nil
+}
diff --git a/internal/sync/sync_test.go b/internal/sync/sync_test.go
new file mode 100644
index 0000000..509001f
--- /dev/null
+++ b/internal/sync/sync_test.go
@@ -0,0 +1,704 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// fixedNow returns a clock function that always reports t. Used to make
+// the sync window deterministic in tests.
+func fixedNow(t time.Time) func() time.Time {
+	return func() time.Time { return t }
+}
+
+func TestSyncWindow_BoundsRelativeToNow(t *testing.T) {
+	now := time.Date(2024, 5, 15, 12, 30, 45, 0, time.UTC)
+	e := &Engine{Now: fixedNow(now)}
+
+	cfg := &Config{DaysBack: 7, DaysForward: 30}
+	start, end := e.SyncWindow(cfg)
+
+	wantStart := now.AddDate(0, 0, -7)
+	wantEnd := now.AddDate(0, 0, 30)
+
+	if !start.Equal(wantStart) {
+		t.Errorf("start = %v, want %v", start, wantStart)
+	}
+	if !end.Equal(wantEnd) {
+		t.Errorf("end = %v, want %v", end, wantEnd)
+	}
+}
+
+func TestSyncWindow_ZeroDaysProducesPointWindow(t *testing.T) {
+	// DaysBack=0 and DaysForward=0 is degenerate but valid; both bounds
+	// should equal "now". Confirm we don't accidentally shift them.
+	now := time.Date(2024, 5, 15, 12, 0, 0, 0, time.UTC)
+	e := &Engine{Now: fixedNow(now)}
+
+	start, end := e.SyncWindow(&Config{})
+	if !start.Equal(now) || !end.Equal(now) {
+		t.Errorf("got [%v, %v), want both %v for zero days", start, end, now)
+	}
+}
+
+func TestFetchWorkEvents_PassesWindowAndID(t *testing.T) {
+	now := time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC)
+	cfg := &Config{
+		WorkCalendarID: "cal-id-xyz",
+		DaysBack:       2,
+		DaysForward:    5,
+	}
+
+	want := []eventkit.Event{
+		{ExternalID: "evt-1", Title: "Standup"},
+		{ExternalID: "evt-2", Title: "Design review"},
+	}
+
+	var gotID string
+	var gotStart, gotEnd time.Time
+	fetcher := func(id string, start, end time.Time) ([]eventkit.Event, error) {
+		gotID = id
+		gotStart = start
+		gotEnd = end
+		return want, nil
+	}
+
+	e := &Engine{Now: fixedNow(now), FetchEventKit: fetcher}
+	got, err := e.FetchWorkEvents(cfg)
+	if err != nil {
+		t.Fatalf("FetchWorkEvents error: %v", err)
+	}
+
+	if gotID != cfg.WorkCalendarID {
+		t.Errorf("calendar id = %q, want %q", gotID, cfg.WorkCalendarID)
+	}
+	if !gotStart.Equal(now.AddDate(0, 0, -2)) {
+		t.Errorf("start = %v, want %v", gotStart, now.AddDate(0, 0, -2))
+	}
+	if !gotEnd.Equal(now.AddDate(0, 0, 5)) {
+		t.Errorf("end = %v, want %v", gotEnd, now.AddDate(0, 0, 5))
+	}
+	if len(got) != len(want) {
+		t.Fatalf("got %d events, want %d", len(got), len(want))
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Errorf("event[%d] = %+v, want %+v", i, got[i], want[i])
+		}
+	}
+}
+
+func TestFetchWorkEvents_PropagatesFetcherError(t *testing.T) {
+	wantErr := errors.New("permission denied")
+	e := &Engine{
+		Now: fixedNow(time.Now()),
+		FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+			return nil, wantErr
+		},
+	}
+	cfg := &Config{WorkCalendarID: "cal-id", DaysBack: 1, DaysForward: 1}
+
+	_, err := e.FetchWorkEvents(cfg)
+	if err == nil {
+		t.Fatal("FetchWorkEvents() returned nil error, want wrapped fetcher error")
+	}
+	if !errors.Is(err, wantErr) {
+		t.Errorf("err = %v, want chain to include %v", err, wantErr)
+	}
+}
+
+func TestFetchWorkEvents_NilSliceWhenEmpty(t *testing.T) {
+	e := &Engine{
+		Now: fixedNow(time.Now()),
+		FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+			return nil, nil
+		},
+	}
+	cfg := &Config{WorkCalendarID: "cal-id", DaysBack: 1, DaysForward: 1}
+
+	got, err := e.FetchWorkEvents(cfg)
+	if err != nil {
+		t.Fatalf("FetchWorkEvents error: %v", err)
+	}
+	if got != nil {
+		t.Errorf("got %v, want nil slice", got)
+	}
+}
+
+func TestFetchWorkEvents_RejectsBadInputs(t *testing.T) {
+	good := &Engine{
+		Now: time.Now,
+		FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+			return nil, nil
+		},
+	}
+
+	cases := []struct {
+		name string
+		eng  *Engine
+		cfg  *Config
+	}{
+		{
+			name: "nil cfg",
+			eng:  good,
+			cfg:  nil,
+		},
+		{
+			name: "empty calendar id",
+			eng:  good,
+			cfg:  &Config{WorkCalendarID: "", DaysBack: 1, DaysForward: 1},
+		},
+		{
+			name: "nil fetcher",
+			eng:  &Engine{Now: time.Now, FetchEventKit: nil},
+			cfg:  &Config{WorkCalendarID: "cal-id"},
+		},
+		{
+			name: "nil clock",
+			eng: &Engine{Now: nil, FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+				return nil, nil
+			}},
+			cfg: &Config{WorkCalendarID: "cal-id"},
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := tc.eng.FetchWorkEvents(tc.cfg); err == nil {
+				t.Error("expected error, got nil")
+			}
+		})
+	}
+}
+
+func TestNewEngine_WiresDefaults(t *testing.T) {
+	e := NewEngine()
+	if e.Now == nil {
+		t.Error("NewEngine().Now is nil")
+	}
+	if e.FetchEventKit == nil {
+		t.Error("NewEngine().FetchEventKit is nil")
+	}
+	if e.Log == nil {
+		t.Error("NewEngine().Log is nil")
+	}
+	// FetchCalDAV/PutCalDAV/DeleteCalDAV are intentionally left nil —
+	// see the field docs on Engine.
+	if e.FetchCalDAV != nil {
+		t.Error("NewEngine().FetchCalDAV should be nil; caller wires the CalDAV client")
+	}
+	if e.PutCalDAV != nil {
+		t.Error("NewEngine().PutCalDAV should be nil; caller wires the CalDAV client")
+	}
+	if e.DeleteCalDAV != nil {
+		t.Error("NewEngine().DeleteCalDAV should be nil; caller wires the CalDAV client")
+	}
+	// Sanity check: clock returns something close to time.Now.
+	delta := time.Since(e.Now())
+	if delta < 0 {
+		delta = -delta
+	}
+	if delta > time.Second {
+		t.Errorf("NewEngine().Now drifted from time.Now by %v", delta)
+	}
+}
+
+// fakeCalDAVFetcher returns a CalDAVEventFetcher that records the context
+// it was called with and returns the canned events/err. Useful for
+// asserting that FetchManagedEvents threads its arguments correctly.
+func fakeCalDAVFetcher(events []RawEvent, err error, ctxOut *context.Context) CalDAVEventFetcher {
+	return func(ctx context.Context) ([]RawEvent, error) {
+		if ctxOut != nil {
+			*ctxOut = ctx
+		}
+		return events, err
+	}
+}
+
+func TestFetchManagedEvents_TypicalCase(t *testing.T) {
+	mod := time.Date(2024, 5, 15, 10, 0, 0, 0, time.UTC)
+	specs := []struct {
+		extID, uid, href, etag string
+	}{
+		{"ek-1", "uid-1", "/cal/work/1.ics", "etag-1"},
+		{"ek-2", "uid-2", "/cal/work/2.ics", "etag-2"},
+	}
+	raws := make([]RawEvent, 0, len(specs))
+	for _, s := range specs {
+		data, err := BuildVCalendar(eventkit.Event{
+			ExternalID:   s.extID,
+			Title:        "T " + s.extID,
+			Start:        time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+			End:          time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+			LastModified: mod,
+		}, s.uid)
+		if err != nil {
+			t.Fatalf("BuildVCalendar: %v", err)
+		}
+		raws = append(raws, RawEvent{Href: s.href, Data: data, ETag: s.etag})
+	}
+
+	var gotCtx context.Context
+	e := &Engine{
+		Now:         time.Now,
+		FetchCalDAV: fakeCalDAVFetcher(raws, nil, &gotCtx),
+	}
+
+	ctx := context.Background()
+	got, _, err := e.FetchManagedEvents(ctx)
+	if err != nil {
+		t.Fatalf("FetchManagedEvents error: %v", err)
+	}
+	if gotCtx != ctx {
+		t.Errorf("fetcher received different ctx than passed in")
+	}
+	if len(got) != len(specs) {
+		t.Fatalf("len(map) = %d, want %d", len(got), len(specs))
+	}
+	for _, s := range specs {
+		me, ok := got[s.extID]
+		if !ok {
+			t.Errorf("missing key %q", s.extID)
+			continue
+		}
+		if me.Href != s.href || me.ETag != s.etag || me.UID != s.uid || me.WorkID != s.extID {
+			t.Errorf("entry for %s = %+v, want href=%q etag=%q uid=%q workID=%q",
+				s.extID, me, s.href, s.etag, s.uid, s.extID)
+		}
+		if me.ModifiedUnix != mod.Unix() {
+			t.Errorf("%s: ModifiedUnix = %d, want %d", s.extID, me.ModifiedUnix, mod.Unix())
+		}
+	}
+}
+
+func TestFetchManagedEvents_SkipsEventsWithoutWorkID(t *testing.T) {
+	const foreign = "BEGIN:VCALENDAR\r\n" +
+		"VERSION:2.0\r\n" +
+		"PRODID:-//someone-else//EN\r\n" +
+		"BEGIN:VEVENT\r\n" +
+		"UID:not-ours\r\n" +
+		"DTSTAMP:20240515T120000Z\r\n" +
+		"SUMMARY:User-created event\r\n" +
+		"END:VEVENT\r\n" +
+		"END:VCALENDAR\r\n"
+
+	managedData, err := BuildVCalendar(eventkit.Event{
+		ExternalID: "ek-managed",
+		Title:      "Managed",
+		Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-managed")
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+
+	raws := []RawEvent{
+		{Href: "/cal/work/foreign.ics", Data: []byte(foreign), ETag: "etag-f"},
+		{Href: "/cal/work/managed.ics", Data: managedData, ETag: "etag-m"},
+	}
+
+	e := &Engine{
+		Now:         time.Now,
+		FetchCalDAV: fakeCalDAVFetcher(raws, nil, nil),
+		Log:         discardLogger(),
+	}
+
+	got, _, err := e.FetchManagedEvents(context.Background())
+	if err != nil {
+		t.Fatalf("FetchManagedEvents error: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1 (foreign event must be skipped)", len(got))
+	}
+	if _, ok := got["ek-managed"]; !ok {
+		t.Errorf("expected key ek-managed in map, got %v", got)
+	}
+}
+
+func TestFetchManagedEvents_PropagatesFetcherError(t *testing.T) {
+	wantErr := errors.New("connection refused")
+	e := &Engine{
+		Now:         time.Now,
+		FetchCalDAV: fakeCalDAVFetcher(nil, wantErr, nil),
+	}
+
+	got, _, err := e.FetchManagedEvents(context.Background())
+	if err == nil {
+		t.Fatal("FetchManagedEvents returned nil error, want wrapped fetcher error")
+	}
+	if !errors.Is(err, wantErr) {
+		t.Errorf("err = %v, want chain to include %v", err, wantErr)
+	}
+	if got != nil {
+		t.Errorf("got map %v, want nil on error", got)
+	}
+}
+
+// TestFetchManagedEvents_BadEventDataLogged confirms unparseable bytes do
+// not abort the whole fetch: the engine logs a warning and continues.
+// Aborting on a single corrupt resource would let one bad event on the
+// server permanently break sync.
+func TestFetchManagedEvents_BadEventDataLogged(t *testing.T) {
+	good, err := BuildVCalendar(eventkit.Event{
+		ExternalID: "ek-good",
+		Title:      "Good",
+		Start:      time.Date(2024, 5, 15, 9, 0, 0, 0, time.UTC),
+		End:        time.Date(2024, 5, 15, 9, 30, 0, 0, time.UTC),
+	}, "uid-good")
+	if err != nil {
+		t.Fatalf("BuildVCalendar: %v", err)
+	}
+
+	raws := []RawEvent{
+		{Href: "/cal/work/garbage.ics", Data: []byte("not a calendar"), ETag: "etag-g"},
+		{Href: "/cal/work/good.ics", Data: good, ETag: "etag-good"},
+	}
+
+	var logBuf bytes.Buffer
+	e := &Engine{
+		Now:         time.Now,
+		FetchCalDAV: fakeCalDAVFetcher(raws, nil, nil),
+		Log:         slog.New(slog.NewTextHandler(&logBuf, &slog.HandlerOptions{Level: slog.LevelWarn})),
+	}
+
+	got, _, err := e.FetchManagedEvents(context.Background())
+	if err != nil {
+		t.Fatalf("FetchManagedEvents error: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("len(map) = %d, want 1 (only the good event)", len(got))
+	}
+	if _, ok := got["ek-good"]; !ok {
+		t.Errorf("expected key ek-good in map, got %v", got)
+	}
+	if !strings.Contains(logBuf.String(), "skipping unparseable CalDAV event") {
+		t.Errorf("expected warning about unparseable event, got:\n%s", logBuf.String())
+	}
+}
+
+func TestFetchManagedEvents_EmptyCalendar(t *testing.T) {
+	e := &Engine{
+		Now:         time.Now,
+		FetchCalDAV: fakeCalDAVFetcher(nil, nil, nil),
+		Log:         discardLogger(),
+	}
+
+	got, _, err := e.FetchManagedEvents(context.Background())
+	if err != nil {
+		t.Fatalf("FetchManagedEvents error: %v", err)
+	}
+	if got == nil {
+		t.Fatal("FetchManagedEvents returned nil map, want empty non-nil map")
+	}
+	if len(got) != 0 {
+		t.Errorf("len(map) = %d, want 0", len(got))
+	}
+}
+
+func TestFetchManagedEvents_RejectsBadInputs(t *testing.T) {
+	cases := []struct {
+		name string
+		eng  *Engine
+		ctx  context.Context
+	}{
+		{
+			name: "nil ctx",
+			eng:  &Engine{FetchCalDAV: fakeCalDAVFetcher(nil, nil, nil)},
+			ctx:  nil,
+		},
+		{
+			name: "nil fetcher",
+			eng:  &Engine{FetchCalDAV: nil},
+			ctx:  context.Background(),
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, _, err := tc.eng.FetchManagedEvents(tc.ctx); err == nil {
+				t.Error("expected error, got nil")
+			}
+		})
+	}
+}
+
+// jsonLogger returns a slog.Logger that writes JSON records to buf so
+// tests can decode each line and assert on individual keys/values.
+func jsonLogger(buf *bytes.Buffer) *slog.Logger {
+	return slog.New(slog.NewJSONHandler(buf, &slog.HandlerOptions{Level: slog.LevelDebug}))
+}
+
+// parseLogLines splits buf into JSON records keyed by the log message.
+// When two records share a message the later one wins; that's fine for
+// these tests because each message we care about appears exactly once.
+func parseLogLines(t *testing.T, buf *bytes.Buffer) map[string]map[string]any {
+	t.Helper()
+	out := make(map[string]map[string]any)
+	for _, line := range strings.Split(strings.TrimSpace(buf.String()), "\n") {
+		if line == "" {
+			continue
+		}
+		var rec map[string]any
+		if err := json.Unmarshal([]byte(line), &rec); err != nil {
+			t.Fatalf("parse log line %q: %v", line, err)
+		}
+		msg, _ := rec["msg"].(string)
+		out[msg] = rec
+	}
+	return out
+}
+
+func TestApply_LogsPerActionErrors(t *testing.T) {
+	diff := DiffResult{
+		ToCreate: []eventkit.Event{makeWork("ek-create", 1)},
+		ToUpdate: []DiffPair{{
+			Work:    makeWork("ek-update", 2),
+			Managed: makeManaged("ek-update", 1),
+		}},
+		ToDelete: []ManagedEvent{makeManaged("ek-delete", 1)},
+	}
+
+	putErr := errors.New("put kaboom")
+	delErr := errors.New("del kaboom")
+	putFn := func(_ context.Context, href string, _ []byte) (string, error) {
+		return "", putErr
+	}
+	delFn := func(_ context.Context, _, _ string) error {
+		return delErr
+	}
+
+	var buf bytes.Buffer
+	e := &Engine{
+		Now:          time.Now,
+		PutCalDAV:    putFn,
+		DeleteCalDAV: delFn,
+		Log:          jsonLogger(&buf),
+	}
+
+	res, err := e.Apply(context.Background(), diff)
+	if err != nil {
+		t.Fatalf("Apply: %v", err)
+	}
+	if len(res.Errors) != 3 {
+		t.Fatalf("len(res.Errors) = %d, want 3", len(res.Errors))
+	}
+
+	// Walk every JSON line and tally action errors. We can't key by msg
+	// because three records share "apply: ... failed" prefixes with
+	// different actions.
+	var creates, updates, deletes int
+	for _, line := range strings.Split(strings.TrimSpace(buf.String()), "\n") {
+		if line == "" {
+			continue
+		}
+		var rec map[string]any
+		if err := json.Unmarshal([]byte(line), &rec); err != nil {
+			t.Fatalf("parse log line %q: %v", line, err)
+		}
+		// The Apply loop now also emits DEBUG records for each
+		// per-event "apply: create / update / delete" attempt. We're
+		// only counting failures here, so skip non-ERROR lines.
+		if rec["level"] != "ERROR" {
+			continue
+		}
+		switch rec["action"] {
+		case "create":
+			creates++
+			if rec["work_id"] != "ek-create" {
+				t.Errorf("create log work_id = %v, want ek-create", rec["work_id"])
+			}
+		case "update":
+			updates++
+			if rec["work_id"] != "ek-update" {
+				t.Errorf("update log work_id = %v, want ek-update", rec["work_id"])
+			}
+		case "delete":
+			deletes++
+			if rec["work_id"] != "ek-delete" {
+				t.Errorf("delete log work_id = %v, want ek-delete", rec["work_id"])
+			}
+		default:
+			t.Errorf("unexpected action %v in log line: %s", rec["action"], line)
+		}
+	}
+	if creates != 1 || updates != 1 || deletes != 1 {
+		t.Errorf("per-action error counts = create:%d update:%d delete:%d, want 1/1/1",
+			creates, updates, deletes)
+	}
+}
+
+func TestSync_LogsStartDiffAndCompletionWithCounts(t *testing.T) {
+	now := time.Date(2024, 5, 15, 12, 0, 0, 0, time.UTC)
+	cfg := &Config{
+		WorkCalendarID: "cal-xyz",
+		DaysBack:       3,
+		DaysForward:    7,
+	}
+
+	// One create (no managed counterpart), one update (modified
+	// differs), one delete (managed without a work counterpart).
+	work := []eventkit.Event{
+		makeWork("ek-create", 1000),
+		makeWork("ek-update", 3000),
+	}
+	managedRaw := func(extID string, modUnix int64) RawEvent {
+		data, err := BuildVCalendar(eventkit.Event{
+			ExternalID:   extID,
+			Title:        "T " + extID,
+			Start:        now,
+			End:          now.Add(30 * time.Minute),
+			LastModified: time.Unix(modUnix, 0),
+		}, "uid-"+extID)
+		if err != nil {
+			t.Fatalf("BuildVCalendar: %v", err)
+		}
+		return RawEvent{Href: "/cal/" + extID + ".ics", Data: data, ETag: "etag-" + extID}
+	}
+	managed := []RawEvent{
+		managedRaw("ek-update", 2999), // older modified -> update
+		managedRaw("ek-delete", 1234), // not in work -> delete
+	}
+
+	put := &fakePutter{}
+	del := &fakeDeleter{}
+
+	var buf bytes.Buffer
+	e := &Engine{
+		Now: fixedNow(now),
+		FetchEventKit: func(id string, _, _ time.Time) ([]eventkit.Event, error) {
+			if id != cfg.WorkCalendarID {
+				t.Errorf("FetchEventKit called with id %q, want %q", id, cfg.WorkCalendarID)
+			}
+			return work, nil
+		},
+		FetchCalDAV:  fakeCalDAVFetcher(managed, nil, nil),
+		PutCalDAV:    put.Put,
+		DeleteCalDAV: del.Delete,
+		Log:          jsonLogger(&buf),
+	}
+
+	res, err := e.Sync(context.Background(), cfg)
+	if err != nil {
+		t.Fatalf("Sync: %v", err)
+	}
+	if res.Created != 1 || res.Updated != 1 || res.Deleted != 1 {
+		t.Errorf("counts = create:%d update:%d delete:%d, want 1/1/1",
+			res.Created, res.Updated, res.Deleted)
+	}
+	if len(res.Errors) != 0 {
+		t.Errorf("res.Errors = %v, want empty", res.Errors)
+	}
+
+	logs := parseLogLines(t, &buf)
+
+	startRec, ok := logs["sync starting"]
+	if !ok {
+		t.Fatalf("missing 'sync starting' log; got: %v", logs)
+	}
+	if startRec["work_calendar_id"] != cfg.WorkCalendarID {
+		t.Errorf("sync starting work_calendar_id = %v, want %v",
+			startRec["work_calendar_id"], cfg.WorkCalendarID)
+	}
+	// JSON numbers decode as float64.
+	if got, want := startRec["days_back"], float64(cfg.DaysBack); got != want {
+		t.Errorf("sync starting days_back = %v, want %v", got, want)
+	}
+	if got, want := startRec["days_forward"], float64(cfg.DaysForward); got != want {
+		t.Errorf("sync starting days_forward = %v, want %v", got, want)
+	}
+	if startRec["sync_window_start"] == nil || startRec["sync_window_end"] == nil {
+		t.Errorf("sync starting missing window bounds; got %+v", startRec)
+	}
+
+	diffRec, ok := logs["diff computed"]
+	if !ok {
+		t.Fatalf("missing 'diff computed' log; got: %v", logs)
+	}
+	if got, want := diffRec["creates"], float64(1); got != want {
+		t.Errorf("diff computed creates = %v, want %v", got, want)
+	}
+	if got, want := diffRec["updates"], float64(1); got != want {
+		t.Errorf("diff computed updates = %v, want %v", got, want)
+	}
+	if got, want := diffRec["deletes"], float64(1); got != want {
+		t.Errorf("diff computed deletes = %v, want %v", got, want)
+	}
+
+	doneRec, ok := logs["sync complete"]
+	if !ok {
+		t.Fatalf("missing 'sync complete' log; got: %v", logs)
+	}
+	if got, want := doneRec["created"], float64(1); got != want {
+		t.Errorf("sync complete created = %v, want %v", got, want)
+	}
+	if got, want := doneRec["updated"], float64(1); got != want {
+		t.Errorf("sync complete updated = %v, want %v", got, want)
+	}
+	if got, want := doneRec["deleted"], float64(1); got != want {
+		t.Errorf("sync complete deleted = %v, want %v", got, want)
+	}
+	if got, want := doneRec["errors"], float64(0); got != want {
+		t.Errorf("sync complete errors = %v, want %v", got, want)
+	}
+}
+
+func TestSync_PropagatesFetchErrors(t *testing.T) {
+	cfg := &Config{WorkCalendarID: "cal-xyz", DaysBack: 1, DaysForward: 1}
+
+	t.Run("work fetch fails", func(t *testing.T) {
+		fetchErr := errors.New("eventkit boom")
+		e := &Engine{
+			Now: time.Now,
+			FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+				return nil, fetchErr
+			},
+			FetchCalDAV: fakeCalDAVFetcher(nil, nil, nil),
+			Log:         discardLogger(),
+		}
+		_, err := e.Sync(context.Background(), cfg)
+		if !errors.Is(err, fetchErr) {
+			t.Errorf("err = %v, want chain to include %v", err, fetchErr)
+		}
+	})
+
+	t.Run("managed fetch fails", func(t *testing.T) {
+		fetchErr := errors.New("caldav boom")
+		e := &Engine{
+			Now: time.Now,
+			FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+				return nil, nil
+			},
+			FetchCalDAV: fakeCalDAVFetcher(nil, fetchErr, nil),
+			Log:         discardLogger(),
+		}
+		_, err := e.Sync(context.Background(), cfg)
+		if !errors.Is(err, fetchErr) {
+			t.Errorf("err = %v, want chain to include %v", err, fetchErr)
+		}
+	})
+}
+
+func TestSync_RejectsBadInputs(t *testing.T) {
+	e := &Engine{
+		Now: time.Now,
+		FetchEventKit: func(string, time.Time, time.Time) ([]eventkit.Event, error) {
+			return nil, nil
+		},
+		FetchCalDAV: fakeCalDAVFetcher(nil, nil, nil),
+		Log:         discardLogger(),
+	}
+	if _, err := e.Sync(nil, &Config{WorkCalendarID: "x"}); err == nil {
+		t.Error("nil ctx: expected error, got nil")
+	}
+	if _, err := e.Sync(context.Background(), nil); err == nil {
+		t.Error("nil cfg: expected error, got nil")
+	}
+}
diff --git a/internal/sync/url.go b/internal/sync/url.go
new file mode 100644
index 0000000..193c527
--- /dev/null
+++ b/internal/sync/url.go
@@ -0,0 +1,54 @@
+//go:build darwin
+
+package sync
+
+import (
+	"errors"
+	"fmt"
+	"net/url"
+	"strings"
+)
+
+// ValidateServerURL ensures rawURL is a usable CalDAV base URL.
+// It must be parseable, have a scheme, and have a host. The scheme must
+// be HTTPS unless the host is a loopback address (localhost, 127.0.0.1,
+// or ::1).
+func ValidateServerURL(rawURL string) error {
+	if strings.TrimSpace(rawURL) == "" {
+		return errors.New("url is required")
+	}
+
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return fmt.Errorf("invalid url: %w", err)
+	}
+
+	if u.Scheme == "" {
+		return errors.New("url must include a scheme (https://...)")
+	}
+	if u.Host == "" {
+		return errors.New("url must include a host")
+	}
+
+	switch strings.ToLower(u.Scheme) {
+	case "https":
+		return nil
+	case "http":
+		if isLoopbackHost(u.Hostname()) {
+			return nil
+		}
+		return errors.New("http is only allowed for loopback hosts; use https or set host to localhost/127.0.0.1/::1")
+	default:
+		return fmt.Errorf("unsupported url scheme %q; use https", u.Scheme)
+	}
+}
+
+// isLoopbackHost reports whether host is one of the loopback hostnames
+// or addresses we accept for plain http: localhost, 127.0.0.1, or ::1.
+func isLoopbackHost(host string) bool {
+	switch strings.ToLower(host) {
+	case "localhost", "127.0.0.1", "::1":
+		return true
+	}
+	return false
+}
diff --git a/internal/sync/url_test.go b/internal/sync/url_test.go
new file mode 100644
index 0000000..862f993
--- /dev/null
+++ b/internal/sync/url_test.go
@@ -0,0 +1,41 @@
+//go:build darwin
+
+package sync
+
+import "testing"
+
+func TestValidateServerURL_Accepts(t *testing.T) {
+	cases := []string{
+		"https://example.com",
+		"https://cal.example.com:8443/path",
+		"http://localhost:5232",
+		"http://127.0.0.1",
+		"http://[::1]",
+	}
+	for _, in := range cases {
+		in := in
+		t.Run(in, func(t *testing.T) {
+			if err := ValidateServerURL(in); err != nil {
+				t.Errorf("ValidateServerURL(%q) returned error: %v; want nil", in, err)
+			}
+		})
+	}
+}
+
+func TestValidateServerURL_Rejects(t *testing.T) {
+	cases := []string{
+		"",
+		"cal.example.com",
+		"http://example.com",
+		"https://",
+		"ftp://example.com",
+	}
+	for _, in := range cases {
+		in := in
+		t.Run(in, func(t *testing.T) {
+			if err := ValidateServerURL(in); err == nil {
+				t.Errorf("ValidateServerURL(%q) returned nil; want error", in)
+			}
+		})
+	}
+}
diff --git a/internal/sync/wizard.go b/internal/sync/wizard.go
new file mode 100644
index 0000000..526325b
--- /dev/null
+++ b/internal/sync/wizard.go
@@ -0,0 +1,370 @@
+//go:build darwin
+
+package sync
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// EventKitProvider is the subset of the eventkit package the wizard
+// depends on. Defining it as an interface lets tests inject a fake that
+// returns canned calendars without touching Calendar.app.
+type EventKitProvider interface {
+	ListExchangeCalendars() ([]eventkit.Calendar, error)
+}
+
+// CalDAVDialer abstracts the "connect with these credentials and list
+// calendars" step. Tests inject a fake; production wires this to a small
+// adapter around CalDAVClient.
+type CalDAVDialer interface {
+	// ListCalendars connects to the given URL with the given
+	// credentials and returns the calendars the principal can access.
+	ListCalendars(ctx context.Context, serverURL, username, password string) ([]CalendarInfo, error)
+}
+
+// Default sync window when the user just hits Enter and no existing
+// config supplies a different value. Mirrors the Python wizard.
+const (
+	defaultDaysBack    = 7
+	defaultDaysForward = 90
+)
+
+// maxURLValidationAttempts is the number of times the wizard will
+// re-prompt for a CalDAV server URL after a ValidateServerURL failure
+// before giving up.
+const maxURLValidationAttempts = 3
+
+// RunSetup runs the interactive setup wizard. It uses the supplied
+// Prompter for I/O, the existing config (or nil) to seed default
+// values, and the EventKitProvider/CalDAVDialer interfaces to fetch
+// calendar lists. It returns the new Config and the user-supplied
+// CalDAV password (caller decides what to do with it — typically
+// stash in Keychain).
+func RunSetup(p *Prompter, existing *Config, ek EventKitProvider, dial CalDAVDialer) (*Config, string, error) {
+	if p == nil {
+		return nil, "", errors.New("wizard: prompter is required")
+	}
+	if ek == nil {
+		return nil, "", errors.New("wizard: eventkit provider is required")
+	}
+	if dial == nil {
+		return nil, "", errors.New("wizard: caldav dialer is required")
+	}
+
+	if existing == nil {
+		printBanner(p, "work-cal-sync first-run setup")
+	} else {
+		printBanner(p, "work-cal-sync re-configuration")
+	}
+
+	// 1. Detect Exchange calendars and pick one.
+	chosenEK, err := pickExchangeCalendar(p, existing, ek)
+	if err != nil {
+		return nil, "", err
+	}
+
+	// 2. CalDAV server URL with validation retries.
+	serverURL, err := promptServerURL(p, existing)
+	if err != nil {
+		return nil, "", err
+	}
+
+	// 3. CalDAV username.
+	username, err := promptUsername(p, existing)
+	if err != nil {
+		return nil, "", err
+	}
+
+	// 4. CalDAV password — always prompt fresh; we never display an
+	// existing password.
+	password, err := p.Password("CalDAV password: ")
+	if err != nil {
+		return nil, "", err
+	}
+
+	// 5. Connect, list calendars, pick one.
+	chosenCal, err := pickCalDAVCalendar(p, existing, dial, serverURL, username, password)
+	if err != nil {
+		return nil, "", err
+	}
+
+	// 6. Sync window.
+	daysBack, err := p.Int("How many days back to sync", existingDaysBack(existing))
+	if err != nil {
+		return nil, "", err
+	}
+	daysForward, err := p.Int("How many days forward to sync", existingDaysForward(existing))
+	if err != nil {
+		return nil, "", err
+	}
+
+	cfg := &Config{
+		WorkCalendarID:    chosenEK.Identifier,
+		WorkCalendarName:  chosenEK.Title,
+		CalDAVServer:      serverURL,
+		CalDAVUsername:    username,
+		CalDAVCalendarURL: chosenCal.URL,
+		DaysBack:          daysBack,
+		DaysForward:       daysForward,
+	}
+
+	printSummary(p, cfg)
+	return cfg, password, nil
+}
+
+// CompleteSetup runs the wizard, persists the resulting Config to disk,
+// and stores the user-supplied CalDAV password in the keyring under
+// KeyringService keyed by cfg.CalDAVUsername. It is the single entry
+// point the CLI's `setup` subcommand should call so config persistence
+// and keyring writes stay in lockstep.
+//
+// On success it returns the saved Config. Any error from RunSetup,
+// Save, or the keyring write is surfaced unchanged so the caller can
+// distinguish (e.g.) a wizard cancellation from a Keychain failure.
+func CompleteSetup(p *Prompter, existing *Config, ek EventKitProvider, dial CalDAVDialer, ks KeyringStore) (*Config, error) {
+	if p == nil {
+		return nil, errors.New("wizard: prompter is required")
+	}
+	if ks == nil {
+		return nil, errors.New("wizard: keyring store is required")
+	}
+
+	cfg, password, err := RunSetup(p, existing, ek, dial)
+	if err != nil {
+		return nil, err
+	}
+
+	if err := Save(cfg); err != nil {
+		return nil, fmt.Errorf("wizard: save config: %w", err)
+	}
+	cfgPath, err := Path()
+	if err != nil {
+		return nil, fmt.Errorf("wizard: resolve config path: %w", err)
+	}
+	if _, err := fmt.Fprintf(p.out, "✓ Config saved to %s\n", cfgPath); err != nil {
+		return nil, err
+	}
+
+	if err := ks.Set(cfg.CalDAVUsername, password); err != nil {
+		return nil, fmt.Errorf("wizard: store password in keyring: %w", err)
+	}
+	if _, err := fmt.Fprintln(p.out, "✓ Password saved to macOS Keychain"); err != nil {
+		return nil, err
+	}
+
+	return cfg, nil
+}
+
+// pickExchangeCalendar lists Exchange/O365 calendars and asks the user to
+// pick one, defaulting to the previously-configured calendar (by ID) when
+// it still exists.
+func pickExchangeCalendar(p *Prompter, existing *Config, ek EventKitProvider) (eventkit.Calendar, error) {
+	var zero eventkit.Calendar
+
+	if _, err := fmt.Fprintln(p.out); err != nil {
+		return zero, err
+	}
+	if _, err := fmt.Fprintln(p.out, "Detecting Exchange/O365 calendars in Calendar.app..."); err != nil {
+		return zero, err
+	}
+
+	cals, err := ek.ListExchangeCalendars()
+	if err != nil {
+		return zero, fmt.Errorf("wizard: list Exchange calendars: %w", err)
+	}
+	if len(cals) == 0 {
+		return zero, errors.New("wizard: no Exchange/O365 calendars found in Calendar.app; add your work account via System Settings > Internet Accounts first")
+	}
+
+	defIdx := -1
+	if existing != nil && existing.WorkCalendarID != "" {
+		for i, c := range cals {
+			if c.Identifier == existing.WorkCalendarID {
+				defIdx = i
+				break
+			}
+		}
+	}
+
+	return pickWithDefault(p, "Which calendar contains your work events?", cals, func(c eventkit.Calendar) string {
+		return fmt.Sprintf("%s  (%s)", c.Title, c.SourceTitle)
+	}, defIdx)
+}
+
+// promptServerURL asks for the CalDAV server URL, seeded with
+// existing.CalDAVServer if non-empty. It re-prompts up to
+// maxURLValidationAttempts times when ValidateServerURL rejects the
+// input.
+func promptServerURL(p *Prompter, existing *Config) (string, error) {
+	if _, err := fmt.Fprintln(p.out); err != nil {
+		return "", err
+	}
+
+	var lastErr error
+	for attempt := 0; attempt < maxURLValidationAttempts; attempt++ {
+		var (
+			s   string
+			err error
+		)
+		if existing != nil && existing.CalDAVServer != "" {
+			s, err = p.LineDefault("CalDAV server URL (e.g. https://cal.example.com)", existing.CalDAVServer)
+		} else {
+			s, err = p.Line("CalDAV server URL (e.g. https://cal.example.com): ")
+		}
+		if err != nil {
+			return "", err
+		}
+		if verr := ValidateServerURL(s); verr != nil {
+			lastErr = verr
+			if _, werr := fmt.Fprintf(p.out, "  Invalid URL: %v. Try again.\n", verr); werr != nil {
+				return "", werr
+			}
+			continue
+		}
+		return s, nil
+	}
+	if lastErr == nil {
+		lastErr = errors.New("invalid url")
+	}
+	return "", fmt.Errorf("wizard: invalid CalDAV server URL after %d attempts: %w", maxURLValidationAttempts, lastErr)
+}
+
+// promptUsername asks for the CalDAV username, seeded with
+// existing.CalDAVUsername when non-empty.
+func promptUsername(p *Prompter, existing *Config) (string, error) {
+	if existing != nil && existing.CalDAVUsername != "" {
+		return p.LineDefault("CalDAV username", existing.CalDAVUsername)
+	}
+	return p.Line("CalDAV username: ")
+}
+
+// pickCalDAVCalendar connects to the server, lists calendars, and asks
+// the user to pick one. The previously-configured calendar URL (if it
+// still appears in the list) becomes the default.
+func pickCalDAVCalendar(p *Prompter, existing *Config, dial CalDAVDialer, serverURL, username, password string) (CalendarInfo, error) {
+	var zero CalendarInfo
+
+	if _, err := fmt.Fprintln(p.out); err != nil {
+		return zero, err
+	}
+	if _, err := fmt.Fprintln(p.out, "Connecting to CalDAV server and listing calendars..."); err != nil {
+		return zero, err
+	}
+
+	cals, err := dial.ListCalendars(context.Background(), serverURL, username, password)
+	if err != nil {
+		return zero, fmt.Errorf("wizard: list CalDAV calendars: %w", err)
+	}
+	if len(cals) == 0 {
+		return zero, errors.New("wizard: no calendars found on the CalDAV server; create a target calendar first")
+	}
+
+	defIdx := -1
+	if existing != nil && existing.CalDAVCalendarURL != "" {
+		for i, c := range cals {
+			if c.URL == existing.CalDAVCalendarURL {
+				defIdx = i
+				break
+			}
+		}
+	}
+
+	return pickWithDefault(p, "Which CalDAV calendar should work events be copied into?", cals, func(c CalendarInfo) string {
+		return fmt.Sprintf("%s  (%s)", c.Name, c.URL)
+	}, defIdx)
+}
+
+// existingDaysBack returns existing.DaysBack when set to a positive
+// value, otherwise the wizard default.
+func existingDaysBack(existing *Config) int {
+	if existing != nil && existing.DaysBack > 0 {
+		return existing.DaysBack
+	}
+	return defaultDaysBack
+}
+
+// existingDaysForward returns existing.DaysForward when set to a
+// positive value, otherwise the wizard default.
+func existingDaysForward(existing *Config) int {
+	if existing != nil && existing.DaysForward > 0 {
+		return existing.DaysForward
+	}
+	return defaultDaysForward
+}
+
+// pickWithDefault is like Pick but allows a default option. When defIdx
+// is >= 0 and < len(options), the user may press Enter to accept it; the
+// chosen entry is also marked with an asterisk in the printed list.
+func pickWithDefault[T any](p *Prompter, prompt string, options []T, labelFn func(T) string, defIdx int) (T, error) {
+	var zero T
+	if len(options) == 0 {
+		return zero, errors.New("pickWithDefault: no options provided")
+	}
+
+	if _, err := fmt.Fprintln(p.out); err != nil {
+		return zero, err
+	}
+	if _, err := fmt.Fprintln(p.out, prompt); err != nil {
+		return zero, err
+	}
+	for i, opt := range options {
+		marker := " "
+		if i == defIdx {
+			marker = "*"
+		}
+		if _, err := fmt.Fprintf(p.out, " %s %d) %s\n", marker, i+1, labelFn(opt)); err != nil {
+			return zero, err
+		}
+	}
+
+	var promptText string
+	if defIdx >= 0 && defIdx < len(options) {
+		promptText = fmt.Sprintf("Enter number [default %d]: ", defIdx+1)
+	} else {
+		promptText = "Enter number: "
+	}
+
+	const maxAttempts = 3
+	for attempt := 0; attempt < maxAttempts; attempt++ {
+		s, err := p.Line(promptText)
+		if err != nil {
+			return zero, err
+		}
+		if s == "" && defIdx >= 0 && defIdx < len(options) {
+			return options[defIdx], nil
+		}
+		if n, err := strconv.Atoi(s); err == nil && n >= 1 && n <= len(options) {
+			return options[n-1], nil
+		}
+		if _, werr := fmt.Fprintf(p.out, "  Please enter a number between 1 and %d.\n", len(options)); werr != nil {
+			return zero, werr
+		}
+	}
+	return zero, fmt.Errorf("no valid selection after %d attempts", maxAttempts)
+}
+
+// printBanner writes a small framed title to p.out so the user can tell
+// they entered the setup wizard rather than a normal sync run.
+func printBanner(p *Prompter, title string) {
+	fmt.Fprintln(p.out)
+	fmt.Fprintln(p.out, "╔══════════════════════════════════════════╗")
+	fmt.Fprintf(p.out, "║  %-38s  ║\n", title)
+	fmt.Fprintln(p.out, "╚══════════════════════════════════════════╝")
+}
+
+// printSummary echoes the chosen settings (sans password) so the user can
+// verify the wizard captured what they intended.
+func printSummary(p *Prompter, cfg *Config) {
+	fmt.Fprintln(p.out)
+	fmt.Fprintln(p.out, "Setup summary:")
+	fmt.Fprintf(p.out, "  Work calendar:    %s (%s)\n", cfg.WorkCalendarName, cfg.WorkCalendarID)
+	fmt.Fprintf(p.out, "  CalDAV server:    %s\n", cfg.CalDAVServer)
+	fmt.Fprintf(p.out, "  CalDAV username:  %s\n", cfg.CalDAVUsername)
+	fmt.Fprintf(p.out, "  Target calendar:  %s\n", cfg.CalDAVCalendarURL)
+	fmt.Fprintf(p.out, "  Sync window:      %d days back, %d days forward\n", cfg.DaysBack, cfg.DaysForward)
+}
diff --git a/internal/sync/wizard_test.go b/internal/sync/wizard_test.go
new file mode 100644
index 0000000..c9d9d26
--- /dev/null
+++ b/internal/sync/wizard_test.go
@@ -0,0 +1,369 @@
+//go:build darwin
+
+package sync
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/djdead/work-cal-sync/pkg/eventkit"
+)
+
+// fakeEventKit returns a fixed list of Exchange/O365 calendars so the
+// wizard tests don't need access to Calendar.app.
+type fakeEventKit struct {
+	cals []eventkit.Calendar
+	err  error
+}
+
+func (f *fakeEventKit) ListExchangeCalendars() ([]eventkit.Calendar, error) {
+	return f.cals, f.err
+}
+
+// fakeDialer returns a fixed list of CalDAV calendars and records the
+// credentials it was called with so tests can assert the wizard passed
+// the right values.
+type fakeDialer struct {
+	cals []CalendarInfo
+	err  error
+
+	gotURL  string
+	gotUser string
+	gotPass string
+}
+
+func (f *fakeDialer) ListCalendars(_ context.Context, serverURL, username, password string) ([]CalendarInfo, error) {
+	f.gotURL = serverURL
+	f.gotUser = username
+	f.gotPass = password
+	return f.cals, f.err
+}
+
+// twoExchangeCalendars and twoCalDAVCalendars are the canned fixtures
+// used across the wizard tests. Two entries each is enough to exercise
+// "pick by number" and "default by match" behavior without overcomplicating
+// the input scripts.
+func twoExchangeCalendars() []eventkit.Calendar {
+	return []eventkit.Calendar{
+		{Identifier: "ek-id-1", Title: "Work", SourceTitle: "user@corp.example"},
+		{Identifier: "ek-id-2", Title: "Personal", SourceTitle: "user@corp.example"},
+	}
+}
+
+func twoCalDAVCalendars() []CalendarInfo {
+	return []CalendarInfo{
+		{Name: "Work Mirror", URL: "https://cal.example.com/calendars/user/work/"},
+		{Name: "Other", URL: "https://cal.example.com/calendars/user/other/"},
+	}
+}
+
+// scriptedPrompter wires NewPrompter with canned input/output and a
+// password reader that returns a fixed string. It centralizes test
+// plumbing so each scenario only has to describe its actual input.
+func scriptedPrompter(input, password string) (*Prompter, *bytes.Buffer) {
+	out := &bytes.Buffer{}
+	p := NewPrompter(strings.NewReader(input), out)
+	p.WithPasswordReader(func(string) (string, error) { return password, nil })
+	return p, out
+}
+
+func TestRunSetup_FirstRun(t *testing.T) {
+	// Input script (one line per prompt the wizard issues):
+	//   1                        – pick Exchange calendar 1
+	//   https://cal.example.com  – CalDAV server URL
+	//   alice                    – CalDAV username
+	//   1                        – pick CalDAV calendar 1
+	//   <enter>                  – accept default daysBack
+	//   <enter>                  – accept default daysForward
+	input := strings.Join([]string{
+		"1",
+		"https://cal.example.com",
+		"alice",
+		"1",
+		"",
+		"",
+	}, "\n") + "\n"
+
+	p, out := scriptedPrompter(input, "s3cret")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	cfg, pw, err := RunSetup(p, nil, ek, dial)
+	if err != nil {
+		t.Fatalf("RunSetup() error: %v", err)
+	}
+	if cfg == nil {
+		t.Fatal("RunSetup() returned nil config")
+	}
+
+	want := Config{
+		WorkCalendarID:    "ek-id-1",
+		WorkCalendarName:  "Work",
+		CalDAVServer:      "https://cal.example.com",
+		CalDAVUsername:    "alice",
+		CalDAVCalendarURL: "https://cal.example.com/calendars/user/work/",
+		DaysBack:          defaultDaysBack,
+		DaysForward:       defaultDaysForward,
+	}
+	if *cfg != want {
+		t.Errorf("RunSetup() cfg = %+v, want %+v", *cfg, want)
+	}
+	if pw != "s3cret" {
+		t.Errorf("RunSetup() password = %q, want %q", pw, "s3cret")
+	}
+
+	// The dialer should have received the URL/username/password the
+	// user typed.
+	if dial.gotURL != "https://cal.example.com" || dial.gotUser != "alice" || dial.gotPass != "s3cret" {
+		t.Errorf("dialer credentials = (%q, %q, %q), want (https://cal.example.com, alice, s3cret)",
+			dial.gotURL, dial.gotUser, dial.gotPass)
+	}
+
+	if !strings.Contains(out.String(), "first-run setup") {
+		t.Errorf("expected first-run banner, got %q", out.String())
+	}
+}
+
+func TestRunSetup_ReusesExistingValues(t *testing.T) {
+	existing := &Config{
+		WorkCalendarID:    "ek-id-2",
+		WorkCalendarName:  "Personal",
+		CalDAVServer:      "https://old.example.com",
+		CalDAVUsername:    "olduser",
+		CalDAVCalendarURL: "https://cal.example.com/calendars/user/other/",
+		DaysBack:          14,
+		DaysForward:       30,
+	}
+
+	// Press Enter at every prompt to keep the existing values. There are
+	// six interactive prompts: Exchange pick, server URL, username,
+	// CalDAV pick, daysBack, daysForward.
+	input := strings.Repeat("\n", 6)
+
+	p, out := scriptedPrompter(input, "newpass")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	cfg, pw, err := RunSetup(p, existing, ek, dial)
+	if err != nil {
+		t.Fatalf("RunSetup() error: %v", err)
+	}
+
+	want := Config{
+		WorkCalendarID:    "ek-id-2",
+		WorkCalendarName:  "Personal",
+		CalDAVServer:      "https://old.example.com",
+		CalDAVUsername:    "olduser",
+		CalDAVCalendarURL: "https://cal.example.com/calendars/user/other/",
+		DaysBack:          14,
+		DaysForward:       30,
+	}
+	if *cfg != want {
+		t.Errorf("RunSetup() cfg = %+v, want %+v", *cfg, want)
+	}
+	if pw != "newpass" {
+		t.Errorf("RunSetup() password = %q, want %q", pw, "newpass")
+	}
+
+	written := out.String()
+	// The re-config banner should appear, not the first-run one.
+	if !strings.Contains(written, "re-configuration") {
+		t.Errorf("expected re-configuration banner, got:\n%s", written)
+	}
+	if strings.Contains(written, "first-run setup") {
+		t.Errorf("did not expect first-run banner in re-config flow:\n%s", written)
+	}
+	// Existing values must surface in the prompt output so the user can
+	// see what hitting Enter will keep.
+	for _, want := range []string{
+		"https://old.example.com", // server URL default
+		"olduser",                 // username default
+		"[default 14]",            // daysBack default
+		"[default 30]",            // daysForward default
+	} {
+		if !strings.Contains(written, want) {
+			t.Errorf("expected prompt output to contain %q, got:\n%s", want, written)
+		}
+	}
+}
+
+func TestRunSetup_ReusesExistingValues_DaysBackZeroFallsBackToWizardDefault(t *testing.T) {
+	// An existing config with DaysBack/Forward == 0 (e.g. a partially-
+	// migrated config) should fall back to the wizard's built-in
+	// defaults rather than offering 0 as the default.
+	existing := &Config{
+		WorkCalendarID:    "ek-id-1",
+		CalDAVServer:      "https://old.example.com",
+		CalDAVUsername:    "olduser",
+		CalDAVCalendarURL: "https://cal.example.com/calendars/user/work/",
+	}
+	input := strings.Repeat("\n", 6)
+
+	p, out := scriptedPrompter(input, "x")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	cfg, _, err := RunSetup(p, existing, ek, dial)
+	if err != nil {
+		t.Fatalf("RunSetup() error: %v", err)
+	}
+	if cfg.DaysBack != defaultDaysBack || cfg.DaysForward != defaultDaysForward {
+		t.Errorf("days = (%d, %d), want (%d, %d)", cfg.DaysBack, cfg.DaysForward, defaultDaysBack, defaultDaysForward)
+	}
+	if !strings.Contains(out.String(), "[default 7]") || !strings.Contains(out.String(), "[default 90]") {
+		t.Errorf("expected wizard defaults in prompt output, got:\n%s", out.String())
+	}
+}
+
+func TestRunSetup_ServerURLValidationRetries(t *testing.T) {
+	// First URL fails ValidateServerURL (plain http on a non-loopback
+	// host); the wizard should reprompt and accept the second.
+	input := strings.Join([]string{
+		"1",                       // exchange pick
+		"http://nope.example.com", // bad URL
+		"https://cal.example.com", // valid URL
+		"alice",                   // username
+		"1",                       // caldav pick
+		"",                        // daysBack default
+		"",                        // daysForward default
+	}, "\n") + "\n"
+
+	p, out := scriptedPrompter(input, "s3cret")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	cfg, _, err := RunSetup(p, nil, ek, dial)
+	if err != nil {
+		t.Fatalf("RunSetup() error: %v", err)
+	}
+	if cfg.CalDAVServer != "https://cal.example.com" {
+		t.Errorf("CalDAVServer = %q, want https://cal.example.com", cfg.CalDAVServer)
+	}
+	if !strings.Contains(out.String(), "Invalid URL") {
+		t.Errorf("expected validation retry message, got:\n%s", out.String())
+	}
+}
+
+func TestRunSetup_ServerURLValidationGivesUpAfterMaxAttempts(t *testing.T) {
+	// Three bad URLs in a row should cause the wizard to surface an
+	// error rather than keep re-prompting forever.
+	input := strings.Join([]string{
+		"1",                  // exchange pick
+		"not a url",          // bad
+		"http://example.com", // bad (non-loopback http)
+		"ftp://example.com",  // bad (unsupported scheme)
+	}, "\n") + "\n"
+
+	p, _ := scriptedPrompter(input, "s3cret")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	if _, _, err := RunSetup(p, nil, ek, dial); err == nil {
+		t.Fatal("RunSetup() expected error after 3 bad URLs, got nil")
+	}
+}
+
+func TestRunSetup_ErrorsWhenNoExchangeCalendars(t *testing.T) {
+	p, _ := scriptedPrompter("\n", "x")
+	ek := &fakeEventKit{cals: nil}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	_, _, err := RunSetup(p, nil, ek, dial)
+	if err == nil {
+		t.Fatal("RunSetup() expected error when no Exchange calendars, got nil")
+	}
+	if !strings.Contains(err.Error(), "Exchange") {
+		t.Errorf("expected Exchange-calendar error, got %v", err)
+	}
+}
+
+func TestRunSetup_ErrorsWhenEventKitFails(t *testing.T) {
+	p, _ := scriptedPrompter("\n", "x")
+	ek := &fakeEventKit{err: errors.New("permission denied")}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+
+	_, _, err := RunSetup(p, nil, ek, dial)
+	if err == nil {
+		t.Fatal("RunSetup() expected error when ListExchangeCalendars fails, got nil")
+	}
+}
+
+func TestRunSetup_ErrorsWhenDialerFails(t *testing.T) {
+	input := strings.Join([]string{
+		"1",
+		"https://cal.example.com",
+		"alice",
+	}, "\n") + "\n"
+
+	p, _ := scriptedPrompter(input, "s3cret")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{err: errors.New("auth failed")}
+
+	_, _, err := RunSetup(p, nil, ek, dial)
+	if err == nil {
+		t.Fatal("RunSetup() expected error when ListCalendars fails, got nil")
+	}
+}
+
+func TestCompleteSetup_PersistsConfigAndPassword(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	// Same script as TestRunSetup_FirstRun: pick first calendar, supply
+	// URL/username, pick first CalDAV calendar, accept default sync
+	// window.
+	input := strings.Join([]string{
+		"1",
+		"https://cal.example.com",
+		"alice",
+		"1",
+		"",
+		"",
+	}, "\n") + "\n"
+
+	p, out := scriptedPrompter(input, "s3cret")
+	ek := &fakeEventKit{cals: twoExchangeCalendars()}
+	dial := &fakeDialer{cals: twoCalDAVCalendars()}
+	ks := newFakeKeyringStore()
+
+	cfg, err := CompleteSetup(p, nil, ek, dial, ks)
+	if err != nil {
+		t.Fatalf("CompleteSetup() error: %v", err)
+	}
+	if cfg == nil {
+		t.Fatal("CompleteSetup() returned nil config")
+	}
+
+	// Saved config should round-trip through Load() and equal what
+	// CompleteSetup returned.
+	loaded, err := Load()
+	if err != nil {
+		t.Fatalf("Load() error: %v", err)
+	}
+	if loaded == nil {
+		t.Fatal("Load() returned nil after CompleteSetup")
+	}
+	if *loaded != *cfg {
+		t.Errorf("loaded config differs from returned:\n loaded = %+v\nreturned = %+v", *loaded, *cfg)
+	}
+
+	// Keyring should have the username → password mapping.
+	got, err := ks.Get(cfg.CalDAVUsername)
+	if err != nil {
+		t.Fatalf("ks.Get(%q) error: %v", cfg.CalDAVUsername, err)
+	}
+	if got != "s3cret" {
+		t.Errorf("ks.Get(%q) = %q, want %q", cfg.CalDAVUsername, got, "s3cret")
+	}
+
+	// Confirmation lines should be printed to the prompter's output.
+	written := out.String()
+	if !strings.Contains(written, "✓ Config saved to") {
+		t.Errorf("expected config-saved confirmation, got:\n%s", written)
+	}
+	if !strings.Contains(written, "✓ Password saved to macOS Keychain") {
+		t.Errorf("expected keychain confirmation, got:\n%s", written)
+	}
+}
diff --git a/pkg/eventkit/Info.plist b/pkg/eventkit/Info.plist
new file mode 100644
index 0000000..67b987d
--- /dev/null
+++ b/pkg/eventkit/Info.plist
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleIdentifier</key>
+    <string>tel.dead.work-cal-sync</string>
+    <key>CFBundleName</key>
+    <string>work-cal-sync</string>
+    <key>CFBundleDisplayName</key>
+    <string>work-cal-sync</string>
+    <key>CFBundleVersion</key>
+    <string>0.1.0</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.1.0</string>
+    <key>CFBundleExecutable</key>
+    <string>work-cal-sync</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleSignature</key>
+    <string>????</string>
+    <key>NSHumanReadableCopyright</key>
+    <string>work-cal-sync</string>
+    <key>NSCalendarsFullAccessUsageDescription</key>
+    <string>work-cal-sync reads events from your work Exchange/O365 calendar so it can mirror them to your CalDAV server.</string>
+    <key>NSCalendarsUsageDescription</key>
+    <string>work-cal-sync reads events from your work Exchange/O365 calendar so it can mirror them to your CalDAV server.</string>
+</dict>
+</plist>
diff --git a/pkg/eventkit/doc.go b/pkg/eventkit/doc.go
new file mode 100644
index 0000000..0fc8440
--- /dev/null
+++ b/pkg/eventkit/doc.go
@@ -0,0 +1,7 @@
+//go:build darwin
+
+// Package eventkit provides a cgo bridge to the macOS EventKit framework
+// for reading calendars and events from Calendar.app.
+//
+// This package is macOS-only.
+package eventkit
diff --git a/pkg/eventkit/eventkit.go b/pkg/eventkit/eventkit.go
new file mode 100644
index 0000000..284eacb
--- /dev/null
+++ b/pkg/eventkit/eventkit.go
@@ -0,0 +1,259 @@
+//go:build darwin
+
+package eventkit
+
+/*
+#cgo CFLAGS: -fobjc-arc -x objective-c
+#cgo LDFLAGS: -framework EventKit -framework Foundation -Wl,-sectcreate,__TEXT,__info_plist,${SRCDIR}/Info.plist
+
+#include <stdlib.h>
+#include "eventkit.h"
+*/
+import "C"
+
+import (
+	"context"
+	"errors"
+	"time"
+	"unsafe"
+)
+
+// EKAuthorizationStatus values returned by AuthorizationStatus.
+//
+// These mirror the EKAuthorizationStatus enum from EventKit. Codify them
+// here so callers don't sprinkle magic numbers when checking the result
+// or when producing user-facing error messages.
+//
+// Note: the legacy EKAuthorizationStatusAuthorized (pre-macOS 14) and the
+// modern EKAuthorizationStatusFullAccess (macOS 14+) share the same raw
+// value of 3, so a single StatusFullAccess constant covers both.
+const (
+	StatusNotDetermined = 0
+	StatusRestricted    = 1
+	StatusDenied        = 2
+	StatusFullAccess    = 3
+	StatusWriteOnly     = 4
+)
+
+// ErrAccessTimeout is returned by RequestAccess when the system authorization
+// prompt does not produce a decision within the caller-supplied timeout. It is
+// distinct from a plain user denial, which returns (false, nil).
+var ErrAccessTimeout = errors.New("eventkit: timed out waiting for EventKit access decision")
+
+// Calendar describes an EventKit calendar surfaced through the bridge.
+// Only fields the rest of the app needs are exposed.
+type Calendar struct {
+	Identifier  string
+	Title       string
+	SourceTitle string
+}
+
+// Event describes a single EventKit event. Times are in the system local
+// time zone (NSDate is wall-clock here because EventKit returns absolute
+// instants and we just unwrap them via Unix seconds). Missing/nil dates
+// from EventKit are represented as the zero time.Time.
+type Event struct {
+	ExternalID   string
+	Title        string
+	Notes        string
+	Location     string
+	Start        time.Time
+	End          time.Time
+	LastModified time.Time
+	AllDay       bool
+}
+
+// AuthorizationStatus returns the raw EKAuthorizationStatus value. Compare
+// against the Status* constants in this package rather than literal ints.
+//
+// Typical use: surface a "Calendar access denied. Go to System Settings >
+// Privacy & Security > Calendars" message when the result is StatusRestricted
+// or StatusDenied, since RequestAccess cannot recover from those without
+// the user changing the setting manually.
+func AuthorizationStatus() int {
+	return int(C.wcs_authorization_status())
+}
+
+// RequestAccess prompts the user for EventKit access, blocking up to timeout.
+//
+// Return values:
+//   - (true,  nil)               full access granted
+//   - (false, nil)               user denied or access otherwise unavailable
+//   - (false, ErrAccessTimeout)  the timeout elapsed before any decision
+//
+// Callers that just want a granted/not-granted boolean can ignore the error
+// for non-timeout cases; the error exists so a stuck prompt is distinguishable
+// from a real denial.
+func RequestAccess(timeout time.Duration) (bool, error) {
+	granted := C.wcs_request_access(C.double(timeout.Seconds()))
+	if granted != 0 {
+		return true, nil
+	}
+	// The C bridge collapses "denied" and "timeout" into a 0 return value.
+	// Disambiguate by checking the post-call status: a real prompt response
+	// (allow/deny) moves the status off NotDetermined; a timeout leaves it
+	// at StatusNotDetermined.
+	if AuthorizationStatus() == StatusNotDetermined {
+		return false, ErrAccessTimeout
+	}
+	return false, nil
+}
+
+// NSDate ↔ time.Time convention: the bridge marshals NSDate as a C double
+// holding seconds since the unix epoch (NSDate's timeIntervalSince1970),
+// preserving fractional seconds. A bridge value of exactly 0 means "no
+// date" and maps to time.Time{} (and vice versa).
+
+// unixToTime converts a unix-seconds double from the bridge to a time.Time,
+// preserving sub-second precision down to nanoseconds.
+func unixToTime(t C.double) time.Time {
+	if t == 0 {
+		return time.Time{}
+	}
+	f := float64(t)
+	sec := int64(f)
+	nsec := int64((f - float64(sec)) * 1e9)
+	return time.Unix(sec, nsec)
+}
+
+// timeToUnixDouble converts a time.Time to a unix-seconds C.double for the
+// bridge, preserving sub-second precision.
+func timeToUnixDouble(t time.Time) C.double {
+	return C.double(float64(t.Unix()) + float64(t.Nanosecond())/1e9)
+}
+
+// ListExchangeCalendars returns the Exchange/O365 calendars EventKit knows
+// about, with the bridge's birthdays/holidays exclusion already applied.
+// Returns a nil slice (and nil error) when no calendars match.
+func ListExchangeCalendars() ([]Calendar, error) {
+	var n C.int
+	cArr := C.wcs_list_exchange_calendars(&n)
+	if cArr == nil {
+		return nil, nil
+	}
+	defer C.wcs_free_calendars(cArr, n)
+
+	count := int(n)
+	if count == 0 {
+		return nil, nil
+	}
+
+	cs := unsafe.Slice(cArr, count)
+	out := make([]Calendar, count)
+	for i := 0; i < count; i++ {
+		out[i] = Calendar{
+			Identifier:  C.GoString(cs[i].identifier),
+			Title:       C.GoString(cs[i].title),
+			SourceTitle: C.GoString(cs[i].sourceTitle),
+		}
+	}
+	return out, nil
+}
+
+// FetchEvents returns events in the given calendar between start and end
+// (inclusive of start, exclusive of end as far as EventKit's predicate is
+// concerned). Returns a nil slice when the calendar is unknown or empty.
+func FetchEvents(calendarID string, start, end time.Time) ([]Event, error) {
+	cID := C.CString(calendarID)
+	defer C.free(unsafe.Pointer(cID))
+
+	var n C.int
+	cArr := C.wcs_fetch_events(
+		cID,
+		timeToUnixDouble(start),
+		timeToUnixDouble(end),
+		&n,
+	)
+	if cArr == nil {
+		return nil, nil
+	}
+	defer C.wcs_free_events(cArr, n)
+
+	count := int(n)
+	if count == 0 {
+		return nil, nil
+	}
+
+	es := unsafe.Slice(cArr, count)
+	out := make([]Event, count)
+	for i := 0; i < count; i++ {
+		out[i] = Event{
+			ExternalID:   C.GoString(es[i].externalIdentifier),
+			Title:        C.GoString(es[i].title),
+			Notes:        C.GoString(es[i].notes),
+			Location:     C.GoString(es[i].location),
+			Start:        unixToTime(es[i].startUnix),
+			End:          unixToTime(es[i].endUnix),
+			LastModified: unixToTime(es[i].lastModifiedUnix),
+			AllDay:       es[i].isAllDay != 0,
+		}
+	}
+	return out, nil
+}
+
+// ── Change notifications ──────────────────────────────────────────────
+
+// ChangeCount returns the number of EKEventStoreChangedNotification
+// events seen since this process started. The counter starts at zero
+// and only ever increases. Callers can use the value as a snapshot to
+// pass to WaitForChange or to detect changes via simple polling.
+//
+// Idempotent: calling this for the first time also installs the
+// underlying notification observer.
+func ChangeCount() uint64 {
+	return uint64(C.wcs_change_count())
+}
+
+// WaitForChange blocks until the change counter advances past
+// lastSeen, or until timeout elapses. Returns the new counter value
+// when notified, or the unchanged counter value on timeout.
+//
+// Pass timeout <= 0 to wait forever.
+//
+// Typical usage:
+//
+//	last := eventkit.ChangeCount()
+//	for {
+//	    last = eventkit.WaitForChange(last, 0)
+//	    // re-fetch and react to the change
+//	}
+//
+// WaitForChange is safe to call from any goroutine. Multiple
+// concurrent waiters are supported; each will be woken on the next
+// change.
+func WaitForChange(lastSeen uint64, timeout time.Duration) uint64 {
+	secs := timeout.Seconds()
+	if timeout <= 0 {
+		secs = 0
+	}
+	return uint64(C.wcs_wait_for_change(C.ulonglong(lastSeen), C.double(secs)))
+}
+
+// ObserveChanges starts a goroutine that calls fn whenever EventKit
+// posts a store-changed notification. The goroutine exits when ctx is
+// cancelled. fn is invoked synchronously on the goroutine, so a
+// long-running fn will delay the next dispatch — wrap your work in a
+// goroutine of its own if it might be slow.
+//
+// Use this when you want push-style updates and don't need to manage
+// the polling loop yourself.
+func ObserveChanges(ctx context.Context, fn func()) {
+	if fn == nil {
+		return
+	}
+	go func() {
+		last := ChangeCount()
+		for {
+			// Use a moderate timeout so cancellation is responsive even
+			// if no changes ever arrive.
+			next := WaitForChange(last, 5*time.Second)
+			if ctx.Err() != nil {
+				return
+			}
+			if next > last {
+				last = next
+				fn()
+			}
+		}
+	}()
+}
diff --git a/pkg/eventkit/eventkit.h b/pkg/eventkit/eventkit.h
new file mode 100644
index 0000000..83b6e3e
--- /dev/null
+++ b/pkg/eventkit/eventkit.h
@@ -0,0 +1,125 @@
+/*
+ * eventkit.h — C interface for the macOS EventKit bridge used by Go (cgo).
+ *
+ * Both `eventkit.m` (the Objective-C implementation) and `eventkit.go`
+ * (the Go cgo wrapper) include this header so that struct layouts and
+ * function signatures stay in sync.
+ *
+ * All returned strings are heap-allocated via strdup() and all returned
+ * arrays are heap-allocated via calloc(). Callers MUST release them via
+ * the matching wcs_free_* functions; do not call free() directly.
+ */
+
+#ifndef WCS_EVENTKIT_H
+#define WCS_EVENTKIT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct {
+    char* identifier;   /* EKCalendar.calendarIdentifier */
+    char* title;        /* EKCalendar.title */
+    char* sourceTitle;  /* EKCalendar.source.title */
+} WCSCalendar;
+
+typedef struct {
+    char*  externalIdentifier; /* EKEvent.calendarItemExternalIdentifier */
+    char*  title;              /* EKEvent.title       — empty string if nil */
+    char*  notes;              /* EKEvent.notes       — empty string if nil */
+    char*  location;           /* EKEvent.location    — empty string if nil */
+    double startUnix;          /* EKEvent.startDate.timeIntervalSince1970 */
+    double endUnix;            /* EKEvent.endDate.timeIntervalSince1970 */
+    double lastModifiedUnix;   /* EKEvent.lastModifiedDate.timeIntervalSince1970 */
+    int    isAllDay;           /* 0 or 1 */
+} WCSEvent;
+
+/*
+ * Request EventKit access. Blocks until the system grants/denies access or
+ * the timeout (seconds) elapses. Returns 1 on full-access granted, 0 on
+ * denial or timeout. Uses requestFullAccessToEventsWithCompletion: on
+ * macOS 14+; falls back to requestAccessToEntityType:completion: on
+ * earlier systems.
+ */
+int wcs_request_access(double timeoutSeconds);
+
+/*
+ * Returns the raw EKAuthorizationStatus int:
+ *   0 = NotDetermined
+ *   1 = Restricted
+ *   2 = Denied
+ *   3 = FullAccess (formerly Authorized)
+ *   4 = WriteOnly  (macOS 14+ only)
+ */
+int wcs_authorization_status(void);
+
+/*
+ * Returns a heap-allocated array of WCSCalendar entries for Exchange/O365
+ * calendars (source.sourceType == EKSourceTypeExchange == 1). Calendars
+ * named "birthdays", "holidays", or "united states holidays" (case-insensitive)
+ * are excluded. Sets *outCount to the number of entries (0 on empty/error).
+ * Returns NULL when no calendars match. Caller must free with
+ * wcs_free_calendars.
+ */
+WCSCalendar* wcs_list_exchange_calendars(int* outCount);
+
+/* Releases the array and all strdup'd strings inside each entry. */
+void wcs_free_calendars(WCSCalendar* arr, int count);
+
+/*
+ * Returns a heap-allocated array of WCSEvent entries for events in the
+ * calendar with the given identifier between startUnix and endUnix.
+ * Events without a calendarItemExternalIdentifier are skipped (matching
+ * the Python implementation). Sets *outCount; returns NULL on no matches
+ * or unknown calendar identifier. Caller must free with wcs_free_events.
+ */
+WCSEvent* wcs_fetch_events(const char* calendarIdentifier,
+                           double startUnix,
+                           double endUnix,
+                           int* outCount);
+
+/* Releases the array and all strdup'd strings inside each entry. */
+void wcs_free_events(WCSEvent* arr, int count);
+
+/*
+ * Change-notification helpers for EKEventStoreChangedNotification.
+ *
+ * Threading model: a small Objective-C observer registered against the
+ * shared EKEventStore increments a counter every time EventKit posts the
+ * "store changed" notification. wcs_change_count() returns the current
+ * counter value. wcs_wait_for_change() blocks until the counter exceeds
+ * the value the caller saw last (or until timeoutSeconds elapses), then
+ * returns the new value.
+ *
+ * This polling/waiting model — rather than a callback function pointer
+ * back into Go — avoids the Go-routine-from-arbitrary-thread issues that
+ * cgo callbacks introduce. Callers can either poll wcs_change_count()
+ * from a ticker or block in wcs_wait_for_change() from a worker
+ * goroutine.
+ */
+
+/*
+ * Idempotent. Registers the observer the first time it is called; safe
+ * to call repeatedly. Returns the current change count, which begins at
+ * zero before any change has been observed.
+ */
+unsigned long long wcs_change_count(void);
+
+/*
+ * Block until the change counter has incremented past `lastSeen`, or
+ * until `timeoutSeconds` have elapsed. Returns the current counter
+ * value. If the counter has already moved past `lastSeen` when the
+ * function is called, it returns immediately.
+ *
+ * Setting timeoutSeconds <= 0 disables the timeout (waits forever).
+ *
+ * The observer is registered on first call so callers do not need a
+ * separate "start observing" step.
+ */
+unsigned long long wcs_wait_for_change(unsigned long long lastSeen, double timeoutSeconds);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* WCS_EVENTKIT_H */
diff --git a/pkg/eventkit/eventkit.m b/pkg/eventkit/eventkit.m
new file mode 100644
index 0000000..047768b
--- /dev/null
+++ b/pkg/eventkit/eventkit.m
@@ -0,0 +1,362 @@
+/*
+ * eventkit.m — Objective-C bridge to the macOS EventKit framework.
+ *
+ * This file is compiled by cgo on darwin only; the Go side adds the
+ * required `#cgo` directives. The implementation mirrors the behaviour of
+ * the Python script's request_eventkit_access, get_exchange_calendars and
+ * fetch_work_events functions.
+ *
+ * Compiled with -fobjc-arc by cgo's default flags on darwin.
+ */
+
+#import <EventKit/EventKit.h>
+#import <Foundation/Foundation.h>
+
+#include <stdlib.h>
+#include <string.h>
+#include <errno.h>
+#include <sys/time.h>
+
+#include "eventkit.h"
+
+/* ── Helpers ──────────────────────────────────────────────────────────── */
+
+/*
+ * A single EKEventStore is shared across all calls. The store is
+ * thread-safe enough for our usage (single-threaded calls from Go) and
+ * keeping it alive avoids re-prompting for permissions and avoids
+ * re-establishing internal state on every call.
+ */
+static EKEventStore* WCSSharedStore(void) {
+    static EKEventStore* sharedStore = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        sharedStore = [[EKEventStore alloc] init];
+    });
+    return sharedStore;
+}
+
+/*
+ * Returns a heap copy (strdup) of the UTF-8 encoding of `s`, or strdup("")
+ * when `s` is nil. Never returns NULL — the Go side can rely on every
+ * pointer being a valid C string that needs to be free()'d.
+ */
+static char* WCSDupString(NSString* s) {
+    const char* utf8 = (s != nil) ? [s UTF8String] : "";
+    if (utf8 == NULL) {
+        utf8 = "";
+    }
+    return strdup(utf8);
+}
+
+/* ── Authorization ────────────────────────────────────────────────────── */
+
+int wcs_authorization_status(void) {
+    return (int)[EKEventStore authorizationStatusForEntityType:EKEntityTypeEvent];
+}
+
+int wcs_request_access(double timeoutSeconds) {
+    EKEventStore* store = WCSSharedStore();
+
+    /*
+     * Short-circuit on already-decided states so we don't issue a
+     * permission request that the OS will silently swallow:
+     *
+     *   3 (FullAccess / legacy Authorized) → granted, return 1.
+     *   1 (Restricted) or 2 (Denied)       → return 0 immediately;
+     *                                        the user must change the
+     *                                        decision in System Settings.
+     *
+     * Only status 0 (NotDetermined) and 4 (WriteOnly, macOS 14+) fall
+     * through to the actual request, where the prompt may appear.
+     */
+    EKAuthorizationStatus current =
+        [EKEventStore authorizationStatusForEntityType:EKEntityTypeEvent];
+    if ((int)current == 3) {
+        return 1;
+    }
+    if ((int)current == 1 || (int)current == 2) {
+        return 0;
+    }
+
+    dispatch_semaphore_t sem = dispatch_semaphore_create(0);
+    __block BOOL granted = NO;
+
+    void (^completion)(BOOL, NSError*) = ^(BOOL g, NSError* error) {
+        (void)error;
+        granted = g;
+        dispatch_semaphore_signal(sem);
+    };
+
+    /*
+     * Prefer requestFullAccessToEventsWithCompletion: (macOS 14+).
+     * Use the runtime to look it up so this code compiles against older
+     * SDKs too — same approach the Python script uses with hasattr().
+     */
+    SEL fullAccessSel = NSSelectorFromString(@"requestFullAccessToEventsWithCompletion:");
+    if ([store respondsToSelector:fullAccessSel]) {
+        typedef void (*RequestFullAccessFn)(id, SEL, void (^)(BOOL, NSError*));
+        IMP imp = [store methodForSelector:fullAccessSel];
+        RequestFullAccessFn fn = (RequestFullAccessFn)imp;
+        fn(store, fullAccessSel, completion);
+    } else {
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+        [store requestAccessToEntityType:EKEntityTypeEvent completion:completion];
+#pragma clang diagnostic pop
+    }
+
+    dispatch_time_t deadline = dispatch_time(
+        DISPATCH_TIME_NOW,
+        (int64_t)(timeoutSeconds * (double)NSEC_PER_SEC));
+    long waitResult = dispatch_semaphore_wait(sem, deadline);
+    if (waitResult != 0) {
+        return 0; /* timeout */
+    }
+    return granted ? 1 : 0;
+}
+
+/* ── Calendars ────────────────────────────────────────────────────────── */
+
+WCSCalendar* wcs_list_exchange_calendars(int* outCount) {
+    if (outCount) {
+        *outCount = 0;
+    }
+
+    EKEventStore* store = WCSSharedStore();
+    NSArray<EKCalendar*>* allCalendars =
+        [store calendarsForEntityType:EKEntityTypeEvent];
+
+    NSSet<NSString*>* excluded = [NSSet setWithObjects:
+                                  @"birthdays",
+                                  @"holidays",
+                                  @"united states holidays",
+                                  nil];
+
+    NSMutableArray<EKCalendar*>* matching = [NSMutableArray array];
+    for (EKCalendar* cal in allCalendars) {
+        if (cal.source == nil) {
+            continue;
+        }
+        if (cal.source.sourceType != EKSourceTypeExchange) {
+            continue;
+        }
+        NSString* title = cal.title ?: @"";
+        if ([excluded containsObject:[title lowercaseString]]) {
+            continue;
+        }
+        [matching addObject:cal];
+    }
+
+    NSUInteger count = matching.count;
+    if (count == 0) {
+        return NULL;
+    }
+
+    WCSCalendar* arr = (WCSCalendar*)calloc(count, sizeof(WCSCalendar));
+    if (arr == NULL) {
+        return NULL;
+    }
+    for (NSUInteger i = 0; i < count; i++) {
+        EKCalendar* cal = matching[i];
+        arr[i].identifier  = WCSDupString(cal.calendarIdentifier);
+        arr[i].title       = WCSDupString(cal.title);
+        arr[i].sourceTitle = WCSDupString(cal.source.title);
+    }
+    if (outCount) {
+        *outCount = (int)count;
+    }
+    return arr;
+}
+
+void wcs_free_calendars(WCSCalendar* arr, int count) {
+    if (arr == NULL) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        free(arr[i].identifier);
+        free(arr[i].title);
+        free(arr[i].sourceTitle);
+    }
+    free(arr);
+}
+
+/* ── Events ───────────────────────────────────────────────────────────── */
+
+WCSEvent* wcs_fetch_events(const char* calendarIdentifier,
+                           double startUnix,
+                           double endUnix,
+                           int* outCount) {
+    if (outCount) {
+        *outCount = 0;
+    }
+    if (calendarIdentifier == NULL) {
+        return NULL;
+    }
+
+    EKEventStore* store = WCSSharedStore();
+    NSString* identStr = [NSString stringWithUTF8String:calendarIdentifier];
+    if (identStr == nil) {
+        return NULL;
+    }
+    EKCalendar* calendar = [store calendarWithIdentifier:identStr];
+    if (calendar == nil) {
+        return NULL;
+    }
+
+    NSDate* startDate = [NSDate dateWithTimeIntervalSince1970:startUnix];
+    NSDate* endDate   = [NSDate dateWithTimeIntervalSince1970:endUnix];
+    NSPredicate* predicate =
+        [store predicateForEventsWithStartDate:startDate
+                                       endDate:endDate
+                                     calendars:@[calendar]];
+    NSArray<EKEvent*>* events = [store eventsMatchingPredicate:predicate];
+    if (events == nil) {
+        return NULL;
+    }
+
+    /* Mirror Python: skip events with no externalIdentifier. */
+    NSMutableArray<EKEvent*>* kept = [NSMutableArray array];
+    for (EKEvent* ev in events) {
+        NSString* extID = ev.calendarItemExternalIdentifier;
+        if (extID != nil && extID.length > 0) {
+            [kept addObject:ev];
+        }
+    }
+
+    NSUInteger count = kept.count;
+    if (count == 0) {
+        return NULL;
+    }
+
+    WCSEvent* arr = (WCSEvent*)calloc(count, sizeof(WCSEvent));
+    if (arr == NULL) {
+        return NULL;
+    }
+    for (NSUInteger i = 0; i < count; i++) {
+        EKEvent* ev = kept[i];
+        arr[i].externalIdentifier = WCSDupString(ev.calendarItemExternalIdentifier);
+        arr[i].title              = WCSDupString(ev.title);
+        arr[i].notes              = WCSDupString(ev.notes);
+        arr[i].location           = WCSDupString(ev.location);
+        arr[i].startUnix          = (ev.startDate != nil)
+                                        ? [ev.startDate timeIntervalSince1970]
+                                        : 0.0;
+        arr[i].endUnix            = (ev.endDate != nil)
+                                        ? [ev.endDate timeIntervalSince1970]
+                                        : 0.0;
+        arr[i].lastModifiedUnix   = (ev.lastModifiedDate != nil)
+                                        ? [ev.lastModifiedDate timeIntervalSince1970]
+                                        : 0.0;
+        arr[i].isAllDay           = ev.isAllDay ? 1 : 0;
+    }
+    if (outCount) {
+        *outCount = (int)count;
+    }
+    return arr;
+}
+
+void wcs_free_events(WCSEvent* arr, int count) {
+    if (arr == NULL) {
+        return;
+    }
+    for (int i = 0; i < count; i++) {
+        free(arr[i].externalIdentifier);
+        free(arr[i].title);
+        free(arr[i].notes);
+        free(arr[i].location);
+    }
+    free(arr);
+}
+
+/* ── Change notifications ─────────────────────────────────────────────── */
+
+/*
+ * EKEventStoreChangedNotification fires from EventKit's internal queue
+ * on an arbitrary thread, but we never need to do real work in the
+ * handler — only bump a counter and wake any thread blocked in
+ * wcs_wait_for_change. A pthread mutex + condvar are the simplest
+ * primitives that give us "many waiters, one signal" with timed waits.
+ *
+ * The counter is the synchronization point: callers pass in the last
+ * value they observed and we wake them when our counter exceeds it.
+ * That makes the API safe against missed wakeups (no event lost between
+ * "I just processed change N" and "now I'm calling wait again") and
+ * supports multiple concurrent waiters trivially.
+ */
+
+#import <pthread.h>
+
+static pthread_mutex_t       gChangeMutex = PTHREAD_MUTEX_INITIALIZER;
+static pthread_cond_t        gChangeCond  = PTHREAD_COND_INITIALIZER;
+static unsigned long long    gChangeCount = 0;
+static dispatch_once_t       gObserverOnce;
+static id                    gChangeObserver = nil; /* keep a strong ref */
+
+static void WCSEnsureChangeObserver(void) {
+    dispatch_once(&gObserverOnce, ^{
+        EKEventStore* store = WCSSharedStore();
+        gChangeObserver = [[NSNotificationCenter defaultCenter]
+            addObserverForName:EKEventStoreChangedNotification
+                        object:store
+                         queue:nil
+                    usingBlock:^(NSNotification* note) {
+                        (void)note;
+                        pthread_mutex_lock(&gChangeMutex);
+                        gChangeCount++;
+                        pthread_cond_broadcast(&gChangeCond);
+                        pthread_mutex_unlock(&gChangeMutex);
+                    }];
+    });
+}
+
+unsigned long long wcs_change_count(void) {
+    WCSEnsureChangeObserver();
+    pthread_mutex_lock(&gChangeMutex);
+    unsigned long long n = gChangeCount;
+    pthread_mutex_unlock(&gChangeMutex);
+    return n;
+}
+
+unsigned long long wcs_wait_for_change(unsigned long long lastSeen,
+                                       double timeoutSeconds) {
+    WCSEnsureChangeObserver();
+
+    pthread_mutex_lock(&gChangeMutex);
+    if (gChangeCount > lastSeen) {
+        unsigned long long n = gChangeCount;
+        pthread_mutex_unlock(&gChangeMutex);
+        return n;
+    }
+
+    if (timeoutSeconds <= 0) {
+        while (gChangeCount <= lastSeen) {
+            pthread_cond_wait(&gChangeCond, &gChangeMutex);
+        }
+    } else {
+        struct timespec deadline;
+#if defined(__APPLE__)
+        struct timeval tv;
+        gettimeofday(&tv, NULL);
+        deadline.tv_sec  = tv.tv_sec;
+        deadline.tv_nsec = (long)tv.tv_usec * 1000L;
+#else
+        clock_gettime(CLOCK_REALTIME, &deadline);
+#endif
+        long whole = (long)timeoutSeconds;
+        long nano  = (long)((timeoutSeconds - (double)whole) * 1.0e9);
+        deadline.tv_sec += whole;
+        deadline.tv_nsec += nano;
+        if (deadline.tv_nsec >= 1000000000L) {
+            deadline.tv_sec  += deadline.tv_nsec / 1000000000L;
+            deadline.tv_nsec %= 1000000000L;
+        }
+        while (gChangeCount <= lastSeen) {
+            int rc = pthread_cond_timedwait(&gChangeCond, &gChangeMutex, &deadline);
+            if (rc == ETIMEDOUT) break;
+        }
+    }
+    unsigned long long n = gChangeCount;
+    pthread_mutex_unlock(&gChangeMutex);
+    return n;
+}
diff --git a/pkg/eventkit/eventkit_test.go b/pkg/eventkit/eventkit_test.go
new file mode 100644
index 0000000..0010dee
--- /dev/null
+++ b/pkg/eventkit/eventkit_test.go
@@ -0,0 +1,51 @@
+//go:build darwin
+
+package eventkit
+
+import (
+	"testing"
+	"time"
+)
+
+// TestUnixToTimeZero verifies the "no date" sentinel: a bridge double of 0
+// must round-trip to the zero time.Time, which is how the rest of the code
+// detects missing EventKit dates.
+func TestUnixToTimeZero(t *testing.T) {
+	got := unixToTime(0)
+	if !got.IsZero() {
+		t.Fatalf("unixToTime(0) = %v, want zero time", got)
+	}
+}
+
+// TestUnixDoubleRoundTrip exercises a few representative instants through
+// timeToUnixDouble → unixToTime and confirms the result is within 1µs of
+// the original. The 1µs tolerance accounts for float64 precision loss when
+// representing modern unix-second values (~1.7e9) plus a nanosecond
+// fraction.
+func TestUnixDoubleRoundTrip(t *testing.T) {
+	cases := []struct {
+		name string
+		t    time.Time
+	}{
+		{"epoch+1s", time.Unix(1, 0).UTC()},
+		{"recent whole second", time.Date(2024, 5, 15, 12, 30, 45, 0, time.UTC)},
+		{"recent with nanos", time.Date(2024, 5, 15, 12, 30, 45, 123_456_789, time.UTC)},
+		{"future", time.Date(2030, 1, 1, 0, 0, 0, 500_000_000, time.UTC)},
+	}
+	const tolerance = time.Microsecond
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			d := timeToUnixDouble(tc.t)
+			got := unixToTime(d)
+			diff := got.Sub(tc.t)
+			if diff < 0 {
+				diff = -diff
+			}
+			if diff > tolerance {
+				t.Fatalf("round-trip drift %v exceeds tolerance %v (in=%v out=%v)",
+					diff, tolerance, tc.t, got)
+			}
+		})
+	}
+}