domma-cms 1.6.59 → 1.7.0

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

@@ -0,0 +1,538 @@
+# Calendar Plugin - Design Spec
+
+**Date:** 2026-04-07
+**Status:** Approved
+
+---
+
+## Context
+
+Domma CMS ships with a plugin architecture where bundled plugins register their collections, roles, and routes at enable-time. The Calendar plugin is a standalone plugin with two purposes:
+
+1. **Public-facing events calendar** - a public page at `/calendar` with an iCal feed and RSVP registration.
+2. **Composable scheduling service** - exports a `service.js` that other plugins (primarily Jobs) import directly to create and manage calendar occurrences without HTTP round-trips.
+
+It is the first plugin to export a **service layer** (`service.js`) for cross-plugin consumption, establishing a pattern for tight inter-plugin integration without circular HTTP dependencies.
+
+---
+
+## Decisions
+
+| Concern | Decision |
+|---|---|
+| Recurrence storage | Materialised occurrences - pre-generated for a rolling 12-month window |
+| Jobs integration | Jobs imports `service.js` directly - no HTTP round-trip |
+| Public routing | `plugin.public.js` handles `/feed.ics`, `/event/:slug`, `POST /rsvp`; index page is a seeded CMS page |
+| RSVP | Seeded CMS form (`calendar-rsvp`); public event page embeds via `[form slug="calendar-rsvp"]` shortcode |
+| Admin views | Three modes (Grid, List, Split) - all theme-aware, switchable per user via `S.set()` |
+| Roles | Plugin-registered: `calendar-organiser` (level 2), `calendar-admin` (level 1) |
+| iCal feed | Public events only; registered before `/:slug` to avoid parametric shadowing |
+| Interview events | Created by Jobs via `service.js`; shown read-only in Calendar admin |
+| Seeded assets | Page, form, views, block - all seeded on enable, removed on disable via `teardownPlugin` |
+| Shortcode | `[calendar /]` registered on enable - renders upcoming public events; embeddable anywhere |
+
+---
+
+## Seeded Assets
+
+The Calendar plugin seeds the following CMS assets on enable and removes them on disable via `teardownPlugin`. All assets are stored under `plugins/calendar/` and copied into the appropriate `content/` directories by `setupPlugin`.
+
+### Mechanism: `setupPlugin` / `teardownPlugin`
+
+`setupPlugin(pluginName, services)` is called from `server/services/plugins.js:registerPlugins()` on every server startup (idempotent). For Calendar it:
+
+1. Seeds the three collections via `services.collections.createCollection` (existing behaviour - skipped if already present)
+2. Copies `plugins/calendar/forms/calendar-rsvp.json` → `content/forms/calendar-rsvp.json` (skipped if already present)
+3. Copies `plugins/calendar/pages/calendar.md` → `content/pages/calendar.md` (skipped if already present)
+4. Copies `plugins/calendar/blocks/upcoming-events.html` → `content/blocks/upcoming-events.html` (skipped if already present)
+5. Seeds three saved view JSON files into `content/views/` (skipped if already present; format: `{ slug, label, collection, filter, sort }`)
+
+`teardownPlugin(pluginName)` is called when the plugin is disabled. For Calendar it removes:
+- `content/forms/calendar-rsvp.json`
+- `content/pages/calendar.md`
+- `content/blocks/upcoming-events.html`
+- `content/views/calendar-upcoming.json`, `content/views/calendar-past.json`, `content/views/calendar-my-events.json`
+
+Collections are **not** destroyed on disable (data preserved). Roles are not destroyed on disable.
+
+### `[calendar /]` Shortcode Registration
+
+Inside `plugin.js` (the Fastify plugin function), after routes are registered, call:
+
+```js
+options.hooks.registerShortcode('calendar', async (attrs, context) => {
+    const limit = parseInt(attrs.limit ?? settings.eventsPerPage, 10);
+    const type  = attrs.type ?? null;
+    // fetch upcoming public occurrences from calendar-occurrences collection
+    // return HTML string
+});
+```
+
+`options.hooks` is the `hooks` service injected into every plugin via `registerPlugins`. Handler signature:
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `attrs` | `object` | Parsed shortcode attributes (all values are strings) |
+| `context` | `object` | `{ pageUrl, user }` - user may be null for public pages |
+
+The handler must return a `string` (or a `Promise<string>`). It is called server-side at render time.
+
+Shortcode is unregistered (`options.hooks.unregisterShortcode('calendar')`) in the plugin's cleanup path (called by `teardownPlugin`).
+
+### Form: `calendar-rsvp`
+
+File: `plugins/calendar/forms/calendar-rsvp.json`
+
+Seeded into `content/forms/calendar-rsvp.json`. Fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | text | Required |
+| `email` | email | Required |
+| `website` | text | Honeypot - hidden via CSS, never shown to user |
+
+The form's `submitAction` is set to `{basePath}/rsvp` at seed time (i.e. `/calendar/rsvp` with default config). If `basePath` is changed in settings, re-disable then re-enable the plugin to reseed with the new path. The form does not include an `occurrenceId` field - that is injected directly by the `event.html` public template as a hidden `<input>` outside the form shortcode (see Public Routes section). The event detail page renders the RSVP form inline (not via shortcode). The standalone `[form slug="calendar-rsvp"]` embed use-case (placing the form on an arbitrary CMS page) is **out of scope for v1** - the seeded form JSON is present so the CMS forms admin can display its field structure, but the shortcode embed requires manual wiring of `occurrenceId` which is not supported in this version.
+
+### Page: `calendar` (index)
+
+File: `plugins/calendar/pages/calendar.md`
+
+Seeded into `content/pages/calendar.md`. Provides the `/calendar` landing page with frontmatter:
+
+```yaml
+---
+title: Events
+layout: default
+description: Upcoming events
+visibility: public
+---
+[calendar /]
+```
+
+The `[calendar /]` shortcode (registered on enable) renders the paginated public events listing. Sub-routes (`/calendar/event/:slug`, `/calendar/feed.ics`, `/calendar/rsvp`) are handled by `plugin.public.js` directly. The index page is destroyed on disable; sub-routes stop responding.
+
+### Shortcode: `[calendar /]`
+
+Registered via `hooks.registerShortcode('calendar', handler)` on plugin enable. The handler fetches upcoming public occurrences from `calendar-occurrences` (server-side, at render time) and returns an HTML events grid. Supports optional attributes:
+
+| Attribute | Default | Notes |
+|---|---|---|
+| `limit` | `eventsPerPage` config value | Max events to show |
+| `type` | (all) | Filter by event type |
+
+### Views (saved)
+
+Three saved views seeded into `content/views/`. File format:
+
+```json
+{
+  "slug": "calendar-upcoming",
+  "label": "Upcoming Events",
+  "collection": "calendar-occurrences",
+  "filter": { "status": "active" },
+  "sort": { "field": "startAt", "direction": "asc" }
+}
+```
+
+| Slug | Label | Filter | Sort |
+|---|---|---|---|
+| `calendar-upcoming` | Upcoming Events | `{ status: 'active' }` | `startAt asc` |
+| `calendar-past` | Past Events | `{}` | `startAt desc` |
+| `calendar-my-events` | My Events | `{}` | `startAt asc` |
+
+Removed on disable. These are **advisory views for the admin Collections UI** - they are not used by the plugin's own admin panel (which has its own filter bar and query logic). The `calendar-my-events` view has no special `currentUser` token; it is a blank filter that an admin can manually configure. The complex `organiserId` scoping only applies inside `plugin.js` API routes.
+
+### Block: `upcoming-events`
+
+File: `plugins/calendar/blocks/upcoming-events.html`
+
+Seeded into `content/blocks/upcoming-events.html`. Embeddable anywhere via `[block name="upcoming-events"]`. Contains the `[calendar limit="3" /]` shortcode, so it re-uses the same shortcode renderer and always shows live data. Use this block to embed an upcoming events teaser on a homepage or landing page.
+
+---
+
+## Recurrence Model
+
+Recurrence rules are stored as a JSON object on the parent event - simpler than RRULE strings but covers all common patterns:
+
+```json
+{
+  "freq": "weekly",
+  "interval": 1,
+  "byday": ["MO", "WE"],
+  "until": "2026-12-31",
+  "count": null
+}
+```
+
+Supported frequencies: `daily`, `weekly`, `monthly`, `yearly`.
+
+`generateOccurrences(event, windowDays)` materialises individual `calendar-occurrences` entries for the rolling window. Regeneration is triggered:
+- On `createEvent` - generate `occurrenceWindow` days ahead (default 365)
+- On `updateEvent` - delete occurrences where `startAt > Date.now()` at the moment of the update call, then regenerate from today; past occurrences are never modified
+- On `GET /occurrences?eventId=&from=&to=` - if `eventId` is present and the query's `to` date is within 30 days of that event's `windowGeneratedTo`, trigger a top-up for that specific event only. No top-up occurs when `eventId` is absent (list queries spanning multiple events do not trigger materialisation)
+
+**Event deletion:** `DELETE /events/:id` is a **soft cancel** - the parent event and all its occurrences are marked `status: 'cancelled'`; no rows are hard-deleted. Past occurrences and their RSVPs are retained. Only `calendar-admin` may delete events.
+
+---
+
+## Data Model
+
+### Collection: `calendar-events`
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `title` | text | yes | |
+| `slug` | text | yes | URL-safe, unique; auto-derived from title |
+| `description` | markdown | no | Rendered on public event page |
+| `type` | select | yes | `meeting` \| `interview` \| `public-event` \| `webinar` \| `other` |
+| `visibility` | select | yes | `public` \| `private` |
+| `location` | text | no | Physical address or video URL |
+| `organiserId` | text | yes | User ID of creator |
+| `recurrence` | object | no | `{ freq, interval, byday, until, count }` - null = one-off |
+| `windowGeneratedTo` | datetime | no | Tracks materialisation horizon |
+| `rsvpEnabled` | boolean | no | Defaults to plugin config `rsvpEnabled` |
+| `rsvpLimit` | number | no | Capacity cap; null = unlimited |
+| `status` | select | yes | `active` \| `cancelled` |
+
+### Collection: `calendar-occurrences`
+
+One entry per event instance (materialised from recurrence rule, or standalone for Jobs-created interviews).
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `eventId` | text | no | FK to parent event; null for standalone (Jobs-created) occurrences |
+| `title` | text | yes | Defaults to parent title; overridable per-instance |
+| `startAt` | datetime | yes | ISO 8601 UTC string (e.g. `2026-04-25T14:00:00.000Z`) |
+| `endAt` | datetime | yes | ISO 8601 UTC string |
+| `type` | select | yes | Inherited from parent; stored for fast filtering |
+| `visibility` | select | yes | Inherited from parent; stored for fast filtering |
+| `status` | select | yes | `active` \| `cancelled` \| `rescheduled` |
+| `rsvpCount` | number | no | Denormalised; updated on each RSVP |
+| `rsvpLimit` | number | no | Inherited from parent; overridable per-instance |
+| `slug` | text | no | Denormalised from parent event at occurrence creation time; null for Jobs-created standalone occurrences |
+| `source` | text | no | `'calendar'` \| `'jobs'` - identifies the creating plugin |
+
+### Collection: `calendar-rsvps`
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `occurrenceId` | text | yes | FK to occurrence |
+| `name` | text | yes | |
+| `email` | text | yes | |
+| `status` | select | yes | `confirmed` \| `cancelled` |
+| `contactId` | text | no | Populated when Contacts plugin is enabled (upsert on submit) |
+| `createdAt` | datetime | yes | Set server-side |
+
+---
+
+## Service Layer (`service.js`)
+
+### Dependencies
+
+`service.js` is a plain ES module - no Fastify, no HTTP. It imports directly from CMS core services:
+
+```js
+import { createEntry, getEntry, updateEntry, deleteEntry, listEntries } from '../../server/services/collections.js';
+import { getConfig } from '../../server/config.js';
+```
+
+It does **not** receive an options/settings object - it reads config via `getConfig()` at call time.
+
+**Disabled-state guard:** If Calendar is disabled, its collections (`calendar-occurrences`, etc.) will not exist and `createEntry` / `listEntries` will throw a "collection not found" error. Callers (e.g. Jobs) are responsible for checking whether Calendar is enabled before calling service functions. The recommended pattern:
+
+```js
+// In Jobs plugin.js
+const calendarEnabled = options.config?.plugins?.calendar?.enabled ?? false;
+if (calendarEnabled) {
+    const { createOccurrence } = await import('../calendar/service.js');
+    // ...
+}
+```
+
+`service.js` itself does not guard against this - it trusts that callers have verified the plugin state.
+
+### Exported Functions
+
+Exported functions for cross-plugin consumption. Jobs and other plugins import directly:
+
+```js
+import {
+    createEvent,
+    updateEvent,
+    cancelEvent,
+    createOccurrence,
+    getOccurrence,
+    cancelOccurrence,
+    generateOccurrences
+} from '../calendar/service.js';
+```
+
+### Function signatures
+
+| Function | Purpose |
+|---|---|
+| `createEvent(data)` | Create parent event + materialise occurrences for `occurrenceWindow` days |
+| `updateEvent(id, data)` | Update parent + delete/regenerate future occurrences |
+| `cancelEvent(id)` | Mark parent cancelled; cancel all future occurrences |
+| `createOccurrence(data)` | Create standalone occurrence (no parent) - primary Jobs entry point |
+| `getOccurrence(id)` | Fetch single occurrence by ID |
+| `cancelOccurrence(id)` | Cancel a single instance without affecting the series |
+| `generateOccurrences(event, windowDays)` | Internal - materialise occurrences; exposed for admin top-up |
+
+**Jobs integration example:**
+```js
+// In plugins/jobs/plugin.js
+import { createOccurrence, cancelOccurrence } from '../calendar/service.js';
+
+const slot = await createOccurrence({
+    title: `Interview: ${candidate.name}`,
+    type: 'interview',
+    visibility: 'private',
+    startAt: scheduledAt,
+    endAt: endAt,
+    organiserId: recruiterId,
+    source: 'jobs'
+});
+// Store slot.id on the application record
+```
+
+Calendar does not import anything from Jobs - the dependency is one-way.
+
+---
+
+## Plugin Roles
+
+### `calendar-organiser`
+```json
+{
+  "name": "calendar-organiser",
+  "label": "Calendar Organiser",
+  "level": 2,
+  "permissions": ["calendar-events", "calendar-occurrences"],
+  "badgeClass": "badge-info",
+  "resources": [
+    { "key": "calendar-events",      "label": "Calendar Events",      "actions": ["read", "create", "update", "delete"] },
+    { "key": "calendar-occurrences", "label": "Calendar Occurrences", "actions": ["read", "update", "delete"] }
+  ]
+}
+```
+Organisers can create, edit, and delete their own events and occurrences. They cannot modify events owned by others, view RSVPs, or change plugin settings.
+
+### `calendar-admin`
+```json
+{
+  "name": "calendar-admin",
+  "label": "Calendar Admin",
+  "level": 1,
+  "permissions": ["calendar-events", "calendar-occurrences", "calendar-rsvps", "calendar-settings"],
+  "badgeClass": "badge-success",
+  "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"] }
+  ]
+}
+```
+
+---
+
+## API Routes (`plugin.js`)
+
+All under `/api/plugins/calendar`. All routes require `authenticate`.
+
+| Method | Path | Auth | Purpose |
+|---|---|---|---|
+| GET | `/events` | organiser+ | List parent events |
+| POST | `/events` | organiser+ | Create event + materialise occurrences |
+| GET | `/events/:id` | organiser+ | Get event |
+| PUT | `/events/:id` | organiser (own) / admin | Update + regenerate occurrences |
+| DELETE | `/events/:id` | admin | Cancel event + future occurrences |
+| GET | `/occurrences` | organiser+ | List occurrences (`?from=&to=&type=&visibility=&eventId=`) |
+| GET | `/occurrences/:id` | organiser+ | Get single occurrence |
+| PUT | `/occurrences/:id` | organiser (own) / admin | Override title/time for single instance |
+| DELETE | `/occurrences/:id` | organiser (own) / admin | Cancel single instance |
+| GET | `/rsvps` | organiser+ | List RSVPs (`?occurrenceId=&status=`) |
+| PUT | `/rsvps/:id` | organiser+ | Update RSVP status |
+| DELETE | `/rsvps/:id` | organiser+ | Delete RSVP |
+| GET | `/settings` | admin | Get plugin settings |
+| PUT | `/settings` | admin | Save settings to `config/plugins.json` |
+
+**Ownership rule:** `calendar-organiser` users can only update/delete events and occurrences where `organiserId === request.user.id`. Use a named-role bypass list (same pattern as the blog plugin's `PUBLISH_ROLES`):
+
+```js
+const ADMIN_ROLES = ['calendar-admin', 'admin', 'super-admin'];
+// In route handler:
+if (!ADMIN_ROLES.includes(request.user.role) && event.organiserId !== request.user.id) {
+    return reply.code(403).send({ error: 'Forbidden' });
+}
+```
+
+Do NOT use `getRoleLevel()` for this check - `calendar-organiser` is level 2 and a base `user` is also level 2; level comparison would incorrectly allow base users through.
+
+**RSVP visibility:** `GET /rsvps` for a `calendar-organiser` is scoped to occurrences belonging to their own events (`organiserId === request.user.id`). `calendar-admin`, `admin`, and `super-admin` see all RSVPs regardless of ownership.
+
+---
+
+## Public Routes (`plugin.public.js`)
+
+`plugin.public.js` is registered at the Fastify root (before `routes/public.js`) by `server.js`. It receives the same options object as `plugin.js`:
+
+```js
+{ settings, auth: { authenticate, requireAdmin }, config }
+```
+
+`basePath` is resolved inside `plugin.public.js` as `options.settings?.basePath ?? '/calendar'`. All routes are registered under `basePath`. Static routes registered before `/:slug`.
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/` | Public events listing - paginated, published events only |
+| GET | `/feed.ics` | iCal 2.0 feed - public occurrences only, up to `feedLength` - registered first |
+| GET | `/event/:slug` | Individual event page + RSVP form (when `rsvpEnabled`) |
+| POST | `/rsvp` | Submit RSVP - no auth, honeypot protected |
+
+**RSVP submission (`POST /rsvp`):**
+1. Validate required fields (`occurrenceId`, `name`, `email`)
+2. Honeypot check - if `website` field non-empty, silently return 201
+3. Duplicate check - if a `confirmed` RSVP already exists for the same `occurrenceId` + `email`, return 200 (idempotent, no new row created)
+4. Check `rsvpLimit` - if set and `rsvpCount >= rsvpLimit`, return 409
+5. Create `calendar-rsvps` entry with `status: 'confirmed'`, `createdAt: new Date().toISOString()`
+6. Increment `rsvpCount` on the occurrence
+7. If Contacts plugin is enabled: upsert into `contacts-contacts` matching on `email`; write `{ name, email, source: 'calendar' }`; store returned contact ID as `contactId` on the RSVP record
+
+**iCal feed format:** Standard iCalendar 2.0 (`text/calendar`). All datetimes converted from ISO 8601 UTC to iCal format (`YYYYMMDDTHHMMSSZ`). Each public occurrence becomes a `VEVENT` with:
+
+| iCal field | Value |
+|---|---|
+| `UID` | `<occurrenceId>@<siteHostname>` (e.g. `abc123@example.com`) |
+| `DTSTAMP` | Feed generation time in `YYYYMMDDTHHMMSSZ` format (required by RFC 5545) |
+| `DTSTART` | `startAt` converted to `YYYYMMDDTHHMMSSZ` |
+| `DTEND` | `endAt` converted to `YYYYMMDDTHHMMSSZ` |
+| `SUMMARY` | `title` |
+| `DESCRIPTION` | `description` (plain text, newlines as `\n`) |
+| `LOCATION` | `location` (omitted if empty) |
+| `URL` | `<siteUrl>/calendar/event/<slug>` - omitted when `slug` is null (Jobs-created occurrences) |
+
+`siteHostname` and `siteUrl` resolved from `config.site.url` with a fallback to `'localhost'`.
+
+---
+
+## Admin UI
+
+Single "Calendar" sidebar entry with sub-navigation.
+
+### Events list (`#/plugins/calendar`)
+- Three view modes, toggled at top right, persisted via `S.set('calendar_view', mode)`:
+  - **Grid** - month calendar grid; click day to see/create events
+  - **List** - `T.create()` table: title, next occurrence, type badge, visibility badge, RSVP count, edit/delete actions
+  - **Split** - compact month picker left; selected day's occurrences right
+- Filter bar: type select, visibility select, date range
+- "New Event" button → navigates to editor
+
+### Event editor (`#/plugins/calendar/events/new` and `#/plugins/calendar/events/:id`)
+- Two-column layout:
+  - **Main**: title, slug (auto-derive toggle), description (markdown textarea), type, visibility, location, start/end datetime
+  - **Sidebar**: recurrence panel (checkbox to enable; freq/interval/until/byday controls), RSVP panel (enable toggle, capacity input)
+- Jobs-created events (`source: 'jobs'`) are shown read-only with a "Managed by Jobs" label
+
+### RSVPs (`#/plugins/calendar/rsvps`)
+- Filterable by occurrence (select dropdown of upcoming events)
+- Table: name, email, event title, occurrence date, status, created at
+- Per-row: confirm / cancel / delete actions
+
+### Settings (`#/plugins/calendar/settings`)
+- `F.create()` form: `basePath`, `eventsPerPage`, `rsvpEnabled`, `occurrenceWindow`, `feedLength`
+- Banner: "Base path changes require a server restart"
+
+---
+
+## `config.js` Defaults
+
+```js
+export default {
+    basePath:          '/calendar',
+    eventsPerPage:     12,
+    rsvpEnabled:       true,
+    defaultView:       'list',       // 'grid' | 'list' | 'split'
+    occurrenceWindow:  365,          // days ahead to materialise occurrences
+    feedLength:        50,
+    storage: { adapter: 'file' }
+};
+```
+
+---
+
+## Plugin Layout
+
+```
+plugins/calendar/
+  plugin.json
+  plugin.js              API routes
+  plugin.public.js       Public calendar page + iCal feed + RSVP POST
+  service.js             Exported createEvent/createOccurrence etc. for Jobs + other plugins
+  config.js
+  CLAUDE.md
+  roles/
+    calendar-organiser.json
+    calendar-admin.json
+  collections/
+    calendar-events/schema.json
+    calendar-occurrences/schema.json
+    calendar-rsvps/schema.json
+  forms/
+    calendar-rsvp.json   Seeded RSVP form (public event page uses [form slug="calendar-rsvp"])
+  pages/
+    calendar.md          Seeded index page at /calendar; contains [calendar /] shortcode
+  blocks/
+    upcoming-events.html Seeded block; embeddable via [block name="upcoming-events"]
+  templates/
+    index.html           Public events listing body template
+    event.html           Public event detail body template
+  admin/
+    views/
+      calendar.js        Events list (all 3 view modes)
+      event-editor.js    Create/edit event + recurrence
+      rsvps.js           RSVPs list + moderation
+      settings.js
+    templates/
+      calendar.html
+      event-editor.html
+      rsvps.html
+      settings.html
+```
+
+---
+
+## Build Sequence
+
+1. **Collection schemas** - `calendar-events`, `calendar-occurrences`, `calendar-rsvps`
+2. **Role files** - `calendar-organiser.json`, `calendar-admin.json`
+3. **`service.js`** - `createEvent`, `updateEvent`, `cancelEvent`, `createOccurrence`, `getOccurrence`, `cancelOccurrence`, `generateOccurrences`
+4. **`plugin.js`** - API routes (events, occurrences, RSVPs, settings)
+5. **`plugin.public.js`** - public listing, iCal feed, event page, RSVP POST
+6. **Public templates** - `templates/index.html`, `templates/event.html`
+7. **Seeded assets** - `forms/calendar-rsvp.json`, `pages/calendar.md`, `blocks/upcoming-events.html`; registered views defined in `setupPlugin` call (three view JSON files)
+8. **Admin templates** - `calendar.html`, `event-editor.html`, `rsvps.html`, `settings.html`
+9. **Admin views** - `calendar.js` (3 view modes), `event-editor.js`, `rsvps.js`, `settings.js`
+10. **`plugin.json` + `config.js` + `CLAUDE.md`**
+11. **`config/plugins.json`** - add calendar entry (disabled by default)
+
+---
+
+## Verification
+
+- **Fresh install**: enable Calendar → three collections appear in `content/collections/`, two roles in `content/collections/roles/data.json`, `content/pages/calendar.md` exists, `content/forms/calendar-rsvp.json` exists, `content/blocks/upcoming-events.html` exists
+- **Disable plugin**: disable Calendar → page, form, block removed from `content/`; `GET /calendar` returns 404; iCal feed returns 404
+- **Shortcode embed**: add `[calendar limit="3" /]` to any page → renders up to 3 upcoming public events inline
+- **Block embed**: add `[block name="upcoming-events"]` to any page → renders same events via the seeded block
+- **One-off event**: create a public-event → one occurrence in `calendar-occurrences` → `GET /calendar/event/:slug` returns 200
+- **Recurring event**: create weekly event with `until` 4 weeks out → 4 occurrences materialised → all appear in `GET /calendar`
+- **Update recurrence**: change `until` → future occurrences regenerated; past occurrences preserved
+- **iCal feed**: `GET /calendar/feed.ics` returns `text/calendar` with `BEGIN:VCALENDAR` and correct `VEVENT` entries for public occurrences only
+- **RSVP flow**: submit RSVP on public page → entry in `calendar-rsvps` → `rsvpCount` incremented on occurrence → appears in admin RSVPs view
+- **Contacts integration**: submit RSVP with Contacts enabled → contact upserted in `contacts-contacts` with `source: 'calendar'`
+- **Capacity limit**: set `rsvpLimit: 2`, submit 3 RSVPs → third returns 409
+- **Jobs integration**: call `createOccurrence({ source: 'jobs', type: 'interview', ... })` → occurrence created → appears read-only in Calendar admin with "Jobs" label
+- **View modes**: toggle Grid / List / Split → preference persisted across page navigations via `S.set()`
+- **Role gate**: `calendar-organiser` can edit own events; attempting to edit another user's event returns 403; `calendar-admin` can edit any
+- **Private events**: private occurrences do not appear on `GET /calendar` or in `feed.ics`; direct `GET /calendar/event/:slug` for a private event returns 404