domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/specs/plans/2026-04-07-calendar-plugin.md

@@ -0,0 +1,1526 @@
+# Calendar Plugin Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a standalone Calendar plugin with public event pages, iCal feed, RSVP registration, recurring events (materialised occurrences), three admin view modes, two plugin roles, and a `service.js` layer for Jobs integration.
+
+**Architecture:** `plugin.js` registers API routes + the `[calendar /]` shortcode at startup; `plugin.public.js` registers SSR public routes at the Fastify root; `service.js` is a plain ES module exporting CRUD helpers that Jobs imports directly. Recurrence is pre-materialised as individual `calendar-occurrences` entries (rolling 12-month window). Seeded assets (form, page, block, views) are created in the `onEnable` lifecycle and removed in `onDisable`.
+
+**Tech Stack:** Fastify 5 (ESM), Domma SPA (admin), `server/services/collections.js` (CRUD), `server/services/renderer.js` (`renderBlogPage`), `server/services/hooks.js` (`registerShortcode`).
+
+---
+
+## Critical CMS conventions - read before implementing any task
+
+- **HTTP in admin views**: Always use `H.get/post/put/delete` - never `fetch()`.
+- **DOM selection**: `$container.find('#id')` - never `document.querySelector()`.
+- **Native DOM element**: `$container.find('#id').get(0)` - never `$container.find('#id')[0]` (returns `undefined`).
+- **Storage**: `S.get/set` - never `localStorage`.
+- **Icons**: `<span data-icon="name">` + call `I.scan()` after DOM updates.
+- **Tables**: `T.create(el, { data, columns })` - pass native DOM element via `.get(0)`.
+- **Toasts**: `E.toast('msg', { type: 'success' })`.
+- **Confirm**: `await E.confirm('message?')`.
+- **Templates**: `templateUrl: '/plugins/calendar/admin/templates/foo.html'` (absolute path).
+- **DOM updates with HTML strings**: Use `$(el).html(htmlString)` - Domma wraps DOMPurify. Avoid setting `.innerHTML` directly on raw DOM elements.
+- **Interactive elements inside HTML strings**: Build them with `document.createElement` + `appendChild` - Domma's `.html()` strips buttons and inputs.
+- **Route registration order in `plugin.public.js`**: Static segments before `/:slug`. Register `/feed.ics` first.
+- **`listEntries` returns `{ entries, total }`** - destructure: `const { entries } = await listEntries(SLUG, { limit: 100000 })`.
+- **Entry shape**: `{ id, data: { ...fields }, meta: { createdAt, updatedAt } }`. Flatten with helper: `const toEvent = e => ({ id: e.id, ...e.data, createdAt: e.meta.createdAt })`.
+- **`escapeHtml`** must be defined in every file that renders untrusted data into HTML strings.
+- **Contacts slug**: Check `plugins/contacts/plugin.js` for the current `CONTACTS_SLUG` constant before using it in RSVP upsert code. It should be `contacts-contacts` after the namespace rename.
+- **Server is always running on port 4096** - never kill or restart it. Use `curl` to verify endpoints.
+
+---
+
+## File Structure
+
+### New files
+```
+plugins/calendar/
+  plugin.json
+  plugin.js                   API routes + shortcode registration + onEnable/onDisable
+  plugin.public.js             Public SSR routes (listing, feed.ics, event page, RSVP POST)
+  service.js                  Exported createEvent/updateEvent/cancelEvent/createOccurrence/etc.
+  config.js
+  CLAUDE.md
+  collections/
+    calendar-events/schema.json
+    calendar-occurrences/schema.json
+    calendar-rsvps/schema.json
+  roles/
+    calendar-organiser.json
+    calendar-admin.json
+  forms/
+    calendar-rsvp.json
+  pages/
+    calendar.md
+  blocks/
+    upcoming-events.html
+  templates/
+    index.html                 Public events listing body template
+    event.html                 Public event detail body template (includes inline RSVP form)
+  admin/
+    views/
+      calendar.js              Events list with Grid / List / Split modes
+      event-editor.js          Create / edit event + recurrence + RSVP panels
+      rsvps.js                 RSVPs list
+      settings.js              Plugin settings form
+    templates/
+      calendar.html
+      event-editor.html
+      rsvps.html
+      settings.html
+```
+
+### Modified files
+```
+config/plugins.json            Add calendar entry (enabled: false initially, true after smoke test)
+```
+
+---
+
+## Task 1: Scaffolding - schemas, roles, forms, pages, blocks, manifest, config
+
+**Files:**
+- Create: `plugins/calendar/collections/calendar-events/schema.json`
+- Create: `plugins/calendar/collections/calendar-occurrences/schema.json`
+- Create: `plugins/calendar/collections/calendar-rsvps/schema.json`
+- Create: `plugins/calendar/roles/calendar-organiser.json`
+- Create: `plugins/calendar/roles/calendar-admin.json`
+- Create: `plugins/calendar/forms/calendar-rsvp.json`
+- Create: `plugins/calendar/pages/calendar.md`
+- Create: `plugins/calendar/blocks/upcoming-events.html`
+- Create: `plugins/calendar/plugin.json`
+- Create: `plugins/calendar/config.js`
+- Create: `plugins/calendar/CLAUDE.md`
+
+- [ ] **Step 1: Create directory structure**
+
+```bash
+mkdir -p plugins/calendar/collections/calendar-events
+mkdir -p plugins/calendar/collections/calendar-occurrences
+mkdir -p plugins/calendar/collections/calendar-rsvps
+mkdir -p plugins/calendar/roles
+mkdir -p plugins/calendar/forms
+mkdir -p plugins/calendar/pages
+mkdir -p plugins/calendar/blocks
+mkdir -p plugins/calendar/templates
+mkdir -p plugins/calendar/admin/views
+mkdir -p plugins/calendar/admin/templates
+```
+
+- [ ] **Step 2: Write `plugins/calendar/collections/calendar-events/schema.json`**
+
+```json
+{
+  "title": "Calendar Events",
+  "slug": "calendar-events",
+  "description": "Parent event records with recurrence rules.",
+  "plugin": "calendar",
+  "bundled": false,
+  "fields": [
+    { "key": "title",              "label": "Title",               "type": "text",     "required": true },
+    { "key": "slug",               "label": "Slug",                "type": "text",     "required": true },
+    { "key": "description",        "label": "Description",         "type": "markdown", "required": false },
+    { "key": "type",               "label": "Type",                "type": "select",   "required": true,
+      "options": ["meeting","interview","public-event","webinar","other"] },
+    { "key": "visibility",         "label": "Visibility",          "type": "select",   "required": true,
+      "options": ["public","private"] },
+    { "key": "location",           "label": "Location",            "type": "text",     "required": false },
+    { "key": "organiserId",        "label": "Organiser ID",        "type": "text",     "required": true },
+    { "key": "recurrence",         "label": "Recurrence",          "type": "object",   "required": false },
+    { "key": "windowGeneratedTo",  "label": "Window Generated To", "type": "datetime", "required": false },
+    { "key": "rsvpEnabled",        "label": "RSVP Enabled",        "type": "boolean",  "required": false },
+    { "key": "rsvpLimit",          "label": "RSVP Limit",          "type": "number",   "required": false },
+    { "key": "status",             "label": "Status",              "type": "select",   "required": true,
+      "options": ["active","cancelled"], "default": "active" }
+  ],
+  "api": { "list": true, "get": true, "create": true, "update": true, "delete": true },
+  "storage": { "adapter": "file" }
+}
+```
+
+- [ ] **Step 3: Write `plugins/calendar/collections/calendar-occurrences/schema.json`**
+
+```json
+{
+  "title": "Calendar Occurrences",
+  "slug": "calendar-occurrences",
+  "description": "Materialised event instances (one per occurrence, including recurring).",
+  "plugin": "calendar",
+  "bundled": false,
+  "fields": [
+    { "key": "eventId",     "label": "Event ID",    "type": "text",     "required": false },
+    { "key": "title",       "label": "Title",        "type": "text",     "required": true },
+    { "key": "slug",        "label": "Slug",         "type": "text",     "required": false,
+      "notes": "Denormalised from parent event at creation time. Null for Jobs-created standalone occurrences." },
+    { "key": "startAt",     "label": "Start",        "type": "datetime", "required": true },
+    { "key": "endAt",       "label": "End",          "type": "datetime", "required": true },
+    { "key": "type",        "label": "Type",         "type": "select",   "required": true,
+      "options": ["meeting","interview","public-event","webinar","other"] },
+    { "key": "visibility",  "label": "Visibility",   "type": "select",   "required": true,
+      "options": ["public","private"] },
+    { "key": "status",      "label": "Status",       "type": "select",   "required": true,
+      "options": ["active","cancelled","rescheduled"], "default": "active" },
+    { "key": "rsvpCount",   "label": "RSVP Count",   "type": "number",   "required": false },
+    { "key": "rsvpLimit",   "label": "RSVP Limit",   "type": "number",   "required": false },
+    { "key": "source",      "label": "Source",       "type": "text",     "required": false }
+  ],
+  "api": { "list": true, "get": true, "create": true, "update": true, "delete": true },
+  "storage": { "adapter": "file" }
+}
+```
+
+- [ ] **Step 4: Write `plugins/calendar/collections/calendar-rsvps/schema.json`**
+
+```json
+{
+  "title": "Calendar RSVPs",
+  "slug": "calendar-rsvps",
+  "description": "RSVP registrations for calendar occurrences.",
+  "plugin": "calendar",
+  "bundled": false,
+  "fields": [
+    { "key": "occurrenceId", "label": "Occurrence ID", "type": "text",    "required": true },
+    { "key": "name",         "label": "Name",           "type": "text",    "required": true },
+    { "key": "email",        "label": "Email",          "type": "text",    "required": true },
+    { "key": "status",       "label": "Status",         "type": "select",  "required": true,
+      "options": ["confirmed","cancelled"], "default": "confirmed" },
+    { "key": "contactId",    "label": "Contact ID",     "type": "text",    "required": false },
+    { "key": "createdAt",    "label": "Created At",     "type": "datetime","required": true }
+  ],
+  "api": { "list": true, "get": true, "create": true, "update": true, "delete": true },
+  "storage": { "adapter": "file" }
+}
+```
+
+- [ ] **Step 5: Write role files**
+
+`plugins/calendar/roles/calendar-organiser.json`:
+```json
+{
+  "name": "calendar-organiser",
+  "label": "Calendar Organiser",
+  "level": 2,
+  "permissions": ["calendar-events","calendar-occurrences"],
+  "badgeClass": "badge-info",
+  "plugin": "calendar",
+  "resources": [
+    { "key": "calendar-events",      "label": "Calendar Events",      "actions": ["read","create","update","delete"] },
+    { "key": "calendar-occurrences", "label": "Calendar Occurrences", "actions": ["read","update","delete"] }
+  ]
+}
+```
+
+`plugins/calendar/roles/calendar-admin.json`:
+```json
+{
+  "name": "calendar-admin",
+  "label": "Calendar Admin",
+  "level": 1,
+  "permissions": ["calendar-events","calendar-occurrences","calendar-rsvps","calendar-settings"],
+  "badgeClass": "badge-success",
+  "plugin": "calendar",
+  "resources": [
+    { "key": "calendar-events",      "label": "Calendar Events",      "actions": ["read","create","update","delete"] },
+    { "key": "calendar-occurrences", "label": "Calendar Occurrences", "actions": ["read","create","update","delete"] },
+    { "key": "calendar-rsvps",       "label": "Calendar RSVPs",       "actions": ["read","update","delete"] },
+    { "key": "calendar-settings",    "label": "Calendar Settings",    "actions": ["read","update"] }
+  ]
+}
+```
+
+- [ ] **Step 6: Write `plugins/calendar/forms/calendar-rsvp.json`**
+
+```json
+{
+  "slug": "calendar-rsvp",
+  "title": "Event RSVP",
+  "description": "RSVP registration form for calendar events.",
+  "plugin": "calendar",
+  "submitAction": "/calendar/rsvp",
+  "fields": [
+    { "name": "name",    "type": "string", "label": "Name",    "required": true,  "placeholder": "Your name",     "helper": "" },
+    { "name": "email",   "type": "email",  "label": "Email",   "required": true,  "placeholder": "you@email.com", "helper": "" },
+    { "name": "website", "type": "string", "label": "Website", "required": false, "placeholder": "",              "helper": "" }
+  ],
+  "settings": {
+    "submitText": "Register",
+    "successMessage": "You're registered!",
+    "layout": "stacked",
+    "honeypot": true,
+    "rateLimitPerMinute": 5
+  }
+}
+```
+
+Note: `submitAction` is set at seed time. If `basePath` changes in settings, disable then re-enable the plugin to reseed the form with the new path. The standalone shortcode embed (`[form slug="calendar-rsvp"]`) is **out of scope for v1** - the event detail page renders the RSVP form inline in `event.html`.
+
+- [ ] **Step 7: Write `plugins/calendar/pages/calendar.md`**
+
+```markdown
+---
+title: Events
+layout: default
+description: Upcoming events
+visibility: public
+plugin: calendar
+---
+[calendar /]
+```
+
+- [ ] **Step 8: Write `plugins/calendar/blocks/upcoming-events.html`**
+
+```
+[calendar limit="3" /]
+```
+
+- [ ] **Step 9: Write `plugins/calendar/plugin.json`**
+
+```json
+{
+  "name": "calendar",
+  "displayName": "Calendar",
+  "version": "1.0.0",
+  "description": "Public events calendar with RSVP, iCal feed, and recurring events.",
+  "author": "Domma CMS",
+  "date": "2026-04-07",
+  "icon": "calendar",
+  "admin": {
+    "sidebar": [
+      {
+        "id": "calendar",
+        "text": "Calendar",
+        "icon": "calendar",
+        "url": "#/plugins/calendar",
+        "section": "#/plugins/calendar",
+        "items": [
+          { "id": "calendar-events",   "text": "Events",   "url": "#/plugins/calendar" },
+          { "id": "calendar-rsvps",    "text": "RSVPs",    "url": "#/plugins/calendar/rsvps" },
+          { "id": "calendar-settings", "text": "Settings", "url": "#/plugins/calendar/settings" }
+        ]
+      }
+    ],
+    "routes": [
+      { "path": "/plugins/calendar",            "view": "plugin-calendar",          "title": "Calendar - Domma CMS" },
+      { "path": "/plugins/calendar/events/new", "view": "plugin-calendar-editor",   "title": "New Event - Domma CMS" },
+      { "path": "/plugins/calendar/events/:id", "view": "plugin-calendar-editor",   "title": "Edit Event - Domma CMS" },
+      { "path": "/plugins/calendar/rsvps",      "view": "plugin-calendar-rsvps",    "title": "Calendar RSVPs - Domma CMS" },
+      { "path": "/plugins/calendar/settings",   "view": "plugin-calendar-settings", "title": "Calendar Settings - Domma CMS" }
+    ],
+    "views": {
+      "plugin-calendar":          { "entry": "calendar/admin/views/calendar.js?v=1",      "exportName": "calendarView" },
+      "plugin-calendar-editor":   { "entry": "calendar/admin/views/event-editor.js?v=1",  "exportName": "eventEditorView" },
+      "plugin-calendar-rsvps":    { "entry": "calendar/admin/views/rsvps.js?v=1",         "exportName": "rsvpsView" },
+      "plugin-calendar-settings": { "entry": "calendar/admin/views/settings.js?v=1",      "exportName": "settingsView" }
+    }
+  }
+}
+```
+
+- [ ] **Step 10: Write `plugins/calendar/config.js`**
+
+```js
+export default {
+    basePath:         '/calendar',
+    eventsPerPage:    12,
+    rsvpEnabled:      true,
+    defaultView:      'list',
+    occurrenceWindow: 365,
+    feedLength:       50,
+    storage: { adapter: 'file' }
+};
+```
+
+- [ ] **Step 11: Write `plugins/calendar/CLAUDE.md`**
+
+```markdown
+# Calendar Plugin - AI Assistant Guide
+
+## Purpose
+Public-facing events calendar with RSVP, iCal feed, recurring events, and a `service.js`
+layer for direct import by the Jobs plugin.
+
+## Files
+- `plugin.js` - API routes + `[calendar /]` shortcode + `onEnable`/`onDisable` lifecycle
+- `plugin.public.js` - SSR public routes (listing, feed.ics, event page, RSVP POST)
+- `service.js` - `createEvent`, `updateEvent`, `cancelEvent`, `createOccurrence`, `getOccurrence`, `cancelOccurrence`, `generateOccurrences`
+- `config.js` - defaults: `basePath`, `eventsPerPage`, `rsvpEnabled`, `defaultView`, `occurrenceWindow`, `feedLength`
+
+## Collections
+| Slug | Purpose |
+|---|---|
+| `calendar-events` | Parent events with recurrence rules |
+| `calendar-occurrences` | Materialised instances (one per occurrence) |
+| `calendar-rsvps` | RSVP registrations |
+
+## API Routes (`/api/plugins/calendar`) - all require `authenticate`
+
+| Method | Path | Notes |
+|---|---|---|
+| GET/POST | `/events` | List / create parent events |
+| GET/PUT/DELETE | `/events/:id` | Get / update / cancel event |
+| GET | `/occurrences` | List occurrences (`?from=&to=&type=&visibility=&eventId=`) |
+| GET/PUT/DELETE | `/occurrences/:id` | Get / update / cancel single occurrence |
+| GET/PUT/DELETE | `/rsvps` / `/rsvps/:id` | RSVPs |
+| GET/PUT | `/settings` | Plugin settings |
+
+## Public Routes (under `basePath`, default `/calendar`)
+| Method | Path | Notes |
+|---|---|---|
+| GET | `/feed.ics` | iCal feed - registered BEFORE event slug route |
+| GET | `/event/:slug` | Event detail + inline RSVP form |
+| GET | `/page/:n` | Paginated listing |
+| GET | `/` | Events listing (page 1) |
+| POST | `/rsvp` | RSVP submission - no auth, honeypot protected |
+
+## Roles
+- `calendar-organiser` (level 2) - CRUD own events/occurrences
+- `calendar-admin` (level 1) - full access including RSVPs and settings
+
+## Ownership gate pattern
+```js
+const ADMIN_ROLES = ['calendar-admin', 'admin', 'super-admin'];
+if (!ADMIN_ROLES.includes(request.user.role) && event.organiserId !== request.user.id) {
+    return reply.code(403).send({ error: 'Forbidden' });
+}
+```
+Do NOT use `getRoleLevel()` - organiser and base user are both level 2.
+
+## Shortcode handler signature
+```js
+options.hooks.registerShortcode('calendar', async (attrStr, body, context) => {
+    const attrs = context.parseShortcodeAttrs(attrStr);
+    // body is null for [calendar /] (self-closing)
+    // return HTML string
+});
+```
+
+## Gotchas
+- **Route order**: In `plugin.public.js`, register `/feed.ics` before `/event/:slug` before base `/`.
+- **Occurrence slug**: Denormalised from parent event. Null for Jobs-created occurrences.
+- **Top-up trigger**: Only fires on `GET /occurrences?eventId=<id>` when `to` is within 30 days of `event.windowGeneratedTo`.
+- **Soft cancel**: `DELETE /events/:id` sets `status: cancelled` - no hard deletes.
+- **Jobs integration**: `import { createOccurrence } from '../calendar/service.js'` - one-way dependency.
+- **Seeded assets**: form, page, block, views - seeded via `onEnable`, removed via `onDisable`.
+- **DOM updates**: Use `$(el).html(str)` not raw `.innerHTML` - Domma sanitises via DOMPurify.
+```
+
+- [ ] **Step 12: Commit scaffolding**
+
+```bash
+git add plugins/calendar/
+git commit -m "feat(calendar): add plugin scaffolding - schemas, roles, forms, pages, blocks, manifest"
+```
+
+> **Note - `setupPlugin` auto-seeding:** When Calendar is enabled via the admin UI, `setupPlugin` automatically copies `plugins/calendar/forms/calendar-rsvp.json` → `content/forms/`, `plugins/calendar/pages/calendar.md` → `content/pages/`, `plugins/calendar/roles/*.json` → `content/collections/roles/data.json`, and creates all three collection directories. Creating the files in this task is all that is required - no additional implementation needed. The `onEnable` export (Task 3) handles only blocks and views, which `setupPlugin` does NOT seed.
+>
+> **Note - `teardownPlugin`:** `teardownPlugin` is called automatically by the plugin system on disable. The plugin implementer does NOT write a `teardownPlugin` function - it is handled by the CMS. It removes the seeded page, form, and roles. `onDisable` (Task 3) handles block and views removal - those are NOT touched by `teardownPlugin`.
+
+---
+
+## Task 2: `service.js` - core business logic
+
+**Files:**
+- Create: `plugins/calendar/service.js`
+
+Service functions are used by both `plugin.js` (API routes) and Jobs (via direct import). No Fastify, no HTTP - pure collection CRUD.
+
+### Dependencies
+
+```js
+import {
+    listEntries, createEntry, updateEntry, deleteEntry, getEntry
+} from '../../server/services/collections.js';
+import { getConfig } from '../../server/config.js';
+```
+
+No Fastify, no `options` object. Config is read via `getConfig()` at call time.
+
+**Disabled-state guard:** If Calendar is disabled its collections do not exist and `createEntry` will throw. Callers (e.g. Jobs) must check plugin state before calling:
+
+```js
+const calendarEnabled = options.config?.plugins?.calendar?.enabled ?? false;
+if (calendarEnabled) {
+    const { createOccurrence } = await import('../calendar/service.js');
+}
+```
+
+`service.js` itself does not guard - it trusts callers.
+
+- [ ] **Step 1: Write `plugins/calendar/service.js`**
+
+Write the full file with these exported constants and functions:
+
+**Constants (export these so plugin.js and plugin.public.js can import them):**
+```js
+export const EVENTS_SLUG      = 'calendar-events';
+export const OCCURRENCES_SLUG = 'calendar-occurrences';
+export const RSVPS_SLUG       = 'calendar-rsvps';
+```
+
+**Flatten helpers:**
+```js
+export const toEvent      = e => ({ id: e.id, ...e.data, createdAt: e.meta.createdAt, updatedAt: e.meta.updatedAt });
+export const toOccurrence = e => ({ id: e.id, ...e.data, createdAt: e.meta.createdAt, updatedAt: e.meta.updatedAt });
+export const toRsvp       = e => ({ id: e.id, ...e.data });
+```
+
+**`slugify(str)`** - lowercases, replaces non-alphanumeric with `-`, strips leading/trailing `-`.
+
+**`generateOccurrences(event, windowDays)`:**
+- Reads `occurrenceWindow` from `getConfig()` as fallback if `windowDays` is undefined
+- Uses `event.startAt` as the series origin; skips past dates relative to today
+- Supports `freq`: `daily`, `weekly`, `monthly`, `yearly`
+- Supports `interval` (default 1), `byday` array (e.g. `['MO','WE']`) for weekly, `until` date string, `count` limit
+- For each generated date, calls `createEntry(OCCURRENCES_SLUG, { eventId, title, slug, startAt, endAt, type, visibility, status: 'active', rsvpCount: 0, rsvpLimit, source: 'calendar' })`
+- After generating, calls `updateEntry(EVENTS_SLUG, event.id, { ...event, windowGeneratedTo: effectiveEnd.toISOString() })`
+- Returns array of created occurrence IDs
+
+**`createEvent(data)`:**
+- Derives slug from `data.slug` or `slugify(data.title)`
+- Calls `createEntry(EVENTS_SLUG, { title, slug, description, type, visibility, location, organiserId, recurrence, windowGeneratedTo: null, rsvpEnabled, rsvpLimit, status: 'active', startAt, endAt })`
+- If recurring: calls `generateOccurrences(event, occurrenceWindow)`
+- If one-off: calls `createEntry(OCCURRENCES_SLUG, { eventId, title, slug, startAt, endAt, type, visibility, status: 'active', rsvpCount: 0, rsvpLimit, source: 'calendar' })`
+- Returns flattened event
+
+**`updateEvent(id, data)`:**
+- Deletes all occurrences where `eventId === id && startAt > now` (future occurrences only - past preserved)
+- Merges `data` into `existing.data` and calls `updateEntry`
+- If recurring: calls `generateOccurrences(updatedEvent, occurrenceWindow)`
+- Returns updated event
+
+**`cancelEvent(id)`:**
+- Sets `status: 'cancelled'` on the parent event
+- Fetches occurrences with `listEntries(OCCURRENCES_SLUG, { limit: 100000 })` - must use high limit to avoid pagination truncation
+- Sets `status: 'cancelled'` on all occurrences where `eventId === id && startAt >= now`
+- Returns cancelled event
+
+**`createOccurrence(data)`:**
+- Primary Jobs entry point - creates standalone occurrence with `eventId: data.eventId ?? null`, `slug: data.slug ?? null`, `source: data.source ?? 'calendar'`
+- Returns flattened occurrence
+
+**`getOccurrence(id)`:** - calls `getEntry(OCCURRENCES_SLUG, id)`, returns flattened or `null`
+
+**`cancelOccurrence(id)`:** - sets `status: 'cancelled'` on a single occurrence, returns updated
+
+- [ ] **Step 2: Verify importable**
+
+```bash
+node --input-type=module <<'EOF'
+import { createEvent, createOccurrence, generateOccurrences } from './plugins/calendar/service.js';
+console.log(typeof createEvent, typeof createOccurrence, typeof generateOccurrences);
+EOF
+```
+Expected: `function function function`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add plugins/calendar/service.js
+git commit -m "feat(calendar): add service.js - createEvent, generateOccurrences, createOccurrence and friends"
+```
+
+---
+
+## Task 3: `plugin.js` - API routes, shortcode, lifecycle
+
+**Files:**
+- Create: `plugins/calendar/plugin.js`
+
+All routes under `/api/plugins/calendar`. Shortcode `[calendar /]` registered via `options.hooks.registerShortcode`. `onEnable` / `onDisable` exports seed/remove block and views.
+
+- [ ] **Step 1: Write `plugins/calendar/plugin.js`**
+
+Structure:
+
+```js
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import defaultConfig from './config.js';
+import { listEntries, getEntry, createEntry, updateEntry, deleteEntry } from '../../server/services/collections.js';
+import { getConfig, saveConfig } from '../../server/config.js';
+import {
+    EVENTS_SLUG, OCCURRENCES_SLUG, RSVPS_SLUG,
+    toEvent, toOccurrence, toRsvp,
+    createEvent, updateEvent, cancelEvent,
+    createOccurrence, cancelOccurrence, generateOccurrences
+} from './service.js';
+
+const ADMIN_ROLES = ['calendar-admin', 'admin', 'super-admin'];
+const isAdmin    = user => ADMIN_ROLES.includes(user?.role);
+const isOrg      = user => [...ADMIN_ROLES, 'calendar-organiser'].includes(user?.role);
+```
+
+**Shortcode registration** (inside the exported Fastify plugin function, after `const settings = ...`):
+
+> **IMPORTANT - signature discrepancy:** The spec's shortcode example shows a two-argument signature `(attrs, context)` where `attrs` is pre-parsed. That is WRONG. The CMS hook system always calls handlers as `(attrStr, body, context)` where `attrStr` is the raw attribute string. Always use the three-argument form below and parse with `context.parseShortcodeAttrs(attrStr)`.
+
+```js
+const escapeHtml = s => String(s ?? '').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
+
+options.hooks.registerShortcode('calendar', async (attrStr, body, context) => {
+    const attrs    = context.parseShortcodeAttrs(attrStr);
+    const limit    = parseInt(attrs.limit ?? settings.eventsPerPage, 10) || 12;
+    const typeFilter = attrs.type ?? null;
+    try {
+        const now = new Date().toISOString();
+        const { entries } = await listEntries(OCCURRENCES_SLUG, { limit: 100000, sort: 'startAt', order: 'asc' });
+        let upcoming = entries.map(toOccurrence)
+            .filter(o => o.visibility === 'public' && o.status === 'active' && o.startAt >= now);
+        if (typeFilter) upcoming = upcoming.filter(o => o.type === typeFilter);
+        upcoming = upcoming.slice(0, limit);
+        if (!upcoming.length) return '<p class="text-muted">No upcoming events.</p>';
+        const base = (settings.basePath ?? '/calendar').replace(/\/$/, '');
+        const items = upcoming.map(o => {
+            const date = new Date(o.startAt).toLocaleDateString('en-GB', { weekday:'short', day:'numeric', month:'short' });
+            const href = o.slug ? `${base}/event/${encodeURIComponent(o.slug)}` : null;
+            const title = escapeHtml(o.title);
+            const type  = escapeHtml(o.type);
+            return `<div class="card mb-3"><div class="card-body"><div class="text-muted small">${date}</div>`
+                + `<h5 class="card-title">${href ? `<a href="${href}">${title}</a>` : title}</h5>`
+                + (type ? `<span class="badge badge-secondary">${type}</span>` : '')
+                + '</div></div>';
+        }).join('');
+        return `<div class="calendar-shortcode">${items}</div>`;
+    } catch { return ''; }
+});
+```
+
+**Routes to implement** (follow blog/plugin.js pattern exactly):
+
+Events:
+- `GET /events` - list; organisers see own only, admins see all
+- `POST /events` - calls `createEvent({ ...body, organiserId: uid })`; 201 response
+- `GET /events/:id` - 404 for not-found; 404 for organiser viewing others' events
+- `PUT /events/:id` - ownership gate with `ADMIN_ROLES` named list; read-only if `source === 'jobs'`; calls `updateEvent()`
+- `DELETE /events/:id` - admin-only; calls `cancelEvent()`
+
+Occurrences:
+- `GET /occurrences` - filters: `from`, `to`, `type`, `visibility`, `eventId`; top-up logic when `eventId` present and `to` is within 30 days of `event.windowGeneratedTo`; organisers see occurrences from own events only
+- `GET /occurrences/:id` - simple fetch
+- `PUT /occurrences/:id` - ownership gate via parent event's `organiserId`
+- `DELETE /occurrences/:id` - calls `cancelOccurrence()`
+
+RSVPs:
+- `GET /rsvps` - filters: `occurrenceId`, `status`; organisers scoped to own events' occurrences
+- `PUT /rsvps/:id` - update status
+- `DELETE /rsvps/:id` - hard delete
+
+Settings:
+- `GET /settings` - admin-only; returns current `settings` object
+- `PUT /settings` - admin-only; merges into `config/plugins.json` under `plugins.calendar.settings` using `saveConfig`
+
+**Lifecycle exports** (these are named exports from `plugin.js`, NOT Fastify routes):
+
+```js
+export async function onEnable({ fastify, services }) {
+    // Seed block
+    const blockPath = path.resolve('content/blocks/upcoming-events.html');
+    try { await fs.access(blockPath); } catch {
+        await fs.writeFile(blockPath, '[calendar limit="3" /]\n', 'utf8');
+    }
+    // Seed views (advisory - for admin Collections UI)
+    const views = [
+        { slug: 'calendar-upcoming',  label: 'Upcoming Events', collection: 'calendar-occurrences',
+          filter: { status: 'active' }, sort: { field: 'startAt', direction: 'asc' } },
+        { slug: 'calendar-past',      label: 'Past Events',     collection: 'calendar-occurrences',
+          filter: {},                  sort: { field: 'startAt', direction: 'desc' } },
+        { slug: 'calendar-my-events', label: 'My Events',       collection: 'calendar-occurrences',
+          filter: {},                  sort: { field: 'startAt', direction: 'asc' } }
+    ];
+    for (const view of views) {
+        const p = path.resolve(`content/views/${view.slug}.json`);
+        try { await fs.access(p); } catch {
+            await fs.writeFile(p, JSON.stringify(view, null, 2), 'utf8');
+        }
+    }
+}
+
+export async function onDisable({ fastify, services }) {
+    await fs.unlink(path.resolve('content/blocks/upcoming-events.html')).catch(() => {});
+    for (const slug of ['calendar-upcoming', 'calendar-past', 'calendar-my-events']) {
+        await fs.unlink(path.resolve(`content/views/${slug}.json`)).catch(() => {});
+    }
+}
+```
+
+- [ ] **Step 2: Add calendar to `config/plugins.json`**
+
+Open `config/plugins.json` and add: `"calendar": { "enabled": false, "bundled": false, "settings": {} }`
+
+- [ ] **Step 3: Smoke-test routes respond**
+
+```bash
+curl -s http://localhost:4096/api/plugins/calendar/events \
+  -H "Authorization: Bearer INVALID_TOKEN" | grep -o '"error"\|"message"'
+```
+Expected: `"error"` or `"message"` (not a 404 on the route itself - the plugin is loaded)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/calendar/plugin.js config/plugins.json
+git commit -m "feat(calendar): add plugin.js - API routes, shortcode registration, onEnable/onDisable lifecycle"
+```
+
+---
+
+## Task 4: `plugin.public.js` - public SSR routes
+
+**Files:**
+- Create: `plugins/calendar/plugin.public.js`
+
+Receives `options = { settings, auth: { authenticate, requireAdmin }, config }`.
+`basePath` resolved as `(options.settings?.basePath ?? '/calendar').replace(/\/$/, '')`.
+
+**CRITICAL: Route registration order** - register `feed.ics` FIRST, then `rsvp`, then `/event/:slug`, then paginated `/page/:n`, then base `/`. Fastify matches in registration order; `/event/:slug` registered last (of the static routes) to avoid swallowing the feed.
+
+- [ ] **Step 1: Before writing - read `server/services/renderer.js`**
+
+Open `server/services/renderer.js` and find `renderBlogPage`. Confirm its signature (typically `renderBlogPage(templatePath, data, seoMeta, reply)`). The Blog plugin uses it for plugin SSR pages; Calendar follows the same pattern. If the signature differs from what the plan describes, adjust the calls accordingly.
+
+- [ ] **Step 2: Write `plugins/calendar/plugin.public.js`**
+
+Imports:
+```js
+import path from 'node:path';
+import { fileURLToPath } from 'url';
+import { renderBlogPage } from '../../server/services/renderer.js';
+import { listEntries, getEntry, createEntry, updateEntry } from '../../server/services/collections.js';
+import { getConfig } from '../../server/config.js';
+import { EVENTS_SLUG, OCCURRENCES_SLUG, RSVPS_SLUG, toOccurrence } from './service.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+```
+
+**Helpers:**
+```js
+function escapeHtml(s) { return String(s ?? '').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;'); }
+function toIcalDate(iso) { return iso.replace(/[-:]/g,'').replace(/\.\d{3}/,''); }
+const isPublicActive = o => o.visibility === 'public' && o.status === 'active';
+```
+
+**`GET {base}/feed.ics`** - iCal 2.0 feed:
+- Fetch public active occurrences (sorted by `startAt`, limited to `feedLength`)
+- For each occurrence build a `VEVENT` with: `UID:<id>@<hostname>`, `DTSTAMP:<now>`, `DTSTART`, `DTEND`, `SUMMARY`, `DESCRIPTION`, `LOCATION` (if set), `URL:<siteUrl>/calendar/event/<slug>` (omit if `slug` is null)
+- Wrap in `BEGIN:VCALENDAR` / `END:VCALENDAR` with `CRLF` line endings
+- Reply with `Content-Type: text/calendar`
+
+**`POST {base}/rsvp`** - RSVP submission:
+1. Honeypot check: if `website` field non-empty → return 201 silently
+2. Validate `occurrenceId`, `name`, `email` - return 400 if missing
+3. Fetch occurrence - 404 if not found
+4. Capacity: if `rsvpLimit` set and `rsvpCount >= rsvpLimit` → 409
+5. Duplicate: check `calendar-rsvps` for same `occurrenceId` + `email` + `status: confirmed` → 200 if found
+6. Build `rsvpData = { occurrenceId, name, email, status: 'confirmed', contactId: null, createdAt: new Date().toISOString() }`
+7. Contacts upsert: if `getConfig()?.plugins?.calendar?.enabled && getConfig()?.plugins?.contacts?.enabled` → check `contacts-contacts` for matching email; upsert (verify slug constant first); store `contactId`
+8. `createEntry(RSVPS_SLUG, rsvpData)`
+9. Increment `rsvpCount` on occurrence via `updateEntry`
+10. If `Accept` header includes `text/html` → redirect to `{base}/event/{slug}?rsvp=success`; else return `201 { ok: true }`
+
+**`GET {base}/event/:slug`** - event detail page:
+- List occurrences, find first public active one matching the slug
+- 404 if not found
+- If `eventId` is set, fetch parent event for `description` and `location`
+- Call `renderBlogPage(path.join(templateDir, 'event.html'), { occ, description, location, ... }, seoMeta, reply)`
+
+**Listing helper `renderListing(reply, page)`:**
+- List public active occurrences with `startAt >= now`, sorted ascending
+- Paginate with `eventsPerPage`
+- Call `renderBlogPage(path.join(templateDir, 'index.html'), { events, page, totalPages, base }, { title: 'Events' }, reply)`
+
+**`GET {base}/page/:n`** → `renderListing(reply, parseInt(n))`
+
+**`GET {base}`** → `renderListing(reply, 1)`
+
+- [ ] **Step 3: Verify public plugin exports a default function**
+
+```bash
+node --input-type=module <<'EOF'
+import plugin from './plugins/calendar/plugin.public.js';
+console.log(typeof plugin);
+EOF
+```
+Expected: `function`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/calendar/plugin.public.js
+git commit -m "feat(calendar): add plugin.public.js - public listing, iCal feed, event page, RSVP POST"
+```
+
+---
+
+## Task 5: Public body templates
+
+**Files:**
+- Create: `plugins/calendar/templates/index.html`
+- Create: `plugins/calendar/templates/event.html`
+
+**CRITICAL: Before writing these, read how `renderBlogPage` works:**
+
+```bash
+sed -n '/export async function renderBlogPage/,/^}/p' server/services/renderer.js | head -60
+cat plugins/blog/templates/index.html
+```
+
+Follow the exact same pattern that the blog plugin uses. The `data` object passed to `renderBlogPage` is used to construct the HTML body string - the exact mechanism (string interpolation, template engine, etc.) depends on what `renderBlogPage` does. Match the blog's approach exactly.
+
+- [ ] **Step 1: Read blog's `renderBlogPage` implementation and `plugins/blog/templates/index.html`**
+
+Run:
+```bash
+sed -n '/export async function renderBlogPage/,/^}/p' server/services/renderer.js | head -80
+cat plugins/blog/templates/index.html
+```
+
+- [ ] **Step 2: Write `plugins/calendar/templates/index.html`**
+
+Build to match the blog template pattern. Include:
+- Page heading "Events"
+- List/grid of event cards: title (linked to `/calendar/event/{slug}` if slug exists), date, time, type badge, location (if set)
+- Pagination nav (Previous / Next links when `totalPages > 1`)
+- "No upcoming events" empty state
+
+- [ ] **Step 3: Write `plugins/calendar/templates/event.html`**
+
+Include:
+- Event title as `<h1>`
+- Date / time formatted as human-readable string
+- Location (if set)
+- Description rendered as HTML (check how blog renders Markdown in public templates)
+- RSVP success banner (shown when `?rsvp=success` query param is present - check the `rsvpSuccess` data field)
+- Inline RSVP form when `showRsvp` is true and `atCapacity` is false:
+
+```html
+<form method="POST" action="{base}/rsvp">
+  <input type="hidden" name="occurrenceId" value="{occ.id}">
+  <div class="mb-3">
+    <label>Name *</label>
+    <input type="text" name="name" required class="form-control">
+  </div>
+  <div class="mb-3">
+    <label>Email *</label>
+    <input type="email" name="email" required class="form-control">
+  </div>
+  <div style="display:none">
+    <label>Website<br><input type="text" name="website"></label>
+  </div>
+  <button type="submit" class="btn btn-primary">Register</button>
+</form>
+```
+
+- "At capacity" message when `atCapacity` is true
+- Current RSVP count when `rsvpCount > 0`
+
+- [ ] **Step 4: Enable calendar and smoke-test public routes**
+
+Set `"calendar": { "enabled": true }` in `config/plugins.json`, then:
+
+```bash
+# Public listing
+curl -s http://localhost:4096/calendar | grep -c '<title>'
+
+# iCal feed
+curl -s http://localhost:4096/calendar/feed.ics | head -3
+```
+Expected for feed:
+```
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Domma CMS//Calendar//EN
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/calendar/templates/
+git commit -m "feat(calendar): add public body templates - events listing and event detail with RSVP form"
+```
+
+---
+
+## Task 6: Admin HTML templates
+
+**Files:**
+- Create: `plugins/calendar/admin/templates/calendar.html`
+- Create: `plugins/calendar/admin/templates/event-editor.html`
+- Create: `plugins/calendar/admin/templates/rsvps.html`
+- Create: `plugins/calendar/admin/templates/settings.html`
+
+Admin templates are static HTML shells - all dynamic content is injected by the corresponding `.js` view using Domma APIs. Follow the blog plugin template pattern (`plugins/blog/admin/templates/blog.html`).
+
+- [ ] **Step 1: Write `plugins/calendar/admin/templates/calendar.html`**
+
+```html
+<div class="d-flex justify-content-between align-items-center mb-3">
+  <h2 class="mb-0">Events</h2>
+  <div class="d-flex gap-2 align-items-center">
+    <div class="btn-group" role="group">
+      <button id="btn-view-grid"  class="btn btn-sm btn-outline" title="Grid view">
+        <span data-icon="grid" data-icon-size="14"></span>
+      </button>
+      <button id="btn-view-list"  class="btn btn-sm btn-outline" title="List view">
+        <span data-icon="list" data-icon-size="14"></span>
+      </button>
+      <button id="btn-view-split" class="btn btn-sm btn-outline" title="Split view">
+        <span data-icon="columns" data-icon-size="14"></span>
+      </button>
+    </div>
+    <button id="btn-new-event" class="btn btn-sm btn-primary">
+      <span data-icon="plus" data-icon-size="14"></span> New Event
+    </button>
+  </div>
+</div>
+
+<div class="d-flex gap-2 mb-3">
+  <select id="filter-type" class="form-control form-control-sm" style="width:auto;">
+    <option value="">All types</option>
+    <option value="meeting">Meeting</option>
+    <option value="interview">Interview</option>
+    <option value="public-event">Public Event</option>
+    <option value="webinar">Webinar</option>
+    <option value="other">Other</option>
+  </select>
+  <select id="filter-visibility" class="form-control form-control-sm" style="width:auto;">
+    <option value="">All visibility</option>
+    <option value="public">Public</option>
+    <option value="private">Private</option>
+  </select>
+</div>
+
+<!-- Grid view -->
+<div id="view-grid" style="display:none;">
+  <div class="d-flex justify-content-between align-items-center mb-2">
+    <button id="btn-prev-month" class="btn btn-sm btn-outline">&laquo;</button>
+    <strong id="grid-month-label"></strong>
+    <button id="btn-next-month" class="btn btn-sm btn-outline">&raquo;</button>
+  </div>
+  <div id="calendar-grid"></div>
+</div>
+
+<!-- List view -->
+<div id="view-list" style="display:none;">
+  <div id="events-table"></div>
+</div>
+
+<!-- Split view -->
+<div id="view-split" style="display:none;">
+  <div class="d-flex gap-3">
+    <div style="width:240px;flex-shrink:0;">
+      <div class="d-flex justify-content-between align-items-center mb-2">
+        <button id="btn-split-prev" class="btn btn-sm btn-outline">&laquo;</button>
+        <strong id="split-month-label"></strong>
+        <button id="btn-split-next" class="btn btn-sm btn-outline">&raquo;</button>
+      </div>
+      <div id="split-mini-cal"></div>
+    </div>
+    <div style="flex:1;">
+      <div id="split-day-label" class="text-muted small mb-2"></div>
+      <div id="split-day-events"></div>
+    </div>
+  </div>
+</div>
+```
+
+- [ ] **Step 2: Write `plugins/calendar/admin/templates/event-editor.html`**
+
+```html
+<div class="d-flex justify-content-between align-items-center mb-3">
+  <h2 class="mb-0" id="editor-heading">New Event</h2>
+  <div class="d-flex gap-2">
+    <button id="btn-cancel" class="btn btn-sm btn-outline">Cancel</button>
+    <button id="btn-save"   class="btn btn-sm btn-primary">Save Event</button>
+  </div>
+</div>
+
+<div id="jobs-notice" style="display:none;" class="alert alert-info mb-3">
+  This event is managed by Jobs and is read-only.
+</div>
+
+<div class="d-flex gap-3" id="editor-body">
+  <div style="flex:1;">
+    <div class="mb-3">
+      <label class="form-label">Title *</label>
+      <input id="field-title" type="text" class="form-control" placeholder="Event title">
+    </div>
+    <div class="mb-3">
+      <label class="form-label">Slug</label>
+      <div class="d-flex gap-2 align-items-center">
+        <input id="field-slug" type="text" class="form-control" placeholder="auto-derived">
+        <label style="white-space:nowrap;font-size:12px;">
+          <input type="checkbox" id="slug-auto" checked> Auto
+        </label>
+      </div>
+    </div>
+    <div class="mb-3">
+      <label class="form-label">Description (Markdown)</label>
+      <textarea id="field-description" class="form-control" rows="5" placeholder="Optional description"></textarea>
+    </div>
+    <div class="d-flex gap-2 mb-3">
+      <div style="flex:1;">
+        <label class="form-label">Type</label>
+        <select id="field-type" class="form-control">
+          <option value="meeting">Meeting</option>
+          <option value="interview">Interview</option>
+          <option value="public-event">Public Event</option>
+          <option value="webinar">Webinar</option>
+          <option value="other">Other</option>
+        </select>
+      </div>
+      <div style="flex:1;">
+        <label class="form-label">Visibility</label>
+        <select id="field-visibility" class="form-control">
+          <option value="private">Private</option>
+          <option value="public">Public</option>
+        </select>
+      </div>
+    </div>
+    <div class="mb-3">
+      <label class="form-label">Location</label>
+      <input id="field-location" type="text" class="form-control" placeholder="Address or video URL">
+    </div>
+    <div class="d-flex gap-2 mb-3">
+      <div style="flex:1;">
+        <label class="form-label">Start *</label>
+        <input id="field-start" type="datetime-local" class="form-control">
+      </div>
+      <div style="flex:1;">
+        <label class="form-label">End *</label>
+        <input id="field-end" type="datetime-local" class="form-control">
+      </div>
+    </div>
+  </div>
+  <div style="width:220px;flex-shrink:0;">
+    <div class="card mb-3">
+      <div class="card-header" style="font-size:12px;font-weight:600;">Recurrence</div>
+      <div class="card-body" style="font-size:12px;">
+        <label class="d-flex align-items-center gap-2 mb-2">
+          <input type="checkbox" id="recurrence-enabled"> Recurring event
+        </label>
+        <div id="recurrence-fields" style="display:none;">
+          <div class="mb-2">
+            <label>Frequency</label>
+            <select id="field-freq" class="form-control form-control-sm">
+              <option value="daily">Daily</option>
+              <option value="weekly" selected>Weekly</option>
+              <option value="monthly">Monthly</option>
+              <option value="yearly">Yearly</option>
+            </select>
+          </div>
+          <div class="mb-2">
+            <label>Every</label>
+            <input id="field-interval" type="number" min="1" value="1" class="form-control form-control-sm">
+          </div>
+          <div id="byday-section" class="mb-2">
+            <label>On days</label>
+            <div class="d-flex gap-1 flex-wrap" id="byday-checks">
+              <label><input type="checkbox" value="MO"> Mo</label>
+              <label><input type="checkbox" value="TU"> Tu</label>
+              <label><input type="checkbox" value="WE"> We</label>
+              <label><input type="checkbox" value="TH"> Th</label>
+              <label><input type="checkbox" value="FR"> Fr</label>
+              <label><input type="checkbox" value="SA"> Sa</label>
+              <label><input type="checkbox" value="SU"> Su</label>
+            </div>
+          </div>
+          <div class="mb-2">
+            <label>Until</label>
+            <input id="field-until" type="date" class="form-control form-control-sm">
+          </div>
+        </div>
+      </div>
+    </div>
+    <div class="card">
+      <div class="card-header" style="font-size:12px;font-weight:600;">RSVP</div>
+      <div class="card-body" style="font-size:12px;">
+        <label class="d-flex align-items-center gap-2 mb-2">
+          <input type="checkbox" id="rsvp-enabled"> Accept RSVPs
+        </label>
+        <div id="rsvp-fields" style="display:none;">
+          <label>Capacity (blank = unlimited)</label>
+          <input id="field-rsvp-limit" type="number" min="1" class="form-control form-control-sm" placeholder="Unlimited">
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+- [ ] **Step 3: Write `plugins/calendar/admin/templates/rsvps.html`**
+
+```html
+<div class="d-flex justify-content-between align-items-center mb-3">
+  <h2 class="mb-0">RSVPs</h2>
+</div>
+<div class="d-flex gap-2 mb-3">
+  <select id="filter-occurrence" class="form-control form-control-sm" style="max-width:320px;">
+    <option value="">All events</option>
+  </select>
+  <select id="filter-status" class="form-control form-control-sm" style="width:auto;">
+    <option value="">All statuses</option>
+    <option value="confirmed">Confirmed</option>
+    <option value="cancelled">Cancelled</option>
+  </select>
+</div>
+<div id="rsvps-table"></div>
+```
+
+- [ ] **Step 4: Write `plugins/calendar/admin/templates/settings.html`**
+
+```html
+<div class="mb-3">
+  <h2>Settings</h2>
+</div>
+<div class="card" style="max-width:520px;">
+  <div class="card-body">
+    <div id="settings-form"></div>
+  </div>
+</div>
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/calendar/admin/templates/
+git commit -m "feat(calendar): add admin HTML templates"
+```
+
+---
+
+## Task 7: Admin view: `calendar.js` - events list (Grid, List, Split)
+
+**Files:**
+- Create: `plugins/calendar/admin/views/calendar.js`
+
+This is the most complex admin view. Manages three rendering modes, month navigation for Grid/Split, and a filter bar. All event data fetched via `H.get`. View mode preference persisted via `S.set('calendar_view', mode)`.
+
+**Key implementation notes:**
+- Use `T.create()` for the List mode - same pattern as `plugins/blog/admin/views/blog.js`
+- For Grid and Split calendar grids: build HTML strings with `escapeHtml()` for all user data, then use `$(el).html(htmlString)` to update the DOM - this goes through Domma's DOMPurify sanitisation
+- For Split day events: same pattern - build HTML string, set via `$(el).html(str)`
+- Interactive elements (edit buttons in Split view): build with `document.createElement` and `appendChild`, or use event delegation on the container after setting HTML (since `$(el).html()` strips buttons)
+- For the Split day events panel buttons specifically: render event cards as plain HTML (no buttons inside) and add separate DOM-built action buttons, OR navigate via `<a href="...">` links instead of buttons
+
+- [ ] **Step 1: Write `plugins/calendar/admin/views/calendar.js`**
+
+Export `calendarView = { templateUrl: '/plugins/calendar/admin/templates/calendar.html', async onMount($container) { ... } }`.
+
+**`onMount` structure:**
+
+```js
+async onMount($container) {
+    let allEvents = [], allOccurrences = [];
+    let eventsTable = null;
+    let gridMonth = new Date(); gridMonth.setDate(1);
+    let splitSelectedDate = new Date().toISOString().slice(0, 10);
+
+    const BASE = '/api/plugins/calendar';
+
+    function escapeHtml(s) { return String(s ?? '').replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;'); }
+
+    async function loadData() { /* H.get events + occurrences */ }
+
+    // View mode
+    let currentMode = S.get('calendar_view') ?? 'list';
+    function activateMode(mode) {
+        currentMode = mode;
+        S.set('calendar_view', mode);
+        // Hide all view containers
+        ['grid','list','split'].forEach(m => {
+            const el = $container.find(`#view-${m}`).get(0);
+            if (el) el.style.display = m === mode ? '' : 'none';
+        });
+        // Update button styles
+        ['grid','list','split'].forEach(m => {
+            const btn = $container.find(`#btn-view-${m}`).get(0);
+            if (!btn) return;
+            btn.className = `btn btn-sm ${m === mode ? 'btn-primary' : 'btn-outline'}`;
+        });
+        renderCurrentMode();
+    }
+```
+
+**List mode (`renderList`):**
+- Use `T.create()` with columns: title (linked), next occurrence date, type badge, visibility badge, RSVP count, actions (Edit link, Delete button)
+- Type badge colours: `meeting→badge-info`, `interview→badge-warning`, `public-event→badge-success`, `webinar→badge-primary`, `other→badge-secondary`
+- `nextOccurrence(eventId)` helper: finds first occurrence where `eventId` matches, `startAt >= now`, `status === 'active'`, sorted ascending
+- Guard: `if (eventsTable) { eventsTable.setData(filteredEvents); return; }` to avoid duplicate tables
+- Delete via event delegation on `tableEl`: confirm with `E.confirm()`, call `H.delete`, reload data, call `eventsTable.setData()`
+
+**Grid mode (`renderGrid`):**
+- Build 7-column CSS grid HTML string (Monday-first week)
+- Day cells: show date number + up to 3 occurrence badges (type-coloured) + "+N more" if more
+- Use CSS custom properties for theming: `var(--dm-bg)`, `var(--dm-text)`, `var(--dm-primary)`, `var(--dm-border-color)`, `var(--dm-text-muted)`, `var(--dm-bg-subtle)`
+- Highlight today's date with primary colour border/weight
+- After building the HTML string: `$(gridEl).html(html)` - this goes through DOMPurify (no interactive elements in grid cells)
+
+**Split mode (`renderSplit`):**
+- Mini-cal (left): 7-column grid showing month days; clicking a day sets `splitSelectedDate` and calls `renderSplit()`
+- Mini-cal day cells: plain divs with `data-date` attribute; after `$(calEl).html(miniCalHtml)`, attach click listener via `calEl.addEventListener('click', e => { const d = e.target.closest('[data-date]'); if (d) { splitSelectedDate = d.dataset.date; renderSplit(); } })`
+- Day events panel (right): for the selected date, render event cards as `<a>` links (no buttons) pointing to `#/plugins/calendar/events/{eventId}` - avoids DOMPurify stripping buttons
+
+**Filter bar:**
+- `$container.find('#filter-type, #filter-visibility').each(function() { this.addEventListener('change', () => { eventsTable = null; renderCurrentMode(); }); })`
+
+**Month navigation:**
+- Prev/Next buttons adjust `gridMonth` (for Grid) or trigger `renderSplit()` (for Split mini-cal)
+
+**Init sequence:**
+```js
+await loadData();
+// Bind all buttons
+// Activate saved mode
+activateMode(currentMode);
+I.scan();
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add plugins/calendar/admin/views/calendar.js
+git commit -m "feat(calendar): add calendar.js admin view - Grid, List, Split modes"
+```
+
+---
+
+## Task 8: Admin view: `event-editor.js` - create / edit + recurrence panel
+
+**Files:**
+- Create: `plugins/calendar/admin/views/event-editor.js`
+
+Reads `R.current?.params?.id` - if missing or `'new'`, create mode; otherwise edit mode. Jobs-sourced events are shown read-only (all inputs disabled, save button disabled).
+
+- [ ] **Step 1: Write `plugins/calendar/admin/views/event-editor.js`**
+
+Export `eventEditorView = { templateUrl: '/plugins/calendar/admin/templates/event-editor.html', async onMount($container) { ... } }`.
+
+**`onMount` structure:**
+
+```js
+const rawId = R.current?.params?.id;
+const isNew = !rawId || rawId === 'new';
+const id    = isNew ? null : rawId;
+let event   = null;
+let autoSlug = true;
+const BASE  = '/api/plugins/calendar';
+```
+
+**Load for edit:**
+```js
+if (!isNew) {
+    const res = await H.get(`${BASE}/events/${id}`);
+    if (res.error) { E.toast('Failed to load event.', { type: 'error' }); R.navigate('#/plugins/calendar'); return; }
+    event = res.data ?? res;
+}
+```
+
+**Populate fields:**
+```js
+function setField(fieldId, value) {
+    const el = $container.find(`#${fieldId}`).get(0);
+    if (el) el.value = value ?? '';
+}
+```
+Set: title, slug, description, type, visibility, location, start (as `datetime-local` format: `iso.slice(0,16)`), end.
+
+**Read-only for Jobs events:**
+```js
+const isJobsEvent = event?.source === 'jobs';
+if (isJobsEvent) {
+    $container.find('#jobs-notice').get(0).style.display = '';
+    $container.find('#editor-body').get(0)
+        .querySelectorAll('input, select, textarea, button').forEach(el => el.disabled = true);
+}
+```
+
+**Recurrence panel:**
+- `#recurrence-enabled` checkbox toggles `#recurrence-fields` visibility
+- When populated from existing event: set freq, interval, until, byday checkboxes
+- `#field-freq` change → show/hide `#byday-section` (only visible when freq is `weekly`)
+
+**RSVP panel:**
+- `#rsvp-enabled` checkbox toggles `#rsvp-fields` visibility
+
+**Auto-slug:**
+- `#slug-auto` checkbox: when checked, `#field-slug` is `disabled = true` and its value mirrors `slugify($('#field-title').value)` on input events
+- For edit mode with existing slug: set `autoSlug = false`, uncheck `#slug-auto`, leave slug editable
+
+**`collectValues()` helper:**
+```js
+function collectValues() {
+    const recurrenceEnabled = $container.find('#recurrence-enabled').get(0)?.checked;
+    let recurrence = null;
+    if (recurrenceEnabled) {
+        const freq     = $container.find('#field-freq').get(0)?.value ?? 'weekly';
+        const interval = parseInt($container.find('#field-interval').get(0)?.value ?? '1', 10);
+        const until    = $container.find('#field-until').get(0)?.value || null;
+        const byday    = [];
+        $container.find('#byday-checks input').each(function() { if (this.checked) byday.push(this.value); });
+        recurrence = { freq, interval, byday: freq === 'weekly' ? byday : [], until, count: null };
+    }
+    // Convert datetime-local string 'YYYY-MM-DDTHH:mm' to ISO 8601
+    const startRaw = $container.find('#field-start').get(0)?.value ?? '';
+    const endRaw   = $container.find('#field-end').get(0)?.value ?? '';
+    return {
+        title:       $container.find('#field-title').get(0)?.value.trim() ?? '',
+        slug:        $container.find('#field-slug').get(0)?.value.trim() ?? '',
+        description: $container.find('#field-description').get(0)?.value ?? '',
+        type:        $container.find('#field-type').get(0)?.value ?? 'other',
+        visibility:  $container.find('#field-visibility').get(0)?.value ?? 'private',
+        location:    $container.find('#field-location').get(0)?.value.trim() ?? '',
+        startAt:     startRaw ? new Date(startRaw).toISOString() : null,
+        endAt:       endRaw   ? new Date(endRaw).toISOString()   : null,
+        recurrence,
+        rsvpEnabled: $container.find('#rsvp-enabled').get(0)?.checked ?? false,
+        rsvpLimit:   $container.find('#field-rsvp-limit').get(0)?.value
+                        ? parseInt($container.find('#field-rsvp-limit').get(0)?.value, 10) : null
+    };
+}
+```
+
+**`doSave()` async function:**
+- Validate title + startAt + endAt; show `E.toast` on failure and return null
+- `isNew ? H.post(...) : H.put(...)`
+- On success: `E.toast('Event saved.', { type: 'success' })` then `R.navigate('#/plugins/calendar')`
+
+**Button bindings:**
+- `#btn-save`: calls `doSave()`; disabled if `isJobsEvent`
+- `#btn-cancel`: `R.navigate('#/plugins/calendar')`
+
+**End of `onMount`:** `I.scan()`
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add plugins/calendar/admin/views/event-editor.js
+git commit -m "feat(calendar): add event-editor.js - create/edit event with recurrence and RSVP panels"
+```
+
+---
+
+## Task 9: Admin view: `rsvps.js`
+
+**Files:**
+- Create: `plugins/calendar/admin/views/rsvps.js`
+
+- [ ] **Step 1: Write `plugins/calendar/admin/views/rsvps.js`**
+
+Export `rsvpsView = { templateUrl: '/plugins/calendar/admin/templates/rsvps.html', async onMount($container) { ... } }`.
+
+```js
+const BASE = '/api/plugins/calendar';
+function escapeHtml(s) { ... }
+function formatDate(iso) { return iso ? new Date(iso).toLocaleDateString('en-GB', {...}) : '-'; }
+```
+
+**`onMount` structure:**
+```js
+let allRsvps = [], allOccurrences = [];
+let rsvpsTable = null;
+
+async function loadData() {
+    const [rsvpRes, occRes] = await Promise.all([H.get(`${BASE}/rsvps`), H.get(`${BASE}/occurrences`)]);
+    if (rsvpRes.error || occRes.error) { E.toast('Failed to load RSVPs.', { type: 'error' }); return; }
+    allRsvps       = Array.isArray(rsvpRes) ? rsvpRes : (rsvpRes.data ?? []);
+    allOccurrences = Array.isArray(occRes)  ? occRes  : (occRes.data ?? []);
+}
+```
+
+**`buildOccurrenceFilter()`:** Populates `#filter-occurrence` select with upcoming occurrences (sorted by `startAt` ascending), `option value = occ.id`, `textContent = "${occ.title} - ${formatDate(occ.startAt)}"`.
+
+**`filteredRsvps()`:** Reads filter select values, returns filtered `allRsvps`.
+
+**`renderTable()`:**
+- Guard: `if (rsvpsTable) { rsvpsTable.setData(filteredRsvps()); return; }`
+- `T.create()` columns: Name, Email, Event (resolve occurrence title from `allOccurrences`), Status (badge), Registered (date), Actions
+- Actions column: toggle button (Cancel ↔ Confirm) + Delete button
+- Event delegation on `tableEl`: Cancel/Confirm call `H.put(..., { status: ... })`, Delete calls `E.confirm()` then `H.delete`; on success: `await loadData(); rsvpsTable = null; renderTable()`
+
+**Init:**
+```js
+await loadData();
+buildOccurrenceFilter();
+renderTable();
+$container.find('#filter-occurrence, #filter-status').each(function() {
+    this.addEventListener('change', () => { rsvpsTable = null; renderTable(); });
+});
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add plugins/calendar/admin/views/rsvps.js
+git commit -m "feat(calendar): add rsvps.js admin view"
+```
+
+---
+
+## Task 10: Admin view: `settings.js`, enable plugin, smoke test
+
+**Files:**
+- Create: `plugins/calendar/admin/views/settings.js`
+- Modify: `config/plugins.json` (set `enabled: true`)
+
+- [ ] **Step 1: Write `plugins/calendar/admin/views/settings.js`**
+
+Export `settingsView = { templateUrl: '/plugins/calendar/admin/templates/settings.html', async onMount($container) { ... } }`.
+
+```js
+const BASE = '/api/plugins/calendar';
+
+async onMount($container) {
+    let settings = {};
+    try {
+        const res = await H.get(`${BASE}/settings`);
+        if (res.error) throw new Error(res.error);
+        settings = res.data ?? res ?? {};
+    } catch { E.toast('Failed to load settings.', { type: 'error' }); }
+
+    const formEl = $container.find('#settings-form').get(0);
+    if (!formEl) return;
+
+    F.create(formEl, {
+        blueprint: [
+            { key: 'basePath',         label: 'Base path',                   type: 'text',   value: settings.basePath ?? '/calendar',
+              hint: 'URL prefix for all calendar pages. Changes require a server restart.' },
+            { key: 'eventsPerPage',    label: 'Events per page',             type: 'number', value: settings.eventsPerPage ?? 12 },
+            { key: 'rsvpEnabled',      label: 'Enable RSVPs',                type: 'toggle', value: settings.rsvpEnabled ?? true },
+            { key: 'defaultView',      label: 'Default admin view',          type: 'select', value: settings.defaultView ?? 'list',
+              options: ['list','grid','split'] },
+            { key: 'occurrenceWindow', label: 'Occurrence window (days)',     type: 'number', value: settings.occurrenceWindow ?? 365,
+              hint: 'How many days ahead to pre-generate recurring occurrences.' },
+            { key: 'feedLength',       label: 'iCal feed length',            type: 'number', value: settings.feedLength ?? 50 }
+        ],
+        onSubmit: async (values) => {
+            try {
+                const res = await H.put(`${BASE}/settings`, {
+                    basePath:         values.basePath,
+                    eventsPerPage:    parseInt(values.eventsPerPage, 10),
+                    rsvpEnabled:      Boolean(values.rsvpEnabled),
+                    defaultView:      values.defaultView,
+                    occurrenceWindow: parseInt(values.occurrenceWindow, 10),
+                    feedLength:       parseInt(values.feedLength, 10)
+                });
+                if (res.error) throw new Error(res.error);
+                E.toast('Settings saved. Base path changes require a server restart.', { type: 'success' });
+            } catch (err) {
+                E.toast(err?.message ?? 'Failed to save settings.', { type: 'error' });
+            }
+        }
+    });
+}
+```
+
+- [ ] **Step 2: Enable calendar in `config/plugins.json`**
+
+Set `"calendar": { "enabled": true, "bundled": false, "settings": {} }`.
+
+- [ ] **Step 3: Smoke-test API routes with valid token**
+
+Get a token first:
+```bash
+TOKEN=$(curl -s -X POST http://localhost:4096/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"admin@example.com","password":"YOUR_ADMIN_PASSWORD"}' | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
+```
+
+```bash
+# Create a one-off public event
+curl -s -X POST http://localhost:4096/api/plugins/calendar/events \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"title":"Launch Webinar","type":"public-event","visibility":"public","startAt":"2026-06-01T10:00:00.000Z","endAt":"2026-06-01T11:30:00.000Z"}' | grep -o '"id":"[^"]*"'
+```
+Expected: `"id":"<uuid>"`
+
+```bash
+# Verify occurrence was materialised
+curl -s http://localhost:4096/api/plugins/calendar/occurrences \
+  -H "Authorization: Bearer $TOKEN" | grep -o '"title":"Launch Webinar"'
+```
+Expected: `"title":"Launch Webinar"`
+
+- [ ] **Step 4: Smoke-test public routes**
+
+```bash
+curl -s http://localhost:4096/calendar/feed.ics | head -4
+```
+Expected:
+```
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Domma CMS//Calendar//EN
+```
+
+```bash
+curl -s http://localhost:4096/calendar | grep -i 'events\|calendar' | head -3
+```
+
+- [ ] **Step 5: Smoke-test admin panel in browser**
+
+Open `http://192.168.1.4:4096/admin` in browser. Log in as admin.
+
+1. Verify "Calendar" appears in the sidebar
+2. Navigate to Calendar → Events → confirm List view table loads
+3. Toggle Grid view → confirm month calendar renders (days with type-coloured badges)
+4. Toggle Split view → confirm mini calendar + day detail panel render
+5. Click "New Event" → confirm editor opens
+6. Fill in title, type=Public Event, visibility=Public, start + end datetimes → Save → confirm event appears in list
+7. Enable recurrence (weekly, Monday + Wednesday) → save → check that multiple occurrences appear when switching to Grid view
+8. Navigate to Calendar → RSVPs → confirm table loads (may be empty)
+9. Navigate to Calendar → Settings → confirm F.create form renders with all fields
+
+- [ ] **Step 6: Smoke-test RSVP submission**
+
+After creating a public event with `rsvpEnabled: true`:
+```bash
+# Find the occurrence ID (UUID - used as occurrenceId in the RSVP body)
+OCC_RESPONSE=$(curl -s http://localhost:4096/api/plugins/calendar/occurrences \
+  -H "Authorization: Bearer $TOKEN")
+OCC_ID=$(echo "$OCC_RESPONSE" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+echo "Occurrence ID: $OCC_ID"
+
+# Submit RSVP
+curl -s -X POST http://localhost:4096/calendar/rsvp \
+  -H "Content-Type: application/json" \
+  -d "{\"occurrenceId\":\"$OCC_ID\",\"name\":\"Jane Smith\",\"email\":\"jane@example.com\"}" | grep -o '"ok"'
+```
+Expected: `"ok"`
+
+```bash
+# Verify RSVP in admin
+curl -s http://localhost:4096/api/plugins/calendar/rsvps \
+  -H "Authorization: Bearer $TOKEN" | grep -o '"email":"jane@example.com"'
+```
+Expected: `"email":"jane@example.com"`
+
+- [ ] **Step 7: Final commit**
+
+```bash
+git add plugins/calendar/admin/views/settings.js config/plugins.json
+git commit -m "feat(calendar): add settings.js admin view and enable plugin"
+```
+
+---
+
+## Reference: what `setupPlugin` seeds automatically on `onEnable`
+
+When Calendar is enabled via the admin UI, the plugin system calls `setupPlugin` with full services, then calls the plugin's exported `onEnable({ fastify, services })`. Together these seed:
+
+| Asset | Source | Destination |
+|---|---|---|
+| Collection `calendar-events` | `plugins/calendar/collections/calendar-events/schema.json` | `content/collections/calendar-events/` |
+| Collection `calendar-occurrences` | `plugins/calendar/collections/calendar-occurrences/schema.json` | `content/collections/calendar-occurrences/` |
+| Collection `calendar-rsvps` | `plugins/calendar/collections/calendar-rsvps/schema.json` | `content/collections/calendar-rsvps/` |
+| Role `calendar-organiser` | `plugins/calendar/roles/calendar-organiser.json` | `content/collections/roles/data.json` |
+| Role `calendar-admin` | `plugins/calendar/roles/calendar-admin.json` | `content/collections/roles/data.json` |
+| Form `calendar-rsvp` | `plugins/calendar/forms/calendar-rsvp.json` | `content/forms/calendar-rsvp.json` |
+| Page `/calendar` | `plugins/calendar/pages/calendar.md` | `content/pages/calendar.md` |
+| Block `upcoming-events` | `plugins/calendar/blocks/upcoming-events.html` | `content/blocks/upcoming-events.html` |
+| View `calendar-upcoming` | generated in `onEnable` | `content/views/calendar-upcoming.json` |
+| View `calendar-past` | generated in `onEnable` | `content/views/calendar-past.json` |
+| View `calendar-my-events` | generated in `onEnable` | `content/views/calendar-my-events.json` |
+
+`teardownPlugin` removes: page, form, roles. `onDisable` removes: block, views. Collections are never destroyed (data preserved).