# Nextcloud Skill

Connect to any CalDAV/CardDAV/WebDAV server (Nextcloud, Radicale, ownCloud, Synology).

## Usage

Use this skill when the user asks about their self-hosted calendar events, contacts, or cloud files on Nextcloud or another CalDAV/CardDAV/WebDAV server. This includes checking schedules, creating events, managing contacts, and browsing/reading/uploading files.

## Examples

- "What's on my Nextcloud calendar today?"
- "Am I free at 3pm on Thursday?"
- "Create a meeting for tomorrow at 10am"
- "Show files in my Documents folder"
- "Read my notes.txt from Nextcloud"
- "Upload this report to my cloud"
- "List my contacts"
- "Sync my contacts from Nextcloud"
- "Find free time on Friday"

## Important

- **Calendar**: Uses CalDAV. Events are on the self-hosted server, not Google Calendar.
- **Files**: Uses WebDAV. These are cloud files on the server, not local files on disk.
- **Contacts**: Sync is bidirectional — `sync_in` pulls from server, `sync_out` pushes to server.
- File reads are truncated at 5000 characters for large files.

## Disambiguation

- **Calendar**: `nextcloud_calendar_*` = CalDAV/self-hosted. `calendar_*` = Google Calendar. If both are configured, ask which the user means.
- **Files**: `nextcloud_files_*` = cloud/WebDAV server. `read_document`/`write_file` = local disk. "My cloud files" → Nextcloud. A local path like `/home/user/file.txt` → local tools.
- **Contacts**: `nextcloud_contacts_*` = server contacts. Local contact store is separate.
- This is **NOT** for Joplin notes — use `joplin_*` for the notes app.

## Setup

1. Generate an **app password** in Nextcloud → Settings → Security → Devices & sessions
2. Set environment variables:

```
NEXTCLOUD_URL=https://cloud.example.org
NEXTCLOUD_USER=alice
NEXTCLOUD_TOKEN=xxxx-xxxx-xxxx-xxxx
```

3. Install dependencies:
```
pip install familiar-agent[nextcloud]
```

## Calendar (CalDAV)

- `nextcloud_calendar_today` — List events for today or a date range
- `nextcloud_calendar_create` — Create a calendar event (requires confirmation)
- `nextcloud_calendar_check` — Check if a time slot is available
- `nextcloud_calendar_free` — Find free time slots on a given day
- `nextcloud_calendar_delete` — Delete a calendar event (requires confirmation)

## Contacts (CardDAV)

- `nextcloud_contacts_list` — List contacts from the server
- `nextcloud_contacts_sync_in` — Pull contacts from server into local store
- `nextcloud_contacts_sync_out` — Push local contacts to server (requires confirmation)

## Files (WebDAV)

- `nextcloud_files_list` — List files in a directory
- `nextcloud_files_search` — Search files by name
- `nextcloud_files_read` — Read a text file (truncated at 5000 chars)
- `nextcloud_files_upload` — Upload a file (requires confirmation)
- `nextcloud_files_mkdir` — Create a directory
- `nextcloud_files_delete` — Delete a file or directory (requires confirmation)

## Timezone

Uses `CALENDAR_TIMEZONE` environment variable (shared with the Google Calendar skill).
