domma-cms 1.6.60 → 1.7.0

package/docs/superpowers/plans/2026-06-26-surveys-pro-plugin.md

@@ -0,0 +1,1902 @@
+# Surveys (Pro 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:** Ship a `surveys` Pro plugin that wraps the existing Forms engine with a shared audience, a tokenised invite ledger, editor-triggered sending, a scheduler-ready due-work contract, and per-survey statistics.
+
+**Architecture:** Everything lives under `plugins/surveys/`; nothing in `server/` is modified. The plugin owns four collections (audience contacts, audience groups, campaigns, invite ledger) and reuses core *services* - `collections.js`, `forms.js`/`FormLogicEngine`, `email.js` - rather than core routes. A plugin-owned public submit endpoint validates the invite token, stores the answer via `createEntry`, and flips the ledger; anonymity is intrinsic because the contact↔response link is only ever written to the ledger, never to the response row. Charts and scheduling are deferred upstream behind two stable seams (`renderDistribution`, the `/due-work`+`/run` contract).
+
+**Tech Stack:** Node 20 ESM, Fastify 5, `node:test` + `app.inject`, Domma client (`Domma.forms.render`, `F.create`, `T.create`, `E.*`, `H.*`, `I.*`).
+
+**Spec:** `docs/superpowers/specs/2026-06-26-surveys-pro-plugin-design.md`
+
+---
+
+## Reference patterns (read before starting)
+
+- Plugin entry + collections-service usage: `plugins/contacts/plugin.js`
+- Plugin manifest + admin block: `plugins/contacts/plugin.json`
+- Plugin collection schema: `plugins/contacts/collections/user-contacts/schema.json` (note `"slug"` inside the file is the real slug; the directory name is cosmetic; `setupPlugin` auto-seeds via `createCollection`)
+- Public root routes (SSR): `plugins/blog/plugin.public.js` (mounted by `server/server.js:359` with `{settings, auth:{authenticate,requireAdmin,requireVisibility}, config}`)
+- Collections service API: `createEntry(slug, data, meta)`, `getEntry(slug, id)`, `listEntries(slug, {limit,sort,order}) → {entries}`, `updateEntry(slug, id, data)`, `deleteEntry(slug, id)`; entry shape `{id, data:{}, meta:{createdAt,updatedAt}}`
+- Forms service: `readForm(slug)`, `ensureCollectionForForm(form)` from `server/services/forms.js`
+- Form validation engine: `public/js/form-logic-engine.js` (CJS) - methods `evaluateFieldVisibility(field, values)`, `evaluateFieldRequirement(field, values)`, `validateField(field, value, values) → [{message}]`
+- Email: `createTransport(smtp)`, `sendEmail(transport, {from,fromName,to,subject,html,text})` from `server/services/email.js`; SMTP at `getConfig('site').smtp`
+- Permissions: `registerPluginResource(resource, plugin)` / `unregisterPluginResourcesByPlugin(plugin)` from `server/services/permissionRegistry.js`
+- Test style: `tests/routes/api-tokens.test.js` (`node:test`, build a Fastify app, inject auth, `app.inject`)
+
+**Run tests with:** `npm test` (runs `node --test --test-concurrency=1 'tests/**/*.test.js'`). Single file: `node --test tests/surveys/<file>.test.js`.
+
+**Commit discipline:** commit after every passing step group. Do **not** push (project memory: the user commits/pushes separately - local commits during a feature branch are fine; if unsure, leave staged).
+
+---
+
+## File Structure
+
+```
+plugins/surveys/
+  plugin.json                         manifest + admin (sidebar, routes, views)
+  plugin.js                           authed admin API (mounted /api/plugins/surveys)
+  plugin.public.js                    root public: hosted page, submit, due-work/run
+  config.js                           config defaults (storage adapter, fromName…)
+  CLAUDE.md                           routes, storage, gotchas
+  collections/
+    survey-contacts/schema.json       slug: surveys-contacts
+    survey-groups/schema.json         slug: surveys-groups
+    surveys/schema.json               slug: surveys-surveys (campaigns)
+    survey-invites/schema.json        slug: surveys-invites (ledger)
+  lib/
+    tokens.js                         generate / hash / verify readable codes
+    ledger.js                         invite create + state queries (pure-ish over collections)
+    audience.js                       contact + group helpers, import-from-contacts
+    campaigns.js                      survey CRUD helpers + form binding
+    submit.js                         token→store→ledger flip (reuses core services)
+    sending.js                        invite/reminder batch via email.js
+    stats.js                          aggregation + renderDistribution + CSV/JSON
+  admin/
+    templates/
+      surveys.html                    list view shell
+      survey-editor.html              editor shell
+      audience.html                   contacts/groups shell
+      results.html                    stats shell
+    views/
+      surveys.js                      list (T.create)
+      survey-editor.js                editor (F.create)
+      audience.js                     contacts + groups + import
+      results.js                      health widgets + renderDistribution + export
+  public/
+    survey.mjs                        hosted-page client (Domma.forms.render + token bind)
+    survey.css                        hosted-page styles
+  templates/
+    survey-page.html                  SSR shell for /survey/:slug
+tests/surveys/
+  tokens.test.js  ledger.test.js  audience.test.js  campaigns.test.js
+  submit.test.js  sending.test.js  stats.test.js  due-work.test.js
+```
+
+> **ESM client extension gotcha (project memory):** client modules served to the browser as ES modules must use `.mjs` (package.json stays `commonjs`). Hence `public/survey.mjs`.
+
+---
+
+## Phase 0 - Scaffold
+
+### Task 0.1: Plugin manifest + config + CLAUDE.md
+
+**Files:**
+- Create: `plugins/surveys/plugin.json`
+- Create: `plugins/surveys/config.js`
+- Create: `plugins/surveys/CLAUDE.md`
+
+- [ ] **Step 1: Write `plugin.json`**
+
+```json
+{
+  "name": "surveys",
+  "displayName": "Surveys",
+  "version": "1.0.0",
+  "description": "Targeted surveys over the Forms engine: shared audiences, tokenised invites, reminders, and per-survey statistics.",
+  "author": "Darryl Waterhouse",
+  "date": "2026-06-26",
+  "icon": "clipboard-list",
+  "admin": {
+    "sidebar": [
+      { "id": "surveys", "text": "Surveys", "icon": "clipboard-list", "url": "#/plugins/surveys", "section": "#/plugins/surveys", "permission": "surveys" }
+    ],
+    "routes": [
+      { "path": "/plugins/surveys", "view": "plugin-surveys", "title": "Surveys - Domma CMS" },
+      { "path": "/plugins/surveys/new", "view": "plugin-survey-editor", "title": "New Survey - Domma CMS" },
+      { "path": "/plugins/surveys/edit/:slug", "view": "plugin-survey-editor", "title": "Edit Survey - Domma CMS" },
+      { "path": "/plugins/surveys/audience", "view": "plugin-survey-audience", "title": "Survey Audience - Domma CMS" },
+      { "path": "/plugins/surveys/results/:slug", "view": "plugin-survey-results", "title": "Survey Results - Domma CMS" }
+    ],
+    "views": {
+      "plugin-surveys":        { "entry": "surveys/admin/views/surveys.js",       "exportName": "surveysView" },
+      "plugin-survey-editor":  { "entry": "surveys/admin/views/survey-editor.js",  "exportName": "surveyEditorView" },
+      "plugin-survey-audience":{ "entry": "surveys/admin/views/audience.js",       "exportName": "audienceView" },
+      "plugin-survey-results": { "entry": "surveys/admin/views/results.js",        "exportName": "resultsView" }
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Write `config.js`**
+
+```js
+export default {
+    // Pro: Mongo when config/connections.json exists; degrades to file otherwise.
+    storage: {adapter: 'mongodb', connection: 'default'},
+    // Service token (dcms_...) the external scheduler presents to /due-work + /run.
+    // Empty disables the scheduler endpoints (403). Set in config/plugins.json.
+    schedulerToken: '',
+    fromName: 'Surveys'
+};
+```
+
+- [ ] **Step 3: Write `CLAUDE.md`** documenting: collection slugs (`surveys-contacts`, `surveys-groups`, `surveys-surveys`, `surveys-invites`), the public routes (`/survey/:slug`, `/api/plugins/surveys/submit/:slug`, `/api/plugins/surveys/due-work`, `/api/plugins/surveys/run`), the admin prefix `/api/plugins/surveys`, and gotchas (token hashed not stored; anonymity = link only in ledger; storage degrades to file).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/surveys/plugin.json plugins/surveys/config.js plugins/surveys/CLAUDE.md
+git commit -m "feat(surveys): scaffold plugin manifest, config, and guide"
+```
+
+### Task 0.2: Collection schemas
+
+**Files:**
+- Create: `plugins/surveys/collections/survey-contacts/schema.json`
+- Create: `plugins/surveys/collections/survey-groups/schema.json`
+- Create: `plugins/surveys/collections/surveys/schema.json`
+- Create: `plugins/surveys/collections/survey-invites/schema.json`
+
+- [ ] **Step 1: `survey-contacts/schema.json`**
+
+```json
+{
+  "slug": "surveys-contacts",
+  "title": "Survey Contacts",
+  "description": "Shared survey audience contacts.",
+  "plugin": "surveys",
+  "storage": {"adapter": "mongodb", "connection": "default"},
+  "fields": [
+    {"name": "name",  "label": "Name",  "type": "text",     "required": false},
+    {"name": "email", "label": "Email", "type": "text",     "required": true},
+    {"name": "groups","label": "Groups","type": "text",     "required": false},
+    {"name": "meta",  "label": "Meta",  "type": "textarea", "required": false}
+  ]
+}
+```
+
+- [ ] **Step 2: `survey-groups/schema.json`**
+
+```json
+{
+  "slug": "surveys-groups",
+  "title": "Survey Groups",
+  "description": "Named survey audience groups.",
+  "plugin": "surveys",
+  "storage": {"adapter": "mongodb", "connection": "default"},
+  "fields": [
+    {"name": "name",        "label": "Name",        "type": "text",     "required": true},
+    {"name": "description", "label": "Description", "type": "textarea", "required": false}
+  ]
+}
+```
+
+- [ ] **Step 3: `surveys/schema.json`**
+
+```json
+{
+  "slug": "surveys-surveys",
+  "title": "Surveys",
+  "description": "Survey campaigns.",
+  "plugin": "surveys",
+  "storage": {"adapter": "mongodb", "connection": "default"},
+  "fields": [
+    {"name": "slug",              "label": "Slug",              "type": "text",     "required": true},
+    {"name": "title",             "label": "Title",             "type": "text",     "required": true},
+    {"name": "description",       "label": "Description",       "type": "textarea", "required": false},
+    {"name": "formSlug",          "label": "Form",              "type": "text",     "required": true},
+    {"name": "groupIds",          "label": "Groups",            "type": "text",     "required": false},
+    {"name": "mode",              "label": "Mode",              "type": "text",     "required": true},
+    {"name": "status",            "label": "Status",            "type": "text",     "required": true},
+    {"name": "opensAt",           "label": "Opens At",          "type": "text",     "required": false},
+    {"name": "closesAt",          "label": "Closes At",         "type": "text",     "required": false},
+    {"name": "reminderAfterDays", "label": "Reminder (days)",   "type": "text",     "required": false},
+    {"name": "inviteEmail",       "label": "Invite Email",      "type": "textarea", "required": false}
+  ]
+}
+```
+
+- [ ] **Step 4: `survey-invites/schema.json`**
+
+```json
+{
+  "slug": "surveys-invites",
+  "title": "Survey Invites",
+  "description": "Per-recipient invite ledger (token hashes + status).",
+  "plugin": "surveys",
+  "storage": {"adapter": "mongodb", "connection": "default"},
+  "fields": [
+    {"name": "surveyId",    "label": "Survey",      "type": "text", "required": true},
+    {"name": "contactId",   "label": "Contact",     "type": "text", "required": true},
+    {"name": "tokenHash",   "label": "Token Hash",  "type": "text", "required": true},
+    {"name": "status",      "label": "Status",      "type": "text", "required": true},
+    {"name": "sentAt",      "label": "Sent At",     "type": "text", "required": false},
+    {"name": "completedAt", "label": "Completed At","type": "text", "required": false},
+    {"name": "responseId",  "label": "Response",    "type": "text", "required": false}
+  ]
+}
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/collections
+git commit -m "feat(surveys): collection schemas for contacts, groups, campaigns, invites"
+```
+
+---
+
+## Phase 1 - Tokens (`lib/tokens.js`)
+
+### Task 1.1: Readable token generate / hash / verify
+
+**Files:**
+- Create: `plugins/surveys/lib/tokens.js`
+- Test: `tests/surveys/tokens.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {generateToken, hashToken, formatCode, normaliseCode} from '../../plugins/surveys/lib/tokens.js';
+
+test('generateToken returns a readable code with no ambiguous chars', () => {
+    const t = generateToken();
+    assert.match(t, /^[A-Z0-9]{8}$/);
+    assert.equal(/[O0I1L]/.test(t), false);
+});
+
+test('hashToken is stable and case/format-insensitive via normaliseCode', () => {
+    const t = generateToken();
+    const a = hashToken(normaliseCode(formatCode(t)));
+    const b = hashToken(normaliseCode(t.toLowerCase()));
+    assert.equal(a, b);
+    assert.equal(a.length, 64); // sha-256 hex
+});
+
+test('formatCode groups into XXXX-XXXX, normaliseCode strips it back', () => {
+    assert.equal(formatCode('ABCDEFGH'), 'ABCD-EFGH');
+    assert.equal(normaliseCode('abcd-efgh'), 'ABCDEFGH');
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/tokens.test.js`
+Expected: FAIL - cannot find module `tokens.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+import crypto from 'crypto';
+
+const ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'; // no O,0,I,1,L
+const LENGTH = 8;
+
+/** Generate an 8-char unambiguous uppercase token. */
+export function generateToken() {
+    const bytes = crypto.randomBytes(LENGTH);
+    let out = '';
+    for (let i = 0; i < LENGTH; i++) out += ALPHABET[bytes[i] % ALPHABET.length];
+    return out;
+}
+
+/** SHA-256 hex of a normalised code. The plaintext is never stored. */
+export function hashToken(code) {
+    return crypto.createHash('sha256').update(String(code)).digest('hex');
+}
+
+/** Display form: ABCD-EFGH. */
+export function formatCode(token) {
+    const t = String(token).toUpperCase();
+    return t.length === 8 ? `${t.slice(0, 4)}-${t.slice(4)}` : t;
+}
+
+/** Canonical form for hashing/lookup: strip non-alphanumerics, uppercase. */
+export function normaliseCode(input) {
+    return String(input ?? '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/tokens.test.js`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/tokens.js tests/surveys/tokens.test.js
+git commit -m "feat(surveys): readable invite token generate/hash/normalise"
+```
+
+---
+
+## Phase 2 - Ledger (`lib/ledger.js`)
+
+The ledger wraps the `surveys-invites` collection. Tests inject a fake collections service so they run without disk/Mongo.
+
+### Task 2.1: Create invites for a survey + audience
+
+**Files:**
+- Create: `plugins/surveys/lib/ledger.js`
+- Test: `tests/surveys/ledger.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {createLedger} from '../../plugins/surveys/lib/ledger.js';
+import {normaliseCode} from '../../plugins/surveys/lib/tokens.js';
+
+function fakeCollections() {
+    const rows = [];
+    let n = 0;
+    return {
+        rows,
+        async createEntry(slug, data) { const e = {id: `e${++n}`, data, meta: {}}; rows.push(e); return e; },
+        async listEntries() { return {entries: rows}; },
+        async getEntry(slug, id) { return rows.find(r => r.id === id) ?? null; },
+        async updateEntry(slug, id, data) { const r = rows.find(x => x.id === id); r.data = data; return r; }
+    };
+}
+
+test('issueInvites creates one pending invite per contact with a hashed token', async () => {
+    const col = fakeCollections();
+    const ledger = createLedger(col);
+    const issued = await ledger.issueInvites('survey1', ['c1', 'c2']);
+    assert.equal(issued.length, 2);
+    assert.equal(col.rows.length, 2);
+    assert.equal(col.rows[0].data.status, 'pending');
+    assert.equal(col.rows[0].data.tokenHash.length, 64);
+    // plaintext token is returned to the caller (for the email) but not stored
+    assert.match(issued[0].token, /^[A-Z0-9]{8}$/);
+    assert.equal(col.rows[0].data.token, undefined);
+});
+
+test('issueInvites is idempotent - re-issuing skips existing (survey,contact) pairs', async () => {
+    const col = fakeCollections();
+    const ledger = createLedger(col);
+    await ledger.issueInvites('survey1', ['c1']);
+    const again = await ledger.issueInvites('survey1', ['c1', 'c2']);
+    assert.equal(col.rows.length, 2);          // c1 not duplicated
+    assert.equal(again.length, 1);             // only c2 newly issued
+    assert.equal(again[0].contactId, 'c2');
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/ledger.test.js`
+Expected: FAIL - cannot find module `ledger.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+import {generateToken, hashToken, normaliseCode} from './tokens.js';
+
+const SLUG = 'surveys-invites';
+
+/**
+ * Ledger over the surveys-invites collection.
+ * @param {{createEntry,listEntries,getEntry,updateEntry}} col collections service
+ */
+export function createLedger(col) {
+    async function invitesForSurvey(surveyId) {
+        const {entries} = await col.listEntries(SLUG, {limit: 100000});
+        return entries.filter(e => e.data.surveyId === surveyId);
+    }
+
+    /** Issue pending invites for contacts that don't already have one. Returns [{id, contactId, token}]. */
+    async function issueInvites(surveyId, contactIds) {
+        const existing = await invitesForSurvey(surveyId);
+        const seen = new Set(existing.map(e => e.data.contactId));
+        const out = [];
+        for (const contactId of contactIds) {
+            if (seen.has(contactId)) continue;
+            const token = generateToken();
+            const entry = await col.createEntry(SLUG, {
+                surveyId, contactId,
+                tokenHash: hashToken(normaliseCode(token)),
+                status: 'pending', sentAt: null, completedAt: null, responseId: null
+            }, {source: 'surveys'});
+            out.push({id: entry.id, contactId, token});
+            seen.add(contactId);
+        }
+        return out;
+    }
+
+    /** Find an invite by submitted code (any format). Null if unknown. */
+    async function findByCode(surveyId, code) {
+        const hash = hashToken(normaliseCode(code));
+        const invites = await invitesForSurvey(surveyId);
+        return invites.find(e => e.data.tokenHash === hash) ?? null;
+    }
+
+    /** Mark sent / bounced. */
+    async function markSent(inviteId, ok, nowIso) {
+        const entry = await col.getEntry(SLUG, inviteId);
+        if (!entry) return null;
+        return col.updateEntry(SLUG, inviteId, {
+            ...entry.data,
+            status: ok ? 'sent' : 'bounced',
+            sentAt: ok ? nowIso : entry.data.sentAt
+        });
+    }
+
+    /** Mark completed with the stored response id. */
+    async function markCompleted(inviteId, responseId, nowIso) {
+        const entry = await col.getEntry(SLUG, inviteId);
+        if (!entry) return null;
+        return col.updateEntry(SLUG, inviteId, {
+            ...entry.data, status: 'completed', completedAt: nowIso, responseId: responseId ?? null
+        });
+    }
+
+    return {invitesForSurvey, issueInvites, findByCode, markSent, markCompleted};
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/ledger.test.js`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/ledger.js tests/surveys/ledger.test.js
+git commit -m "feat(surveys): invite ledger - idempotent issue + status transitions"
+```
+
+### Task 2.2: Outstanding + due-for-reminder queries
+
+**Files:**
+- Modify: `plugins/surveys/lib/ledger.js`
+- Test: `tests/surveys/ledger.test.js`
+
+- [ ] **Step 1: Add failing tests**
+
+```js
+test('outstanding excludes completed and bounced', async () => {
+    const col = fakeCollections();
+    const ledger = createLedger(col);
+    const [i1, i2] = await ledger.issueInvites('s', ['c1', 'c2']);
+    await ledger.markCompleted(i1.id, 'r1', '2026-06-26T00:00:00Z');
+    const out = await ledger.outstanding('s');
+    assert.deepEqual(out.map(e => e.data.contactId), ['c2']);
+});
+
+test('dueForReminder = sent, not completed, sentAt older than N days', async () => {
+    const col = fakeCollections();
+    const ledger = createLedger(col);
+    const [i1] = await ledger.issueInvites('s', ['c1']);
+    await ledger.markSent(i1.id, true, '2026-06-01T00:00:00Z');
+    const due = await ledger.dueForReminder('s', 7, new Date('2026-06-26T00:00:00Z'));
+    assert.equal(due.length, 1);
+    const notDue = await ledger.dueForReminder('s', 7, new Date('2026-06-03T00:00:00Z'));
+    assert.equal(notDue.length, 0);
+});
+```
+
+- [ ] **Step 2: Run to verify fail**
+
+Run: `node --test tests/surveys/ledger.test.js`
+Expected: FAIL - `ledger.outstanding is not a function`.
+
+- [ ] **Step 3: Implement (add inside `createLedger`, include in the returned object)**
+
+```js
+    async function outstanding(surveyId) {
+        const invites = await invitesForSurvey(surveyId);
+        return invites.filter(e => e.data.status !== 'completed' && e.data.status !== 'bounced');
+    }
+
+    async function dueForReminder(surveyId, afterDays, now) {
+        const cutoff = now.getTime() - Number(afterDays) * 86400000;
+        const invites = await invitesForSurvey(surveyId);
+        return invites.filter(e =>
+            e.data.status === 'sent' &&
+            e.data.sentAt && new Date(e.data.sentAt).getTime() <= cutoff
+        );
+    }
+```
+
+Add `outstanding, dueForReminder` to the `return {...}`.
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/ledger.test.js`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/ledger.js tests/surveys/ledger.test.js
+git commit -m "feat(surveys): ledger outstanding + due-for-reminder queries"
+```
+
+---
+
+## Phase 3 - Submit pipeline (`lib/submit.js`)
+
+The heart of the feature. Reuses core services; the contact↔response link is written only to the ledger.
+
+### Task 3.1: `processSurveySubmission`
+
+**Files:**
+- Create: `plugins/surveys/lib/submit.js`
+- Test: `tests/surveys/submit.test.js`
+
+- [ ] **Step 1: Write the failing test** (inject all collaborators - no disk, no SMTP)
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {processSurveySubmission} from '../../plugins/surveys/lib/submit.js';
+import {createLedger} from '../../plugins/surveys/lib/ledger.js';
+import {generateToken, hashToken, normaliseCode} from '../../plugins/surveys/lib/tokens.js';
+
+function harness() {
+    const rows = [];
+    let n = 0;
+    const col = {
+        rows,
+        async createEntry(slug, data) { const e = {id: `${slug}-${++n}`, data, meta: {}}; rows.push({slug, ...e}); return e; },
+        async listEntries() { return {entries: rows.filter(r => r.slug === 'surveys-invites')}; },
+        async getEntry(slug, id) { return rows.find(r => r.id === id) ?? null; },
+        async updateEntry(slug, id, data) { const r = rows.find(x => x.id === id); r.data = data; return r; }
+    };
+    const survey = {id: 'sv1', data: {slug: 'sat', formSlug: 'sat-form', mode: 'identified', status: 'open'}};
+    const form = {slug: 'sat-form', title: 'Satisfaction', fields: [{name: 'q1', label: 'Q1', type: 'text', required: true}], actions: {}};
+    const deps = {
+        col,
+        ledger: createLedger(col),
+        getSurveyBySlug: async () => survey,
+        readForm: async () => form,
+        getCollection: async () => ({slug: 'sat-form'}),
+        sendCompletionEmail: async () => {},
+        now: () => '2026-06-26T00:00:00Z'
+    };
+    return {col, survey, form, deps};
+}
+
+test('valid token + identified mode stores answer and links only on the ledger', async () => {
+    const {col, deps} = harness();
+    const [invite] = await deps.ledger.issueInvites('sv1', ['c1']);
+    const res = await processSurveySubmission('sat', invite.token, {q1: 'Great'}, deps);
+    assert.equal(res.ok, true);
+    const response = col.rows.find(r => r.slug === 'sat-form');
+    assert.equal(response.data.q1, 'Great');
+    assert.equal(response.data.contactId, undefined);        // never on the response
+    assert.equal(response.data.survey_token, undefined);     // token never persisted
+    const led = col.rows.find(r => r.slug === 'surveys-invites');
+    assert.equal(led.data.status, 'completed');
+    assert.equal(led.data.responseId, response.id);          // link lives on the ledger
+});
+
+test('anonymous mode flips the ledger but stores no contactId anywhere', async () => {
+    const {col, deps} = harness();
+    deps.getSurveyBySlug = async () => ({id: 'sv1', data: {slug: 'sat', formSlug: 'sat-form', mode: 'anonymous', status: 'open'}});
+    const [invite] = await deps.ledger.issueInvites('sv1', ['c1']);
+    await processSurveySubmission('sat', invite.token, {q1: 'Fine'}, deps);
+    const led = col.rows.find(r => r.slug === 'surveys-invites');
+    assert.equal(led.data.status, 'completed');
+    assert.equal(led.data.responseId, null);                 // anonymous: not even on the ledger
+});
+
+test('unknown token is rejected', async () => {
+    const {deps} = harness();
+    await deps.ledger.issueInvites('sv1', ['c1']);
+    await assert.rejects(() => processSurveySubmission('sat', 'WRONGCOD', {q1: 'x'}, deps), /invalid/i);
+});
+
+test('already-completed token is rejected', async () => {
+    const {deps} = harness();
+    const [invite] = await deps.ledger.issueInvites('sv1', ['c1']);
+    await processSurveySubmission('sat', invite.token, {q1: 'a'}, deps);
+    await assert.rejects(() => processSurveySubmission('sat', invite.token, {q1: 'b'}, deps), /already/i);
+});
+
+test('closed survey is rejected', async () => {
+    const {deps} = harness();
+    deps.getSurveyBySlug = async () => ({id: 'sv1', data: {slug: 'sat', formSlug: 'sat-form', mode: 'identified', status: 'closed'}});
+    const [invite] = await deps.ledger.issueInvites('sv1', ['c1']);
+    await assert.rejects(() => processSurveySubmission('sat', invite.token, {q1: 'a'}, deps), /closed/i);
+});
+
+test('required-field validation rejects empty answers', async () => {
+    const {deps} = harness();
+    const [invite] = await deps.ledger.issueInvites('sv1', ['c1']);
+    await assert.rejects(() => processSurveySubmission('sat', invite.token, {q1: ''}, deps), /required/i);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/submit.test.js`
+Expected: FAIL - cannot find module `submit.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+import {createRequire} from 'module';
+
+const require = createRequire(import.meta.url);
+const FormLogicEngine = require('../../../public/js/form-logic-engine.js');
+
+class SurveyError extends Error {
+    constructor(message, code = 400) { super(message); this.statusCode = code; }
+}
+
+function withinWindow(data, now) {
+    const t = new Date(now).getTime();
+    if (data.opensAt && t < new Date(data.opensAt).getTime()) return false;
+    if (data.closesAt && t > new Date(data.closesAt).getTime()) return false;
+    return true;
+}
+
+/** Validate visible fields with the same engine core uses. Throws SurveyError. */
+function validate(form, body) {
+    const values = {};
+    for (const f of form.fields || []) {
+        if (['page-break', 'spacer'].includes(f.type)) continue;
+        const v = body[f.name];
+        values[f.name] = typeof v === 'string' ? v.trim() : (v ?? '');
+    }
+    const missing = [];
+    const errors = [];
+    for (const f of form.fields || []) {
+        if (['page-break', 'spacer'].includes(f.type)) continue;
+        if (FormLogicEngine.evaluateFieldVisibility(f, values) === 'hidden') continue;
+        const val = values[f.name];
+        const empty = !val?.toString().trim();
+        if (FormLogicEngine.evaluateFieldRequirement(f, values) && empty) missing.push(f.label || f.name);
+        else if (!empty) {
+            const e = FormLogicEngine.validateField(f, val, values);
+            if (e.length) errors.push(e[0].message);
+        }
+    }
+    if (missing.length || errors.length) {
+        const parts = [];
+        if (missing.length) parts.push(`Required fields missing: ${missing.join(', ')}`);
+        if (errors.length) parts.push(errors.join('; '));
+        throw new SurveyError(`${parts.join('. ')}.`);
+    }
+    return values;
+}
+
+/**
+ * Process a tokenised survey submission.
+ * @param {string} surveySlug
+ * @param {string} code submitted invite code (any format)
+ * @param {object} body answer values keyed by field name
+ * @param {object} deps {col, ledger, getSurveyBySlug, readForm, getCollection, sendCompletionEmail, now}
+ * @returns {Promise<{ok:true, message:string}>}
+ */
+export async function processSurveySubmission(surveySlug, code, body, deps) {
+    const {col, ledger, getSurveyBySlug, readForm, getCollection, sendCompletionEmail, now} = deps;
+
+    const survey = await getSurveyBySlug(surveySlug);
+    if (!survey) throw new SurveyError('Survey not found.', 404);
+    const s = survey.data;
+    if (s.status !== 'open') throw new SurveyError('This survey has closed.', 410);
+    if (!withinWindow(s, now())) throw new SurveyError('This survey has closed.', 410);
+
+    const invite = await ledger.findByCode(survey.id, code);
+    if (!invite) throw new SurveyError('That code is invalid for this survey.', 403);
+    if (invite.data.status === 'completed') throw new SurveyError('This survey has already been completed for that code.', 409);
+
+    const form = await readForm(s.formSlug);
+    const values = validate(form, body);
+
+    // Store the answer in the form's own submission collection.
+    const targetSlug = s.formSlug;
+    const col0 = await getCollection(targetSlug);
+    if (!col0) throw new SurveyError('Survey form is not configured correctly.', 500);
+    const data = {};
+    for (const f of form.fields || []) {
+        if (['page-break', 'spacer'].includes(f.type)) continue;
+        if (values[f.name] !== undefined) data[f.name] = values[f.name];
+    }
+    // NOTE: contactId / token are deliberately NOT written here - anonymity is intrinsic.
+    const entry = await col.createEntry(targetSlug, data, {source: `survey:${surveySlug}`});
+
+    // Flip the ledger. Identified mode keeps the response link; anonymous discards it.
+    const responseId = s.mode === 'identified' ? entry.id : null;
+    await ledger.markCompleted(invite.id, responseId, now());
+
+    // Completion notification reuses the form's own email action.
+    await sendCompletionEmail(form, data).catch(() => {});
+
+    return {ok: true, message: form.settings?.successMessage || 'Thank you - your response has been recorded.'};
+}
+
+export {SurveyError};
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/submit.test.js`
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/submit.js tests/surveys/submit.test.js
+git commit -m "feat(surveys): tokenised submit pipeline with intrinsic anonymity"
+```
+
+---
+
+## Phase 4 - Audience & campaign helpers
+
+### Task 4.1: Audience helpers (`lib/audience.js`)
+
+**Files:**
+- Create: `plugins/surveys/lib/audience.js`
+- Test: `tests/surveys/audience.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {createAudience} from '../../plugins/surveys/lib/audience.js';
+
+function fakeCol(seed = []) {
+    const rows = seed.map((d, i) => ({slug: d._slug, id: d.id ?? `r${i}`, data: d, meta: {}}));
+    let n = rows.length;
+    return {
+        rows,
+        async listEntries(slug) { return {entries: rows.filter(r => r.slug === slug)}; },
+        async createEntry(slug, data) { const e = {slug, id: `r${++n}`, data, meta: {}}; rows.push(e); return e; },
+        async getEntry(slug, id) { return rows.find(r => r.id === id) ?? null; }
+    };
+}
+
+test('contactIdsForGroups returns contacts whose groups intersect the requested groups', async () => {
+    const col = fakeCol([
+        {_slug: 'surveys-contacts', id: 'a', email: 'a@x', groups: ['staff']},
+        {_slug: 'surveys-contacts', id: 'b', email: 'b@x', groups: ['vips']},
+        {_slug: 'surveys-contacts', id: 'c', email: 'c@x', groups: ['staff', 'vips']}
+    ]);
+    const aud = createAudience(col);
+    const ids = await aud.contactIdsForGroups(['vips']);
+    assert.deepEqual(ids.sort(), ['b', 'c']);
+});
+
+test('importFromContacts copies name/email/groups and skips entries without email', async () => {
+    const col = fakeCol();
+    const aud = createAudience(col);
+    const source = [{name: 'Jo', email: 'jo@x', groups: ['team']}, {name: 'NoEmail'}];
+    const {imported} = await aud.importFromContacts(source);
+    assert.equal(imported, 1);
+    const stored = col.rows.filter(r => r.slug === 'surveys-contacts');
+    assert.equal(stored[0].data.email, 'jo@x');
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/audience.test.js`
+Expected: FAIL - cannot find module `audience.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+const C = 'surveys-contacts';
+
+function parseGroups(raw) {
+    if (Array.isArray(raw)) return raw;
+    if (typeof raw === 'string') { try { return JSON.parse(raw); } catch { return raw ? [raw] : []; } }
+    return [];
+}
+
+export function createAudience(col) {
+    async function listContacts() {
+        const {entries} = await col.listEntries(C, {limit: 100000});
+        return entries.map(e => ({id: e.id, name: e.data.name ?? '', email: e.data.email ?? '', groups: parseGroups(e.data.groups)}));
+    }
+
+    async function contactIdsForGroups(groupNames) {
+        const want = new Set(groupNames);
+        const contacts = await listContacts();
+        return contacts.filter(c => c.groups.some(g => want.has(g))).map(c => c.id);
+    }
+
+    async function importFromContacts(sourceContacts) {
+        let imported = 0;
+        for (const c of sourceContacts) {
+            const email = (c.email ?? '').trim();
+            if (!email) continue;
+            await col.createEntry(C, {
+                name: (c.name ?? '').trim(),
+                email,
+                groups: parseGroups(c.groups)
+            }, {source: 'import-contacts'});
+            imported++;
+        }
+        return {imported};
+    }
+
+    return {listContacts, contactIdsForGroups, importFromContacts};
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/audience.test.js`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/audience.js tests/surveys/audience.test.js
+git commit -m "feat(surveys): audience helpers - group resolution + contacts import"
+```
+
+### Task 4.2: Campaign helpers (`lib/campaigns.js`)
+
+**Files:**
+- Create: `plugins/surveys/lib/campaigns.js`
+- Test: `tests/surveys/campaigns.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {createCampaigns} from '../../plugins/surveys/lib/campaigns.js';
+
+function fakeCol() {
+    const rows = [];
+    let n = 0;
+    return {
+        rows,
+        async listEntries() { return {entries: rows}; },
+        async createEntry(slug, data) { const e = {id: `s${++n}`, data, meta: {}}; rows.push(e); return e; },
+        async getEntry(slug, id) { return rows.find(r => r.id === id) ?? null; },
+        async updateEntry(slug, id, data) { const r = rows.find(x => x.id === id); r.data = data; return r; }
+    };
+}
+
+test('createSurvey normalises mode/status and rejects a duplicate slug', async () => {
+    const c = createCampaigns(fakeCol());
+    const s = await c.createSurvey({slug: 'sat', title: 'Sat', formSlug: 'f'});
+    assert.equal(s.data.mode, 'identified');
+    assert.equal(s.data.status, 'draft');
+    await assert.rejects(() => c.createSurvey({slug: 'sat', title: 'Dup', formSlug: 'f'}), /exists/i);
+});
+
+test('getBySlug finds a survey by its data.slug', async () => {
+    const c = createCampaigns(fakeCol());
+    await c.createSurvey({slug: 'sat', title: 'Sat', formSlug: 'f', mode: 'anonymous'});
+    const found = await c.getBySlug('sat');
+    assert.equal(found.data.mode, 'anonymous');
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/campaigns.test.js`
+Expected: FAIL - cannot find module `campaigns.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+const S = 'surveys-surveys';
+const MODES = new Set(['identified', 'anonymous']);
+const STATUSES = new Set(['draft', 'open', 'closed']);
+
+export function createCampaigns(col) {
+    async function all() { const {entries} = await col.listEntries(S, {limit: 100000}); return entries; }
+    async function getBySlug(slug) { return (await all()).find(e => e.data.slug === slug) ?? null; }
+
+    async function createSurvey(input) {
+        if (!input.slug || !input.title || !input.formSlug) throw new Error('slug, title and formSlug are required');
+        if (await getBySlug(input.slug)) throw new Error(`A survey with slug "${input.slug}" already exists`);
+        return col.createEntry(S, {
+            slug: input.slug,
+            title: input.title,
+            description: input.description ?? '',
+            formSlug: input.formSlug,
+            groupIds: Array.isArray(input.groupIds) ? input.groupIds : [],
+            mode: MODES.has(input.mode) ? input.mode : 'identified',
+            status: STATUSES.has(input.status) ? input.status : 'draft',
+            opensAt: input.opensAt ?? null,
+            closesAt: input.closesAt ?? null,
+            reminderAfterDays: Number(input.reminderAfterDays) || 7,
+            inviteEmail: input.inviteEmail ?? {subject: '', body: ''}
+        }, {source: 'admin'});
+    }
+
+    async function updateSurvey(id, patch) {
+        const entry = await col.getEntry(S, id);
+        if (!entry) throw new Error('Survey not found');
+        const merged = {...entry.data};
+        for (const k of ['title', 'description', 'formSlug', 'groupIds', 'opensAt', 'closesAt', 'reminderAfterDays', 'inviteEmail']) {
+            if (k in patch) merged[k] = patch[k];
+        }
+        if (patch.mode && MODES.has(patch.mode)) merged.mode = patch.mode;
+        if (patch.status && STATUSES.has(patch.status)) merged.status = patch.status;
+        return col.updateEntry(S, id, merged);
+    }
+
+    return {all, getBySlug, createSurvey, updateSurvey};
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/campaigns.test.js`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/campaigns.js tests/surveys/campaigns.test.js
+git commit -m "feat(surveys): campaign helpers - create/update/getBySlug with validation"
+```
+
+---
+
+## Phase 5 - Sending (`lib/sending.js`)
+
+### Task 5.1: Build invite emails + batch send
+
+**Files:**
+- Create: `plugins/surveys/lib/sending.js`
+- Test: `tests/surveys/sending.test.js`
+
+- [ ] **Step 1: Write the failing test** (inject a fake transport + ledger)
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {renderInvite, sendBatch} from '../../plugins/surveys/lib/sending.js';
+
+test('renderInvite substitutes {{name}} and {{link}}', () => {
+    const out = renderInvite({subject: 'Survey for {{name}}', body: 'Go: {{link}}'}, {name: 'Jo'}, 'https://x/survey/sat?t=ABCD-EFGH');
+    assert.equal(out.subject, 'Survey for Jo');
+    assert.match(out.html, /https:\/\/x\/survey\/sat\?t=ABCD-EFGH/);
+});
+
+test('sendBatch emails each recipient and reports per-recipient outcome', async () => {
+    const sent = [];
+    const fakeTransport = {};
+    const deps = {
+        sendEmail: async (_t, msg) => { if (msg.to === 'bad@x') throw new Error('bounce'); sent.push(msg.to); },
+        transport: fakeTransport, from: 'noreply@x', fromName: 'Surveys',
+        baseUrl: 'https://x', surveySlug: 'sat'
+    };
+    const recipients = [
+        {invite: {id: 'i1'}, contact: {name: 'A', email: 'a@x'}, token: 'AAAAAAAA'},
+        {invite: {id: 'i2'}, contact: {name: 'B', email: 'bad@x'}, token: 'BBBBBBBB'}
+    ];
+    const results = await sendBatch(recipients, {subject: 'Hi {{name}}', body: '{{link}}'}, deps);
+    assert.deepEqual(sent, ['a@x']);
+    assert.deepEqual(results.map(r => [r.inviteId, r.ok]), [['i1', true], ['i2', false]]);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/sending.test.js`
+Expected: FAIL - cannot find module `sending.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+import {formatCode} from './tokens.js';
+
+function escapeHtml(s) {
+    return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Render one invite's subject + html from a template and a substitution context. */
+export function renderInvite(template, contact, link) {
+    const sub = (str) => String(str ?? '')
+        .replaceAll('{{name}}', contact.name || 'there')
+        .replaceAll('{{link}}', link);
+    const subject = sub(template.subject || 'You are invited to a survey');
+    const bodyText = sub(template.body || 'Please take our survey: {{link}}');
+    const html = `<p>${escapeHtml(bodyText).replace(/\n/g, '<br>')}</p>`;
+    return {subject, text: bodyText, html};
+}
+
+/**
+ * Send to each recipient; never fails wholesale. Returns [{inviteId, ok}].
+ * @param {Array<{invite,contact,token}>} recipients
+ * @param {{subject,body}} template
+ * @param {object} deps {sendEmail, transport, from, fromName, baseUrl, surveySlug}
+ */
+export async function sendBatch(recipients, template, deps) {
+    const {sendEmail, transport, from, fromName, baseUrl, surveySlug} = deps;
+    const results = [];
+    for (const r of recipients) {
+        const link = `${baseUrl}/survey/${surveySlug}?t=${formatCode(r.token)}`;
+        const msg = renderInvite(template, r.contact, link);
+        try {
+            await sendEmail(transport, {from, fromName, to: r.contact.email, subject: msg.subject, html: msg.html, text: msg.text});
+            results.push({inviteId: r.invite.id, ok: true});
+        } catch {
+            results.push({inviteId: r.invite.id, ok: false});
+        }
+    }
+    return results;
+}
+```
+
+> **Reminder tokens:** reminders reuse the *original* invite token (it is regenerable only at issue time; the plaintext is not stored). The send flow therefore re-issues a token only for brand-new invites; reminders to already-`sent` invites must carry a token the recipient already holds. **Decision:** reminder emails link to `/survey/<slug>` **without** `?t=` and instruct the recipient to use the code from their first email (the manual-entry box accepts it). This avoids storing plaintext tokens. Document this in `CLAUDE.md`.
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/sending.test.js`
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/sending.js tests/surveys/sending.test.js
+git commit -m "feat(surveys): invite rendering + non-fatal batch send"
+```
+
+---
+
+## Phase 6 - Stats (`lib/stats.js`)
+
+### Task 6.1: Aggregation + renderDistribution + export
+
+**Files:**
+- Create: `plugins/surveys/lib/stats.js`
+- Test: `tests/surveys/stats.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import {aggregateField, renderDistribution, toCsv, campaignHealth} from '../../plugins/surveys/lib/stats.js';
+
+test('aggregateField counts choice distribution with percentages', () => {
+    const field = {name: 'colour', label: 'Colour', type: 'select'};
+    const rows = [{colour: 'red'}, {colour: 'red'}, {colour: 'blue'}];
+    const dist = aggregateField(field, rows);
+    const red = dist.items.find(i => i.label === 'red');
+    assert.equal(red.value, 2);
+    assert.equal(red.pct, 67); // rounded
+});
+
+test('aggregateField on rating returns an average', () => {
+    const field = {name: 'score', label: 'Score', type: 'rating'};
+    const rows = [{score: '4'}, {score: '2'}];
+    const dist = aggregateField(field, rows);
+    assert.equal(dist.average, 3);
+});
+
+test('renderDistribution emits one bar per item with width set from pct', () => {
+    const html = renderDistribution([{label: 'red', value: 2, pct: 67}]);
+    assert.match(html, /67%/);
+    assert.match(html, /red/);
+});
+
+test('campaignHealth computes response rate', () => {
+    const invites = [{data: {status: 'completed'}}, {data: {status: 'sent'}}, {data: {status: 'pending'}}];
+    const h = campaignHealth(invites);
+    assert.equal(h.invited, 3);
+    assert.equal(h.completed, 1);
+    assert.equal(h.responseRate, 33);
+});
+
+test('toCsv escapes commas and quotes', () => {
+    const csv = toCsv([{a: 'x,y', b: 'he said "hi"'}], ['a', 'b']);
+    assert.match(csv.split('\n')[1], /"x,y","he said ""hi"""/);
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/stats.test.js`
+Expected: FAIL - cannot find module `stats.js`.
+
+- [ ] **Step 3: Implement**
+
+```js
+const CHOICE = new Set(['select', 'radio', 'checkbox', 'dropdown']);
+const RATING = new Set(['rating', 'number', 'range']);
+
+/** Aggregate one field across response rows into a normalised distribution. */
+export function aggregateField(field, rows) {
+    const label = field.label || field.name;
+    if (RATING.has(field.type)) {
+        const nums = rows.map(r => Number(r[field.name])).filter(n => !Number.isNaN(n));
+        const average = nums.length ? Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 100) / 100 : 0;
+        const counts = tally(rows.map(r => String(r[field.name] ?? '')).filter(Boolean));
+        return {field: field.name, label, type: 'rating', average, items: toItems(counts)};
+    }
+    if (CHOICE.has(field.type)) {
+        const counts = tally(rows.flatMap(r => Array.isArray(r[field.name]) ? r[field.name] : [r[field.name]]).filter(Boolean));
+        return {field: field.name, label, type: 'choice', items: toItems(counts)};
+    }
+    // free text - list, do not chart
+    return {field: field.name, label, type: 'text', responses: rows.map(r => r[field.name]).filter(Boolean)};
+}
+
+function tally(values) {
+    const m = new Map();
+    for (const v of values) m.set(v, (m.get(v) || 0) + 1);
+    return m;
+}
+
+function toItems(counts) {
+    const total = [...counts.values()].reduce((a, b) => a + b, 0) || 1;
+    return [...counts.entries()].map(([k, v]) => ({label: String(k), value: v, pct: Math.round((v / total) * 100)}));
+}
+
+/**
+ * THE CHARTS SEAM. Input shape [{label,value,pct}] is the exact contract a
+ * future Domma.charts() call will accept. Swap this body for Domma.charts(...)
+ * when the framework component lands. See domma-charts-upstream-proposal.md.
+ */
+export function renderDistribution(items) {
+    return `<div class="survey-dist">` + items.map(i =>
+        `<div class="survey-dist-row"><span class="survey-dist-label">${escapeHtml(i.label)}</span>` +
+        `<span class="survey-dist-bar"><span class="survey-dist-fill" style="width:${i.pct}%"></span></span>` +
+        `<span class="survey-dist-val">${i.value} (${i.pct}%)</span></div>`
+    ).join('') + `</div>`;
+}
+
+export function campaignHealth(invites) {
+    const invited = invites.length;
+    const completed = invites.filter(i => i.data.status === 'completed').length;
+    return {invited, completed, responseRate: invited ? Math.round((completed / invited) * 100) : 0};
+}
+
+export function toCsv(rows, columns) {
+    const esc = (v) => {
+        const s = String(v ?? '');
+        return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+    };
+    const head = columns.join(',');
+    const body = rows.map(r => columns.map(c => esc(r[c])).join(',')).join('\n');
+    return `${head}\n${body}`;
+}
+
+function escapeHtml(s) {
+    return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/stats.test.js`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/lib/stats.js tests/surveys/stats.test.js
+git commit -m "feat(surveys): stats aggregation, renderDistribution seam, CSV export"
+```
+
+---
+
+## Phase 7 - Admin API (`plugin.js`)
+
+`plugin.js` is mounted at `/api/plugins/surveys` with `options.auth.authenticate`. It wires the lib modules to real core services and exposes authed CRUD + actions.
+
+### Task 7.1: Wire core services + survey/audience CRUD
+
+**Files:**
+- Create: `plugins/surveys/plugin.js`
+- Test: `tests/surveys/plugin-admin.test.js`
+
+- [ ] **Step 1: Write the failing integration test** (real collections service, seeded; mirrors `tests/routes/api-tokens.test.js`)
+
+```js
+import {before, test} from 'node:test';
+import assert from 'node:assert/strict';
+import Fastify from 'fastify';
+import fastifyJwt from '@fastify/jwt';
+import surveysPlugin from '../../plugins/surveys/plugin.js';
+import {createCollection, getCollection} from '../../server/services/collections.js';
+
+before(async () => {
+    // Ensure the four plugin collections exist (setupPlugin does this in prod).
+    for (const slug of ['surveys-contacts', 'surveys-groups', 'surveys-surveys', 'surveys-invites']) {
+        if (!(await getCollection(slug).catch(() => null))) {
+            await createCollection({slug, title: slug, plugin: 'surveys', fields: [{name: 'x', type: 'text'}]});
+        }
+    }
+});
+
+async function buildApp() {
+    const app = Fastify();
+    app.register(fastifyJwt, {secret: 'test-secret-only-for-tests-32chars'});
+    const authenticate = async (req) => { req.user = {id: 'admin1', role: 'super-admin'}; };
+    await app.register(surveysPlugin, {prefix: '/api/plugins/surveys', settings: {}, auth: {authenticate}});
+    return app;
+}
+
+test('POST then GET /surveys round-trips a campaign', async () => {
+    const app = await buildApp();
+    const slug = 'sat-' + Date.now();
+    const create = await app.inject({method: 'POST', url: '/api/plugins/surveys/surveys',
+        payload: {slug, title: 'Sat', formSlug: 'sat-form', mode: 'anonymous'}});
+    assert.equal(create.statusCode, 201);
+    const list = await app.inject({method: 'GET', url: '/api/plugins/surveys/surveys'});
+    assert.equal(list.statusCode, 200);
+    assert.ok(JSON.parse(list.body).some(s => s.slug === slug));
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/plugin-admin.test.js`
+Expected: FAIL - cannot find module `plugin.js`.
+
+- [ ] **Step 3: Implement** `plugins/surveys/plugin.js` - import core services and the lib modules, build the wired instances, register routes. Key contents:
+
+```js
+import defaultConfig from './config.js';
+import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../../server/services/collections.js';
+import {createCampaigns} from './lib/campaigns.js';
+import {createAudience} from './lib/audience.js';
+import {createLedger} from './lib/ledger.js';
+
+const col = {createEntry, deleteEntry, getEntry, listEntries, updateEntry};
+
+export default async function surveysPlugin(fastify, options) {
+    const {authenticate} = options.auth;
+    const config = {...defaultConfig, ...(options.settings || {})};
+    const campaigns = createCampaigns(col);
+    const audience = createAudience(col);
+    const ledger = createLedger(col);
+
+    const auth = {preHandler: [authenticate]};
+
+    // ---- Surveys (campaigns) ----
+    fastify.get('/surveys', auth, async () => (await campaigns.all()).map(e => ({id: e.id, ...e.data})));
+
+    fastify.post('/surveys', auth, async (req, reply) => {
+        try {
+            const s = await campaigns.createSurvey(req.body ?? {});
+            return reply.code(201).send({id: s.id, ...s.data});
+        } catch (err) { return reply.code(400).send({error: err.message}); }
+    });
+
+    fastify.get('/surveys/:slug', auth, async (req, reply) => {
+        const s = await campaigns.getBySlug(req.params.slug);
+        if (!s) return reply.code(404).send({error: 'Survey not found'});
+        return {id: s.id, ...s.data};
+    });
+
+    fastify.put('/surveys/:slug', auth, async (req, reply) => {
+        const s = await campaigns.getBySlug(req.params.slug);
+        if (!s) return reply.code(404).send({error: 'Survey not found'});
+        const updated = await campaigns.updateSurvey(s.id, req.body ?? {});
+        return {id: updated.id, ...updated.data};
+    });
+
+    // ---- Audience: contacts ----
+    fastify.get('/contacts', auth, async () => audience.listContacts());
+    fastify.post('/contacts', auth, async (req, reply) => {
+        const {name, email, groups} = req.body ?? {};
+        if (!email) return reply.code(400).send({error: 'email is required'});
+        const e = await createEntry('surveys-contacts', {name: name ?? '', email, groups: Array.isArray(groups) ? groups : []}, {source: 'admin'});
+        return reply.code(201).send({id: e.id, ...e.data});
+    });
+    fastify.delete('/contacts/:id', auth, async (req, reply) => {
+        await deleteEntry('surveys-contacts', req.params.id).catch(() => {});
+        return {ok: true};
+    });
+
+    // ---- Audience: groups ----
+    fastify.get('/groups', auth, async () => {
+        const {entries} = await listEntries('surveys-groups', {limit: 10000});
+        return entries.map(e => ({id: e.id, name: e.data.name, description: e.data.description ?? ''}));
+    });
+    fastify.post('/groups', auth, async (req, reply) => {
+        const {name, description} = req.body ?? {};
+        if (!name) return reply.code(400).send({error: 'name is required'});
+        const e = await createEntry('surveys-groups', {name, description: description ?? ''}, {source: 'admin'});
+        return reply.code(201).send({id: e.id, ...e.data});
+    });
+
+    // ---- Import from Contacts plugin ----
+    fastify.post('/import-from-contacts', auth, async (req, reply) => {
+        const {entries} = await listEntries('contacts-contacts', {limit: 100000}).catch(() => ({entries: []}));
+        const source = entries.map(e => ({name: e.data.name, email: e.data.email, groups: e.data.groups}));
+        const result = await audience.importFromContacts(source);
+        return reply.send(result);
+    });
+
+    // Sending + stats routes are added in later tasks.
+    fastify.surveys = {campaigns, audience, ledger, col, config}; // expose for later tasks/tests
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/plugin-admin.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/plugin.js tests/surveys/plugin-admin.test.js
+git commit -m "feat(surveys): admin API - campaign + audience CRUD, contacts import"
+```
+
+### Task 7.2: Send + reminder + stats routes
+
+**Files:**
+- Modify: `plugins/surveys/plugin.js`
+- Test: `tests/surveys/plugin-send.test.js`
+
+- [ ] **Step 1: Write the failing test** - issue invites for a survey's groups, assert ledger rows created and statuses set. (Use a survey whose `groupIds` matches a seeded contact's groups; stub SMTP by setting an invalid host so `sendBatch` records `ok:false` but the route still 200s and marks `bounced`.)
+
+```js
+import {before, test} from 'node:test';
+import assert from 'node:assert/strict';
+import Fastify from 'fastify';
+import fastifyJwt from '@fastify/jwt';
+import surveysPlugin from '../../plugins/surveys/plugin.js';
+import {createCollection, getCollection, createEntry, listEntries} from '../../server/services/collections.js';
+
+before(async () => {
+    for (const slug of ['surveys-contacts', 'surveys-groups', 'surveys-surveys', 'surveys-invites']) {
+        if (!(await getCollection(slug).catch(() => null))) {
+            await createCollection({slug, title: slug, plugin: 'surveys', fields: [{name: 'x', type: 'text'}]});
+        }
+    }
+});
+
+async function buildApp() {
+    const app = Fastify();
+    app.register(fastifyJwt, {secret: 'test-secret-only-for-tests-32chars'});
+    await app.register(surveysPlugin, {prefix: '/api/plugins/surveys', settings: {}, auth: {authenticate: async (req) => { req.user = {id: 'a', role: 'super-admin'}; }}});
+    return app;
+}
+
+test('POST /surveys/:slug/send issues invites for the audience and reports results', async () => {
+    const app = await buildApp();
+    const tag = 'send-' + Date.now();
+    await createEntry('surveys-contacts', {name: 'A', email: 'a@example.test', groups: [tag]}, {source: 't'});
+    const slug = 'camp-' + Date.now();
+    await app.inject({method: 'POST', url: '/api/plugins/surveys/surveys', payload: {slug, title: 'C', formSlug: 'f', groupIds: [tag], status: 'open'}});
+    const res = await app.inject({method: 'POST', url: `/api/plugins/surveys/surveys/${slug}/send`, payload: {audience: 'all'}});
+    assert.equal(res.statusCode, 200);
+    const body = JSON.parse(res.body);
+    assert.equal(body.results.length, 1);
+    const {entries} = await listEntries('surveys-invites', {limit: 100000});
+    assert.ok(entries.some(e => ['sent', 'bounced'].includes(e.data.status)));
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/plugin-send.test.js`
+Expected: FAIL - 404 on `/send`.
+
+- [ ] **Step 3: Implement** - add to `plugin.js` (before the `fastify.surveys =` line). Reuse `sending.js`, `email.js`, `getConfig`:
+
+```js
+import {createTransport, sendEmail} from '../../server/services/email.js';
+import {getConfig} from '../../server/config.js';
+import {sendBatch} from './lib/sending.js';
+import {createStatsApi} from './lib/stats-api.js'; // thin loader; see note
+
+// inside surveysPlugin, after ledger is created:
+
+async function recipientsFor(survey, mode) {
+    const groupNames = Array.isArray(survey.data.groupIds) ? survey.data.groupIds : [];
+    const contactIds = await audience.contactIdsForGroups(groupNames);
+    const contacts = (await audience.listContacts()).filter(c => contactIds.includes(c.id));
+    const issued = await ledger.issueInvites(survey.id, contactIds);
+    const tokenByContact = new Map(issued.map(i => [i.contactId, i]));
+    let chosen = contacts;
+    if (mode === 'non-responders') {
+        const outstanding = new Set((await ledger.outstanding(survey.id)).map(e => e.data.contactId));
+        chosen = contacts.filter(c => outstanding.has(c.id));
+    }
+    // only contacts with a freshly-issued token can receive a personalised link
+    return chosen.map(c => {
+        const inv = tokenByContact.get(c.id);
+        return inv ? {invite: {id: inv.id}, contact: c, token: inv.token} : null;
+    }).filter(Boolean);
+}
+
+fastify.post('/surveys/:slug/send', auth, async (req, reply) => {
+    const survey = await campaigns.getBySlug(req.params.slug);
+    if (!survey) return reply.code(404).send({error: 'Survey not found'});
+    const {audience: mode = 'all'} = req.body ?? {};
+    const recipients = await recipientsFor(survey, mode === 'non-responders' ? 'non-responders' : 'all');
+    const smtp = getConfig('site').smtp || {};
+    const transport = await createTransport(smtp);
+    const results = await sendBatch(recipients, survey.data.inviteEmail || {}, {
+        sendEmail, transport, from: smtp.fromAddress, fromName: smtp.fromName || config.fromName,
+        baseUrl: getConfig('site').url || '', surveySlug: survey.data.slug
+    });
+    const nowIso = new Date().toISOString();
+    for (const r of results) await ledger.markSent(r.inviteId, r.ok, nowIso);
+    return reply.send({results});
+});
+```
+
+> **Note on `createStatsApi` import:** if you prefer not to add a `stats-api.js`, inline the stats route here instead. The stats route reads the survey's form (`readForm`), lists the form's submission collection (`listEntries(formSlug)`), runs `aggregateField` per field, and computes `campaignHealth(await ledger.invitesForSurvey(survey.id))`. Add `GET /surveys/:slug/stats` returning `{health, fields}` and `GET /surveys/:slug/export?format=csv|json`.
+
+Add the stats route concretely:
+
+```js
+import {readForm} from '../../server/services/forms.js';
+import {aggregateField, campaignHealth, toCsv} from './lib/stats.js';
+
+fastify.get('/surveys/:slug/stats', auth, async (req, reply) => {
+    const survey = await campaigns.getBySlug(req.params.slug);
+    if (!survey) return reply.code(404).send({error: 'Survey not found'});
+    const form = await readForm(survey.data.formSlug).catch(() => null);
+    const {entries} = await listEntries(survey.data.formSlug, {limit: 100000}).catch(() => ({entries: []}));
+    const rows = entries.map(e => e.data);
+    const fields = (form?.fields || [])
+        .filter(f => !['page-break', 'spacer', 'heading', 'paragraph', 'html'].includes(f.type))
+        .map(f => aggregateField(f, rows));
+    const health = campaignHealth(await ledger.invitesForSurvey(survey.id));
+    return reply.send({health, fields});
+});
+
+fastify.get('/surveys/:slug/export', auth, async (req, reply) => {
+    const survey = await campaigns.getBySlug(req.params.slug);
+    if (!survey) return reply.code(404).send({error: 'Survey not found'});
+    const form = await readForm(survey.data.formSlug).catch(() => null);
+    const cols = (form?.fields || []).map(f => f.name).filter(Boolean);
+    const {entries} = await listEntries(survey.data.formSlug, {limit: 100000}).catch(() => ({entries: []}));
+    const rows = entries.map(e => e.data);
+    if ((req.query.format || 'csv') === 'json') {
+        return reply.header('Content-Disposition', `attachment; filename="${survey.data.slug}.json"`).send(rows);
+    }
+    return reply.header('Content-Type', 'text/csv')
+        .header('Content-Disposition', `attachment; filename="${survey.data.slug}.csv"`)
+        .send(toCsv(rows, cols));
+});
+```
+
+(Disregard the `createStatsApi` import line - implement the routes inline as above.)
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/plugin-send.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/plugin.js tests/surveys/plugin-send.test.js
+git commit -m "feat(surveys): send/reminder batch + stats + export routes"
+```
+
+---
+
+## Phase 8 - Public surface (`plugin.public.js`)
+
+Root-mounted: hosted page, public submit, scheduler contract.
+
+### Task 8.1: Public submit endpoint
+
+**Files:**
+- Create: `plugins/surveys/plugin.public.js`
+- Test: `tests/surveys/public-submit.test.js`
+
+> **Carried-forward concern (from Task 3.1 code review):** `processSurveySubmission` does a check-then-act on the invite (read `status === 'completed'`, write the response, then `markCompleted`) with no lock. Under concurrent submits of the SAME token on the lock-free FileAdapter, both could pass the completed-check and create two response rows from one invite - defeating one-response-per-invite. Mitigate at THIS route layer: immediately before storing, re-read the invite via `ledger.findByCode` and abort with 409 if it is now `completed` (narrows but does not fully close the window). Add a test asserting two near-simultaneous submits of one token yield exactly one `completed` invite / one response. Full atomicity would need an adapter-level guard - out of scope; note it in `CLAUDE.md`.
+
+- [ ] **Step 1: Write the failing test** - issue an invite, POST a valid answer to `/api/plugins/surveys/submit/:slug`, assert 200 + ledger completed; POST again → 409.
+
+```js
+import {before, test} from 'node:test';
+import assert from 'node:assert/strict';
+import Fastify from 'fastify';
+import publicPlugin from '../../plugins/surveys/plugin.public.js';
+import {createCollection, getCollection, createEntry, listEntries} from '../../server/services/collections.js';
+import {ensureFormsDir, writeForm} from '../../server/services/forms.js';
+import {createCampaigns} from '../../plugins/surveys/lib/campaigns.js';
+import {createLedger} from '../../plugins/surveys/lib/ledger.js';
+
+const col = {createEntry, getEntry: (s, id) => import('../../server/services/collections.js').then(m => m.getEntry(s, id)), listEntries, updateEntry: (s, id, d) => import('../../server/services/collections.js').then(m => m.updateEntry(s, id, d))};
+
+before(async () => {
+    for (const slug of ['surveys-surveys', 'surveys-invites']) {
+        if (!(await getCollection(slug).catch(() => null))) await createCollection({slug, title: slug, plugin: 'surveys', fields: [{name: 'x', type: 'text'}]});
+    }
+    await ensureFormsDir();
+    await writeForm('ps-form', {slug: 'ps-form', title: 'PS', fields: [{name: 'q1', label: 'Q1', type: 'text', required: true}], actions: {}, settings: {}});
+    if (!(await getCollection('ps-form').catch(() => null))) await createCollection({slug: 'ps-form', title: 'PS', fields: [{name: 'q1', type: 'text'}]});
+});
+
+test('valid token submit completes the invite; second attempt 409', async () => {
+    const slug = 'ps-' + Date.now();
+    const camp = createCampaigns({createEntry, listEntries, getEntry: (s, id) => import('../../server/services/collections.js').then(m => m.getEntry(s, id)), updateEntry: (s, id, d) => import('../../server/services/collections.js').then(m => m.updateEntry(s, id, d))});
+    const survey = await camp.createSurvey({slug, title: 'PS', formSlug: 'ps-form', status: 'open'});
+    const ledger = createLedger({createEntry, listEntries, getEntry: (s, id) => import('../../server/services/collections.js').then(m => m.getEntry(s, id)), updateEntry: (s, id, d) => import('../../server/services/collections.js').then(m => m.updateEntry(s, id, d))});
+    const [invite] = await ledger.issueInvites(survey.id, ['c1']);
+
+    const app = Fastify();
+    await app.register(publicPlugin, {settings: {}, auth: {}, config: {}});
+    const ok = await app.inject({method: 'POST', url: `/api/plugins/surveys/submit/${slug}`, payload: {token: invite.token, data: {q1: 'Great'}}});
+    assert.equal(ok.statusCode, 200);
+    const again = await app.inject({method: 'POST', url: `/api/plugins/surveys/submit/${slug}`, payload: {token: invite.token, data: {q1: 'Again'}}});
+    assert.equal(again.statusCode, 409);
+});
+```
+
+> If the async-getEntry wrapper above proves awkward in practice, build a small synchronous adapter object `{createEntry, listEntries, getEntry, updateEntry}` by importing the four functions at the top of the test instead - the point of the test is the HTTP behaviour, not the wiring style.
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/public-submit.test.js`
+Expected: FAIL - cannot find module `plugin.public.js`.
+
+- [ ] **Step 3: Implement** `plugin.public.js`:
+
+```js
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {createEntry, getEntry, listEntries, updateEntry, getCollection} from '../../server/services/collections.js';
+import {readForm} from '../../server/services/forms.js';
+import {createTransport, sendFormEmail} from '../../server/services/email.js';
+import {getConfig} from '../../server/config.js';
+import {createCampaigns} from './lib/campaigns.js';
+import {createLedger} from './lib/ledger.js';
+import {processSurveySubmission, SurveyError} from './lib/submit.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const col = {createEntry, getEntry, listEntries, updateEntry};
+
+export default async function surveysPublicPlugin(fastify, options) {
+    const campaigns = createCampaigns(col);
+    const ledger = createLedger(col);
+
+    async function sendCompletionEmail(form, data) {
+        const ea = form.actions?.email;
+        if (!ea?.enabled || !ea.recipients) return;
+        const smtp = getConfig('site').smtp || {};
+        const transport = await createTransport(smtp);
+        await sendFormEmail(transport, {
+            from: smtp.fromAddress, fromName: smtp.fromName, to: ea.recipients,
+            subject: `${ea.subjectPrefix || `[${form.title}]`} New survey response`,
+            formTitle: form.title, fields: form.fields, data
+        });
+    }
+
+    const deps = {
+        col, ledger,
+        getSurveyBySlug: (slug) => campaigns.getBySlug(slug),
+        readForm,
+        getCollection,
+        sendCompletionEmail,
+        now: () => new Date().toISOString()
+    };
+
+    // Public submit
+    fastify.post('/api/plugins/surveys/submit/:slug', async (req, reply) => {
+        const {token, data} = req.body ?? {};
+        try {
+            const result = await processSurveySubmission(req.params.slug, token, data || {}, deps);
+            return reply.send(result);
+        } catch (err) {
+            const code = err instanceof SurveyError ? err.statusCode : 500;
+            return reply.code(code).send({error: err.message});
+        }
+    });
+
+    // Hosted page + scheduler contract are added in later tasks.
+    fastify.surveysPublic = {campaigns, ledger, deps};
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/public-submit.test.js`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/plugin.public.js tests/surveys/public-submit.test.js
+git commit -m "feat(surveys): public tokenised submit endpoint"
+```
+
+### Task 8.2: Scheduler contract (`/due-work`, `/run`)
+
+**Files:**
+- Modify: `plugins/surveys/plugin.public.js`
+- Test: `tests/surveys/due-work.test.js`
+
+- [ ] **Step 1: Write the failing test** - without a bearer token → 403; with the configured `schedulerToken` → 200 and a JSON array.
+
+```js
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import Fastify from 'fastify';
+import publicPlugin from '../../plugins/surveys/plugin.public.js';
+
+test('/due-work requires the scheduler token', async () => {
+    const app = Fastify();
+    await app.register(publicPlugin, {settings: {schedulerToken: 'dcms_secret'}, auth: {}, config: {}});
+    const no = await app.inject({method: 'GET', url: '/api/plugins/surveys/due-work'});
+    assert.equal(no.statusCode, 403);
+    const yes = await app.inject({method: 'GET', url: '/api/plugins/surveys/due-work', headers: {authorization: 'Bearer dcms_secret'}});
+    assert.equal(yes.statusCode, 200);
+    assert.ok(Array.isArray(JSON.parse(yes.body)));
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test tests/surveys/due-work.test.js`
+Expected: FAIL - 404.
+
+- [ ] **Step 3: Implement** - add to `plugin.public.js`. Use `options.settings.schedulerToken`:
+
+```js
+const schedulerToken = options.settings?.schedulerToken || '';
+
+function requireScheduler(req, reply) {
+    const hdr = req.headers.authorization || '';
+    const tok = hdr.startsWith('Bearer ') ? hdr.slice(7) : '';
+    if (!schedulerToken || tok !== schedulerToken) { reply.code(403).send({error: 'Forbidden'}); return false; }
+    return true;
+}
+
+// Generic due-work: open campaigns with invites past their reminder threshold.
+fastify.get('/api/plugins/surveys/due-work', async (req, reply) => {
+    if (!requireScheduler(req, reply)) return;
+    const now = new Date();
+    const surveys = (await campaigns.all()).filter(s => s.data.status === 'open');
+    const out = [];
+    for (const s of surveys) {
+        const due = await ledger.dueForReminder(s.id, Number(s.data.reminderAfterDays) || 7, now);
+        if (due.length) out.push({plugin: 'surveys', campaignSlug: s.data.slug, dueCount: due.length});
+    }
+    return reply.send(out);
+});
+
+// Generic run: execute a batch for a campaign (reminder or full).
+fastify.post('/api/plugins/surveys/run', async (req, reply) => {
+    if (!requireScheduler(req, reply)) return;
+    const {campaignSlug, audience: mode = 'non-responders', reminder = true} = req.body ?? {};
+    const survey = await campaigns.getBySlug(campaignSlug);
+    if (!survey) return reply.code(404).send({error: 'Survey not found'});
+    // Reuse the same recipient + send path as the admin route by importing the
+    // shared helper. For reminders, links omit ?t= (recipients use their code).
+    const result = await runScheduledBatch(survey, {mode, reminder});
+    return reply.send(result);
+});
+```
+
+> **`runScheduledBatch`:** factor the admin route's recipient-resolution + `sendBatch` + `markSent` loop from Task 7.2 into an exported helper in `lib/sending.js` (e.g. `export async function runSend({survey, mode, reminder, audience, ledger, sendEmail, smtp, baseUrl, fromName})`) and call it from BOTH the admin `/send` route and this `/run` route. This removes duplication (DRY) - refactor Task 7.2's inline logic into that helper when you reach this step, re-running `tests/surveys/plugin-send.test.js` to confirm no regression.
+
+- [ ] **Step 4: Run to verify pass**
+
+Run: `node --test tests/surveys/due-work.test.js && node --test tests/surveys/plugin-send.test.js`
+Expected: PASS (both).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/surveys/plugin.public.js plugins/surveys/lib/sending.js tests/surveys/due-work.test.js
+git commit -m "feat(surveys): scheduler-ready due-work + run contract"
+```
+
+### Task 8.3: Hosted page (`GET /survey/:slug`) + client + shortcode
+
+**Files:**
+- Modify: `plugins/surveys/plugin.public.js`
+- Create: `plugins/surveys/templates/survey-page.html`
+- Create: `plugins/surveys/public/survey.mjs`
+- Create: `plugins/surveys/public/survey.css`
+
+> **Browser-verified, not unit-tested** (project memory: never claim UI verified from curl/inject alone). Tests here are manual.
+
+- [ ] **Step 1: Write `templates/survey-page.html`** - a public SSR shell with `{{title}}`, a `#survey-mount` div, a `#survey-code` manual-entry box (shown when no token), and script/style tags loading `/plugins/surveys/public/survey.mjs` (as `type="module"`) and `/plugins/surveys/public/survey.css`. Mirror `plugins/blog/templates/*.html` head/asset structure and load the Domma dist (`/dist/domma/...`) the same way the public page shell does.
+
+- [ ] **Step 2: Implement `GET /survey/:slug`** in `plugin.public.js`:
+
+```js
+import fs from 'fs/promises';
+fastify.get('/survey/:slug', async (req, reply) => {
+    const survey = await campaigns.getBySlug(req.params.slug);
+    if (!survey || survey.data.status !== 'open') {
+        return reply.code(survey ? 410 : 404).type('text/html').send('<h1>This survey is not available.</h1>');
+    }
+    let html = await fs.readFile(path.join(__dirname, 'templates', 'survey-page.html'), 'utf8');
+    html = html
+        .replaceAll('{{title}}', escapeHtml(survey.data.title))
+        .replaceAll('{{slug}}', escapeHtml(survey.data.slug))
+        .replaceAll('{{formSlug}}', escapeHtml(survey.data.formSlug));
+    return reply.type('text/html').send(html);
+});
+```
+
+(Add a local `escapeHtml` helper as in `plugin.js`.)
+
+- [ ] **Step 3: Write `public/survey.mjs`** - the client:
+  1. read `?t=` from `location.search` (or show `#survey-code` box; on submit normalise via the same alphabet),
+  2. `fetch('/api/forms/' + formSlug + '/public').then(r => r.json())` to get the form def (do NOT use `H.get` for non-JSON - this IS JSON so `H.get` is fine, but plain `fetch().then(r=>r.json())` avoids the gotcha),
+  3. build a Domma blueprint from the form def fields and render with `Domma.forms.render(mountEl, blueprint, {}, opts)`,
+  4. on submit, `H.post('/api/plugins/surveys/submit/' + slug, {token, data})`,
+  5. on success show the thank-you state via `E.toast` + replacing the mount content; on 409/410/403 show the matching message.
+
+- [ ] **Step 4: Write `public/survey.css`** - styles for `.survey-dist*` bars (shared with the admin results view) and the code-entry box.
+
+- [ ] **Step 5: Register the `[survey]` shortcode** - in `plugin.js` (or a shared init), call the injected `hooks.registerShortcode('survey', handler)` where the handler returns the same `#survey-mount` markup + a `data-survey-slug` attribute, and ensure the page loads `survey.mjs`. (Shortcode is registered via the `hooks` passed to `plugin.js` options - confirm the hooks object is available; the loader passes `hooks` in `options` per `server/services/plugins.js:214`.)
+
+- [ ] **Step 6: Manual browser verification** (per memory - required before claiming it works):
+  - Start nothing (server always running on 4096). Clear cache via `POST /api/cache/clear` with a JWT minted from `JWT_SECRET` (see `project_dev_server_no_hot_reload`).
+  - Create a test form + survey + contact via the admin UI; send an invite to a real inbox you control (or read the token from the `surveys-invites` entry in dev).
+  - Load `http://192.168.1.4:4096/survey/<slug>?t=<code>` in a browser, complete it, confirm thank-you state and that the invite row flipped to `completed`.
+  - Reload with the same token → "already completed" message.
+  - Embed `[survey slug="<slug>"]` in a page → confirm it renders and submits.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add plugins/surveys/plugin.public.js plugins/surveys/templates plugins/surveys/public
+git commit -m "feat(surveys): hosted survey page, client renderer, and [survey] shortcode"
+```
+
+---
+
+## Phase 9 - Admin UI (Domma views)
+
+> **Browser-verified, not unit-tested.** Each view mirrors `plugins/contacts/admin/views/contacts.js` + its `.html` template exactly: `export const <name>View = { templateUrl, async onMount($container) {...} }`. Use `$container.find('#id').get(0)`, `T.create`, `F.create`, `E.*`, `H.*`, `I.scan()`. No `?v=N` on imports.
+
+### Task 9.1: Surveys list view
+
+**Files:**
+- Create: `plugins/surveys/admin/templates/surveys.html`
+- Create: `plugins/surveys/admin/views/surveys.js`
+
+- [ ] **Step 1:** Write `surveys.html` - a header with a "New Survey" button (`#new-survey`) and a `#surveys-table` mount.
+- [ ] **Step 2:** Write `surveys.js` - `onMount` does `H.get('/api/plugins/surveys/surveys')`, then `T.create($container.find('#surveys-table').get(0), {data, columns})`. Columns: title, status (badge), response-rate (from a per-row `H.get` stats call or a lightweight count), and an actions column whose render returns an HTML string with `onclick` handlers (NOT addEventListener - double-bind gotcha) navigating to `#/plugins/surveys/edit/:slug` and `#/plugins/surveys/results/:slug`. Wire `#new-survey` to `#/plugins/surveys/new`.
+- [ ] **Step 3: Browser-verify** the list renders, badges show, buttons navigate.
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/surveys/admin/templates/surveys.html plugins/surveys/admin/views/surveys.js
+git commit -m "feat(surveys): admin surveys list view"
+```
+
+### Task 9.2: Survey editor view
+
+**Files:**
+- Create: `plugins/surveys/admin/templates/survey-editor.html`
+- Create: `plugins/surveys/admin/views/survey-editor.js`
+
+- [ ] **Step 1:** Template with a `#survey-form` mount + Save button.
+- [ ] **Step 2:** `onMount` builds the editor with `F.create('#survey-form', {blueprint})` where blueprint covers: title, slug (disabled on edit), description, formSlug (a select populated from `H.get('/api/forms')`), groupIds (multi-select from `H.get('/api/plugins/surveys/groups')`), mode (`identified|anonymous` radio), status (`draft|open|closed`), opensAt/closesAt (date), reminderAfterDays (number), inviteEmail.subject + inviteEmail.body (textareas with `{{name}}`/`{{link}}` hint). On submit, POST (new) or PUT (edit) to `/api/plugins/surveys/surveys[/:slug]`; `E.toast` on success; navigate back to the list. On the `:slug` route, pre-load via `H.get('/api/plugins/surveys/surveys/:slug')`.
+- [ ] **Step 3: Browser-verify** create + edit round-trip; confirm anonymous/identified persists.
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/surveys/admin/templates/survey-editor.html plugins/surveys/admin/views/survey-editor.js
+git commit -m "feat(surveys): admin survey editor view"
+```
+
+### Task 9.3: Audience view
+
+**Files:**
+- Create: `plugins/surveys/admin/templates/audience.html`
+- Create: `plugins/surveys/admin/views/audience.js`
+
+- [ ] **Step 1:** Template with a contacts `T.create` mount, an "Add contact" (`F.create` in an `E.modal`), a groups panel, and an "Import from Contacts" button (`#import-contacts`).
+- [ ] **Step 2:** `onMount` loads `/contacts` + `/groups`; renders the table; wires add/delete (`E.confirm` before delete); `#import-contacts` calls `H.post('/api/plugins/surveys/import-from-contacts')` then `E.toast('Imported N contacts')` and refreshes. Modal buttons via light-DOM slot projection (gotcha #3).
+- [ ] **Step 3: Browser-verify** add/delete/import; confirm imported contacts appear.
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/surveys/admin/templates/audience.html plugins/surveys/admin/views/audience.js
+git commit -m "feat(surveys): admin audience view with contacts import"
+```
+
+### Task 9.4: Results view
+
+**Files:**
+- Create: `plugins/surveys/admin/templates/results.html`
+- Create: `plugins/surveys/admin/views/results.js`
+
+- [ ] **Step 1:** Template with health-widget row, a per-question section mount, an outstanding-list mount, and CSV/JSON export buttons.
+- [ ] **Step 2:** `onMount` calls `H.get('/api/plugins/surveys/surveys/:slug/stats')`; renders health (invited/completed/rate); for each `fields[]` entry: choice/rating → inject `renderDistribution(field.items)` HTML (import the same function from `../../lib/stats.js`? - NOTE: admin views are browser ESM; import via a small shared client copy or duplicate the ~8-line `renderDistribution` in the view to avoid a server import. Prefer a shared `plugins/surveys/public/dist-shared.mjs` exporting `renderDistribution`, imported by BOTH `survey.mjs` and this view). Text fields → list responses. Export buttons link to `/api/plugins/surveys/surveys/:slug/export?format=csv|json` (open in new tab with the auth header - use `H.get` + blob download, or a tokenised link).
+- [ ] **Step 3: Browser-verify** with a survey that has responses: bars render, rate correct, export downloads.
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/surveys/admin/templates/results.html plugins/surveys/admin/views/results.js plugins/surveys/public/dist-shared.mjs
+git commit -m "feat(surveys): admin results view - health, distributions, export"
+```
+
+> **Refactor note:** when you create `public/dist-shared.mjs` with `renderDistribution`, update `lib/stats.js` to keep the server copy (used for any server-side rendering/tests) and the client copy in sync - or have `lib/stats.js` re-export from a shared location. Keep ONE canonical implementation; the test in `tests/surveys/stats.test.js` must still pass against whichever module it imports.
+
+---
+
+## Phase 10 - Permissions & wiring
+
+### Task 10.1: Register the `surveys` permission resource
+
+**Files:**
+- Modify: `plugins/surveys/plugin.js`
+
+- [ ] **Step 1:** In `surveysPlugin`, register the permission family on load using the injected hooks/registry. The loader exposes `registerSidebarItem` etc. via `options.hooks`; permission registration uses `permissionRegistry.registerPluginResource`. Add at the top of `surveysPlugin`:
+
+```js
+import {registerPluginResource} from '../../server/services/permissionRegistry.js';
+
+// inside surveysPlugin, once:
+registerPluginResource({
+    key: 'surveys',
+    label: 'Surveys',
+    actions: ['read', 'create', 'update', 'delete']
+}, 'surveys');
+```
+
+- [ ] **Step 2:** Add `requirePermission`-style guards if the loader provides them; otherwise keep `authenticate` and rely on the sidebar `permission: "surveys"` filter (matches the Projects/Menus pattern - admins grant `surveys.read` in the role editor). Document in `CLAUDE.md` that custom roles need a manual grant (not back-filled).
+
+- [ ] **Step 3:** Verify the whole suite passes: `npm test`. Expected: all `tests/surveys/*.test.js` pass alongside the existing suite.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add plugins/surveys/plugin.js plugins/surveys/CLAUDE.md
+git commit -m "feat(surveys): register surveys permission family"
+```
+
+### Task 10.2: Enable + smoke-test end to end
+
+- [ ] **Step 1:** Add `surveys` to `config/plugins.json` (enabled: true) - confirm the format from an existing entry.
+- [ ] **Step 2:** Restart is NOT automatic (no hot reload). The user runs the server; ask them to restart it (or restart via their normal process) so `setupPlugin` seeds the four collections.
+- [ ] **Step 3:** Confirm startup log `[plugins] Loaded N plugins:` includes `surveys`, and that `content/collections/surveys-*` (file mode) or the Mongo `cms_surveys-*` collections exist.
+- [ ] **Step 4:** Full manual pass: create form → create survey (identified) → add contacts to a group → send → complete via hosted link → check Results show 100% + the answer; repeat with an anonymous survey and confirm the export contains no contact identity.
+- [ ] **Step 5: Commit** any config change:
+
+```bash
+git add config/plugins.json
+git commit -m "chore(surveys): enable plugin"
+```
+
+---
+
+## Self-Review (completed during planning)
+
+**Spec coverage:**
+- Audience model + import → Phase 0.2, 4.1, 7.1 (`/import-from-contacts`). ✓
+- Mongo-with-file-fallback storage → schemas declare adapter (0.2); helpers are adapter-agnostic. ✓
+- Per-survey identified/anonymous → submit.js (3.1) + campaigns (4.2) + editor (9.2). ✓
+- Hosted page + `[survey]` shortcode → 8.3. ✓
+- Token (readable, hashed) → 1.1; ledger → 2.x. ✓
+- Editor-triggered send + reminders → 7.2; due-work/run contract → 8.2. ✓
+- Layered stats + CSV/JSON export → 6.1 + 7.2 + 9.4. ✓
+- `renderDistribution` seam → 6.1; upstream stub referenced. ✓
+- Permissions family → 10.1. ✓
+- Error handling (invalid/used/closed/validation/bounce/anonymity) → 3.1 tests + 7.2. ✓
+- Out-of-scope (project scoping, open-tracking) → intentionally absent. ✓
+
+**Placeholder scan:** The `createStatsApi` import in Task 7.2 is explicitly retracted in the same task with concrete inline route code; the async-getEntry wrapper in Task 8.1 has a concrete fallback note. No `TBD`/`TODO`. `renderDistribution` duplication is resolved by the Phase 9.4 shared-module note. ✓
+
+**Type/name consistency:** `processSurveySubmission(surveySlug, code, body, deps)`, `createLedger(col)` → `{issueInvites, findByCode, markSent, markCompleted, outstanding, dueForReminder, invitesForSurvey}`, `aggregateField/renderDistribution/campaignHealth/toCsv`, collection slugs `surveys-{contacts,groups,surveys,invites}` - used consistently across tasks and tests. ✓
+
+**Open item flagged for implementer:** the scheduler auth header is a shared-secret Bearer (`schedulerToken`) for v1; if domma-cms-manager uses a different scheme, adjust `requireScheduler` only. ✓
+```