domma-cms 0.66.0 → 0.69.4

package/{plugins/analytics/plugin.js → server/routes/api/analytics.js}

@@ -1,35 +1,60 @@
 /**
- * Analytics Plugin - Server
- * Tracks page hits with per-day buckets so we can chart trends and
- * filter by time range.
+ * Analytics - page-hit counters, trends and journeys.
  *
- * Storage:
- *   lifetime.json  { "/url": totalHits }
- *   daily.json     { "YYYY-MM-DD": { "/url": hits } }
+ * Was the `analytics` plugin until 0.67.0, where it was a CORE_PLUGINS member:
+ * always loaded, never switchable off. A feature nobody may turn off has no
+ * business being listed as an add-on, so it is simply part of the CMS now.
  *
- * Endpoints (mounted at /api/plugins/analytics):
- *   POST   /hit            public  record a hit { url, dnt }
+ * **Counters live in `content/analytics/`, not under plugins/.** They are real
+ * traffic history that cannot be regenerated, and the retirement migration
+ * deletes the plugin directory - so the data had to move out from under it. The
+ * migration copies and verifies before anything is removed.
+ *
+ * This is the CLIENT-SIDE beacon's store: a browser posts to /api/analytics/hit,
+ * which means bots, blocked scripts and Do-Not-Track visitors are absent by
+ * design. `analytics-pro` counts the same site server-side from an onRequest
+ * hook and will always report more. They are different instruments, not two
+ * versions of one, which is why neither supersedes the other.
+ *
+ * Endpoints (mounted at /api/analytics):
+ *   POST   /hit            public  record a hit { url, sid, ref }
  *   GET    /stats          admin   summary + top pages (?range=today|7d|30d|90d|all|custom&from=&to=)
  *   GET    /series         admin   per-day totals series (?days=N or ?from=&to=)
+ *   GET    /journeys       admin   entry/exit/path aggregates
+ *   GET    /realtime       admin   sessions active in the last 5 minutes
+ *   GET    /spikes         admin   days that stand out from the trend
  *   GET    /export.csv     admin   CSV export of top pages for the active range
- *   DELETE /stats          admin   reset all stats
+ *   DELETE /stats          admin   reset all counters
  */
+import {clip, plural} from '../../services/sidebarBadges.js';
 import fs from 'fs/promises';
 import path from 'path';
-import {fileURLToPath} from 'url';
+import {authenticate as defaultAuthenticate, requireAdmin as defaultRequireAdmin} from '../../middleware/auth.js';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Where the counters live. Resolved per call rather than frozen at import so a
+ * test can run against a temporary install, the way the migrations do.
+ */
+export function analyticsDir() {
+    return path.resolve('content', 'analytics');
+}
 
-// Runtime counters live under data/ - the carve-out that BOTH update paths
-// preserve (siteCmsUpdater's copyPlugin backs up data/; `domma-cms update`
-// keeps 'data' in its preserve set). Pre-2.1 they sat in the plugin root and
-// were overwritten by the manager's copy on every plugin push. On first boot
-// migrateToDataDir() moves any pre-2.1 root files across.
-const DATA_DIR = path.join(__dirname, 'data');
+const DATA_DIR = analyticsDir();
 const LIFETIME_FILE = path.join(DATA_DIR, 'lifetime.json');
 const DAILY_FILE = path.join(DATA_DIR, 'daily.json');
 const LEGACY_FILE = path.join(DATA_DIR, 'stats.json');
 const JOURNEYS_FILE = path.join(DATA_DIR, 'journeys.json');
+
+/**
+ * What never gets counted, server side.
+ *
+ * These were the plugin's `config.js` defaults and no install ever changed one,
+ * so they are constants rather than a config block nobody would open. The other
+ * two defaults it carried - honourDnt and sessionDedup - were always decided in
+ * the browser, where the facts are, and still are: see public/js/analytics.js.
+ */
+const EXCLUDE_ADMIN = true;
+const EXCLUDE_PATHS = ['/api'];
 const JOURNEY_DAILY_CAP = 5000;
 const REALTIME_WINDOW_MS = 5 * 60 * 1000;
 
@@ -48,23 +73,6 @@ async function writeJson(file, data) {
     await fs.rename(tmp, file);
 }
 
-/**
- * One-shot relocation of pre-2.1 counters from the plugin root into data/.
- * Runs before migrateLegacy() so the rest of the plugin only ever sees data/.
- */
-async function migrateToDataDir() {
-    await fs.mkdir(DATA_DIR, { recursive: true });
-    for (const name of ['lifetime.json', 'daily.json', 'journeys.json', 'stats.json']) {
-        const dest = path.join(DATA_DIR, name);
-        try { await fs.access(dest); continue; } catch { /* dest absent - maybe move */ }
-        const oldPath = path.join(__dirname, name);
-        try {
-            await fs.access(oldPath);
-            await fs.rename(oldPath, dest);
-        } catch { /* no pre-2.1 file to move */ }
-    }
-}
-
 /**
  * One-shot migration from the legacy flat stats.json.
  * Preserves existing totals as lifetime numbers; daily history starts empty.
@@ -274,11 +282,17 @@ function shouldRecordJourney(dayEntries, cap = JOURNEY_DAILY_CAP) {
     return Array.isArray(dayEntries) && dayEntries.length < cap;
 }
 
-export default async function analyticsPlugin(fastify, options) {
-    const { authenticate, requireAdmin } = options.auth;
-    const settings = options.settings || {};
+/**
+ * Auth is injectable, the shape dashboard.js and plugins.js use, so a test can
+ * drive these routes without registering @fastify/jwt.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} [opts]
+ */
+export async function analyticsRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requireAdmin = opts.requireAdmin || defaultRequireAdmin;
 
-    await migrateToDataDir();
     await migrateLegacy();
 
     fastify.decorate('analytics', {
@@ -333,11 +347,11 @@ export default async function analyticsPlugin(fastify, options) {
         }
 
         const normalised = url.split('?')[0].split('#')[0].replace(/\/+$/, '') || '/';
-        if (settings.excludeAdmin && normalised.startsWith('/admin')) {
+        if (EXCLUDE_ADMIN && normalised.startsWith('/admin')) {
             return { ok: true, ignored: 'admin' };
         }
-        if (Array.isArray(settings.excludePaths)) {
-            for (const prefix of settings.excludePaths) {
+        if (Array.isArray(EXCLUDE_PATHS)) {
+            for (const prefix of EXCLUDE_PATHS) {
                 if (typeof prefix === 'string' && prefix && normalised.startsWith(prefix)) {
                     return { ok: true, ignored: 'excluded' };
                 }
@@ -441,6 +455,40 @@ export default async function analyticsPlugin(fastify, options) {
         return { activeSessions: sids.size, windowMinutes: REALTIME_WINDOW_MS / 60000 };
     });
 
+    /** GET /api/analytics/active-count - the sidebar badge: visitors on the site right now. */
+    fastify.get('/active-count', { preHandler: [authenticate, requireAdmin] }, async () => {
+        const [journeys, daily] = await Promise.all([readJson(JOURNEYS_FILE, {}), readJson(DAILY_FILE, {})]);
+        const today = todayKey();
+        const cutoff = Date.now() - REALTIME_WINDOW_MS;
+        const recent = (journeys[today] || []).filter(ev => ev.t >= cutoff);
+        const n = new Set(recent.map(ev => ev.sid)).size;
+        const mins = REALTIME_WINDOW_MS / 60000;
+
+        // What each active visitor is on now: their latest page.
+        const latest = new Map();
+        for (const ev of recent) if (!latest.has(ev.sid) || latest.get(ev.sid).t < ev.t) latest.set(ev.sid, ev);
+        const onPage = {};
+        for (const ev of latest.values()) onPage[ev.url] = (onPage[ev.url] || 0) + 1;
+        const viewsToday = Object.values(daily[today] || {}).reduce((a, b) => a + b, 0);
+        const sessionsToday = new Set((journeys[today] || []).map(ev => ev.sid)).size;
+
+        return {
+            count: n, label: `${plural(n, 'visitor')} on the site in the last ${mins} minutes`, tone: 'live',
+            details: {
+                title: 'Analytics',
+                rows: [
+                    {label: 'Active now', value: String(n)},
+                    {label: 'Views today', value: viewsToday.toLocaleString('en-GB')},
+                    {label: 'Sessions today', value: sessionsToday.toLocaleString('en-GB')}
+                ],
+                // URLs come from the PUBLIC hit counter - plain text only, set with textContent.
+                items: Object.entries(onPage).sort((a, b) => b[1] - a[1]).slice(0, 5)
+                    .map(([url, c]) => ({text: clip(url, 48), meta: `${plural(c, 'visitor')} here now`})),
+                empty: `Nobody on the site in the last ${mins} minutes.`
+            }
+        };
+    });
+
     fastify.get('/spikes', { preHandler: [authenticate, requireAdmin] }, async () => {
         const daily = await readJson(DAILY_FILE, {});
         return { items: detectSpikes(daily) };

package/{plugins/contacts/plugin.js → server/routes/api/contacts.js}

@@ -1,11 +1,31 @@
-import path from 'path';
-import {fileURLToPath} from 'url';
-
-import defaultConfig from './config.js';
-import {createEntry, deleteEntry, getCollection, getEntry, listEntries, updateCollection, updateEntry} from '../../server/services/collections.js';
-import {syncPluginSchemas} from '../_lib/schemaSync.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Contacts API - /api/contacts
+ *
+ * Was the `contacts` plugin until 0.67.0. Enabled on every site on the fleet,
+ * which is the case for it being part of the CMS rather than something you go
+ * shopping for.
+ *
+ * **Per-user scope, for contacts only.** A contact carries a `userId` and reads
+ * are filtered to the caller's own. **Groups are not**: `loadGroups()` takes no
+ * user and never has, so a group one person creates is visible to everyone.
+ * That asymmetry is preserved rather than tidied - changing who can see a group
+ * is a behaviour change, and this was a relocation. A test pins it so the next
+ * reader finds it stated rather than inferred.
+ *
+ * Hand-filtered, as the plugin did it, rather than via rowAccess.js - the right
+ * end state, and again not something to smuggle into a move.
+ *
+ * **The slugs are `contacts-contacts` and `contacts-groups`**, not the
+ * directories the schemas used to sit in (`user-contacts`,
+ * `user-contact-groups`). setupPlugin() read `schema.slug`, so those are the
+ * live collections and existing rows are found only if they stay exactly so.
+ *
+ * The plugin called syncPluginSchemas() to keep an existing collection's fields
+ * in step with its schema. Core has no need: seedAll() rewrites every preset's
+ * schema.json on each boot, which is the same job done earlier.
+ */
+import {authenticate as defaultAuthenticate, requirePermission as defaultRequirePermission} from '../../middleware/auth.js';
+import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../../services/collections.js';
 
 const CONTACTS_SLUG = 'contacts-contacts';
 const GROUPS_SLUG = 'contacts-groups';
@@ -187,18 +207,19 @@ function toGroupName(entry) {
     return entry.data.name ?? '';
 }
 
-export default async function contactsPlugin(fastify, options) {
-    const {authenticate} = options.auth;
+/**
+ * Auth is injectable, the shape dashboard.js and plugins.js use.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} [opts]
+ */
+export async function contactsRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
 
-    // A collection is created once and never revisited, so the fields added
-    // here reach a fresh install and nowhere else without this.
-    await syncPluginSchemas(path.join(__dirname, 'collections'),
-        {getCollection, updateCollection}, fastify.log);
-    const config = {...defaultConfig, ...(options.settings || {})};
-    const scope = config.scope ?? 'user';
 
     function userId(request) {
-        return scope === 'user' ? (request.user?.id ?? request.user?.sub ?? null) : null;
+        return request.user?.id ?? request.user?.sub ?? null;
     }
 
     async function loadContacts(uid) {
@@ -241,8 +262,8 @@ export default async function contactsPlugin(fastify, options) {
     // Contacts CRUD
     // -------------------------------------------------------------------------
 
-    /** GET /api/plugins/contacts/contacts - supports ?q=, ?group=, ?favourites=true */
-    fastify.get('/contacts', {preHandler: [authenticate]}, async (request, reply) => {
+    /** GET /api/contacts/contacts - supports ?q=, ?group=, ?favourites=true */
+    fastify.get('/contacts', {preHandler: [authenticate, requirePermission('contacts', 'read')]}, async (request, reply) => {
         const uid = userId(request);
         const { q, group, favourites } = request.query;
 
@@ -267,8 +288,8 @@ export default async function contactsPlugin(fastify, options) {
         return reply.send(result);
     });
 
-    /** POST /api/plugins/contacts/contacts */
-    fastify.post('/contacts', {preHandler: [authenticate]}, async (request, reply) => {
+    /** POST /api/contacts/contacts */
+    fastify.post('/contacts', {preHandler: [authenticate, requirePermission('contacts', 'create')]}, async (request, reply) => {
         const uid = userId(request);
         const body = request.body ?? {};
 
@@ -282,8 +303,8 @@ export default async function contactsPlugin(fastify, options) {
         return reply.code(201).send(toContact(entry));
     });
 
-    /** PUT /api/plugins/contacts/contacts/:id */
-    fastify.put('/contacts/:id', {preHandler: [authenticate]}, async (request, reply) => {
+    /** PUT /api/contacts/contacts/:id */
+    fastify.put('/contacts/:id', {preHandler: [authenticate, requirePermission('contacts', 'update')]}, async (request, reply) => {
         const uid = userId(request);
         const { id } = request.params;
         const updates = request.body ?? {};
@@ -292,9 +313,16 @@ export default async function contactsPlugin(fastify, options) {
         if (!entry) return reply.code(404).send({error: 'Contact not found'});
         if (uid && entry.data.userId !== uid) return reply.code(404).send({error: 'Contact not found'});
 
+        // Coerced exactly as create (buildContact) does: the editor sends
+        // payment terms as the input's string and a PUT used to store "30"
+        // where a POST stores 30 - and a bare `favourite: "false"` was truthy.
+        const shaped = buildContact({...entry.data, ...updates}, entry.data.userId ?? null);
         const merged = {...entry.data};
-        for (const key of [...TEXT_FIELDS, 'groups', 'favourite', 'paymentTerms']) {
-            if (key in updates) merged[key] = updates[key];
+        for (const key of TEXT_FIELDS) {
+            if (key in updates) merged[key] = shaped[key];
+        }
+        for (const key of ['groups', 'favourite', 'paymentTerms']) {
+            if (key in updates) merged[key] = shaped[key];
         }
         for (const key of LIST_FIELDS) {
             if (key in updates) merged[key] = cleanList(key, updates[key]);
@@ -304,8 +332,8 @@ export default async function contactsPlugin(fastify, options) {
         return reply.send(toContact(updated));
     });
 
-    /** DELETE /api/plugins/contacts/contacts/bulk - must be before /:id */
-    fastify.delete('/contacts/bulk', {preHandler: [authenticate]}, async (request, reply) => {
+    /** DELETE /api/contacts/contacts/bulk - must be before /:id */
+    fastify.delete('/contacts/bulk', {preHandler: [authenticate, requirePermission('contacts', 'delete')]}, async (request, reply) => {
         const uid = userId(request);
         const { ids } = request.body ?? {};
 
@@ -326,8 +354,8 @@ export default async function contactsPlugin(fastify, options) {
         return reply.send({ deleted });
     });
 
-    /** DELETE /api/plugins/contacts/contacts/:id */
-    fastify.delete('/contacts/:id', {preHandler: [authenticate]}, async (request, reply) => {
+    /** DELETE /api/contacts/contacts/:id */
+    fastify.delete('/contacts/:id', {preHandler: [authenticate, requirePermission('contacts', 'delete')]}, async (request, reply) => {
         const uid = userId(request);
         const { id } = request.params;
 
@@ -340,13 +368,13 @@ export default async function contactsPlugin(fastify, options) {
     });
 
     /**
-     * GET /api/plugins/contacts/contacts/:id/billing
+     * GET /api/contacts/contacts/:id/billing
      *
      * The contact as the Invoice plugin wants a receiver: same field names, so
      * the body can go straight to POST /api/plugins/invoice/receivers. Nothing
      * in the CMS calls this yet - it is the seam, put where the data is.
      */
-    fastify.get('/contacts/:id/billing', {preHandler: [authenticate]}, async (request, reply) => {
+    fastify.get('/contacts/:id/billing', {preHandler: [authenticate, requirePermission('contacts', 'read')]}, async (request, reply) => {
         const uid = userId(request);
         const entry = await getEntry(CONTACTS_SLUG, request.params.id);
         if (!entry) return reply.code(404).send({error: 'Contact not found'});
@@ -358,14 +386,14 @@ export default async function contactsPlugin(fastify, options) {
     // Groups CRUD
     // -------------------------------------------------------------------------
 
-    /** GET /api/plugins/contacts/groups */
-    fastify.get('/groups', {preHandler: [authenticate]}, async (request, reply) => {
+    /** GET /api/contacts/groups */
+    fastify.get('/groups', {preHandler: [authenticate, requirePermission('contacts', 'read')]}, async (request, reply) => {
         const groups = await loadGroups();
         return reply.send(groups.map(g => g.name));
     });
 
-    /** POST /api/plugins/contacts/groups */
-    fastify.post('/groups', {preHandler: [authenticate]}, async (request, reply) => {
+    /** POST /api/contacts/groups */
+    fastify.post('/groups', {preHandler: [authenticate, requirePermission('contacts', 'create')]}, async (request, reply) => {
         const { name } = request.body ?? {};
 
         if (!name || typeof name !== 'string' || !name.trim()) {
@@ -382,8 +410,8 @@ export default async function contactsPlugin(fastify, options) {
         return reply.code(201).send({ name: trimmed });
     });
 
-    /** PUT /api/plugins/contacts/groups/:name - rename + cascade */
-    fastify.put('/groups/:name', {preHandler: [authenticate]}, async (request, reply) => {
+    /** PUT /api/contacts/groups/:name - rename + cascade */
+    fastify.put('/groups/:name', {preHandler: [authenticate, requirePermission('contacts', 'update')]}, async (request, reply) => {
         const oldName = decodeURIComponent(request.params.name);
         const { newName } = request.body ?? {};
 
@@ -418,8 +446,8 @@ export default async function contactsPlugin(fastify, options) {
         return reply.send({ name: trimmed });
     });
 
-    /** DELETE /api/plugins/contacts/groups/:name - delete + cascade */
-    fastify.delete('/groups/:name', {preHandler: [authenticate]}, async (request, reply) => {
+    /** DELETE /api/contacts/groups/:name - delete + cascade */
+    fastify.delete('/groups/:name', {preHandler: [authenticate, requirePermission('contacts', 'delete')]}, async (request, reply) => {
         const name = decodeURIComponent(request.params.name);
 
         const groups = await loadGroups();
@@ -448,8 +476,8 @@ export default async function contactsPlugin(fastify, options) {
     // Import / Export
     // -------------------------------------------------------------------------
 
-    /** GET /api/plugins/contacts/export */
-    fastify.get('/export', {preHandler: [authenticate]}, async (request, reply) => {
+    /** GET /api/contacts/export */
+    fastify.get('/export', {preHandler: [authenticate, requirePermission('contacts', 'read')]}, async (request, reply) => {
         const uid = userId(request);
         const contacts = await loadContacts(uid);
         return reply
@@ -457,8 +485,8 @@ export default async function contactsPlugin(fastify, options) {
             .send(contacts);
     });
 
-    /** POST /api/plugins/contacts/import */
-    fastify.post('/import', {preHandler: [authenticate]}, async (request, reply) => {
+    /** POST /api/contacts/import */
+    fastify.post('/import', {preHandler: [authenticate, requirePermission('contacts', 'create')]}, async (request, reply) => {
         const uid = userId(request);
         const { contacts: incoming } = request.body ?? {};
 

package/server/routes/api/dashboard.js

@@ -281,7 +281,10 @@ export async function dashboardRoutes(fastify, opts = {}) {
         // are recorded. Read the plugin's daily counters straight off disk (same
         // pattern as buildActivity reading versions/collections below).
         const daily = (await safe('analytics.daily', async () => {
-            for (const rel of ['plugins/analytics/data/daily.json', 'plugins/analytics/daily.json']) {
+            // content/analytics/ is where the counters live since analytics became
+            // core. The plugin paths stay as a fallback for one release: a site
+            // that has not restarted yet still has its history under plugins/.
+            for (const rel of ['content/analytics/daily.json', 'plugins/analytics/data/daily.json', 'plugins/analytics/daily.json']) {
                 try { return JSON.parse(await fs.readFile(path.join(ROOT, rel), 'utf8')); }
                 catch { /* try next location */ }
             }
@@ -305,7 +308,10 @@ export async function dashboardRoutes(fastify, opts = {}) {
 
         // Session events read straight off disk too (same reason as daily above).
         const journeysData = (await safe('analytics.journeysData', async () => {
-            for (const rel of ['plugins/analytics/data/journeys.json', 'plugins/analytics/journeys.json']) {
+            // content/analytics/ is where the counters live since analytics became
+            // core. The plugin paths stay as a fallback for one release: a site
+            // that has not restarted yet still has its history under plugins/.
+            for (const rel of ['content/analytics/journeys.json', 'plugins/analytics/data/journeys.json', 'plugins/analytics/journeys.json']) {
                 try { return JSON.parse(await fs.readFile(path.join(ROOT, rel), 'utf8')); }
                 catch { /* try next location */ }
             }

package/{plugins/notes/plugin.js → server/routes/api/notes.js}

@@ -1,5 +1,23 @@
-import defaultConfig from './config.js';
-import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../../server/services/collections.js';
+/**
+ * Notes API - /api/notes
+ *
+ * Was the `notes` plugin until 0.67.0. The logic is unchanged; what moved is
+ * where it lives and how it is gated.
+ *
+ * **Per-user scope.** Entries carry a `userId` and every read is filtered to the
+ * caller's own. The plugin made this configurable (`scope: 'user' | 'site'`) and
+ * no install ever set it to anything else, so it is a constant here. Note this
+ * is hand-filtering rather than `rowAccess.js`, which is the mechanism core has
+ * for exactly this - moving onto it is a behaviour change and belongs in its own
+ * task, not smuggled into a relocation.
+ *
+ * **The collection slug is `notes-notes`, not the directory it used to sit in.**
+ * `setupPlugin()` read `schema.slug`, so the live collection has always been
+ * called this, and existing entries are found only if it stays exactly so.
+ */
+import {ago, clip, plural} from '../../services/sidebarBadges.js';
+import {authenticate as defaultAuthenticate, requirePermission as defaultRequirePermission} from '../../middleware/auth.js';
+import {createEntry, deleteEntry, getEntry, listEntries, updateEntry} from '../../services/collections.js';
 
 const SLUG = 'notes-notes';
 
@@ -14,13 +32,20 @@ function toNote(entry) {
     };
 }
 
-export default async function notesPlugin(fastify, options) {
-    const { authenticate } = options.auth;
-    const config = {...defaultConfig, ...(options.settings || {})};
-    const scope = config.scope ?? 'user';
+/**
+ * Auth is injectable so a test can drive these routes without registering
+ * @fastify/jwt or a role store - the same shape dashboard.js and plugins.js use.
+ *
+ * @param {import('fastify').FastifyInstance} fastify
+ * @param {object} [opts]
+ */
+export async function notesRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requirePermission = opts.requirePermission || defaultRequirePermission;
+
 
     function userId(request) {
-        return scope === 'user' ? (request.user?.id ?? request.user?.sub ?? null) : null;
+        return request.user?.id ?? request.user?.sub ?? null;
     }
 
     async function loadAll(uid) {
@@ -30,8 +55,27 @@ export default async function notesPlugin(fastify, options) {
         return items;
     }
 
-    /** GET /api/plugins/notes/items - supports ?q= and ?category= */
-    fastify.get('/items', { preHandler: [authenticate] }, async (request, reply) => {
+    /** GET /api/notes/count - the sidebar badge: how many notes this user has. */
+    fastify.get('/count', {preHandler: [authenticate, requirePermission('notes', 'read')]}, async (request) => {
+        const notes = await loadAll(userId(request));    // newest edit first
+        const categories = new Set(notes.flatMap(n => (Array.isArray(n.categories) ? n.categories : []).map(c => String(c).toLowerCase())));
+        return {
+            count: notes.length, label: plural(notes.length, 'note'), tone: 'info',
+            details: {
+                title: 'Notes',
+                rows: [
+                    {label: 'Notes', value: String(notes.length)},
+                    {label: 'Categories', value: String(categories.size)},
+                    {label: 'Edited this week', value: String(notes.filter(n => Date.now() - new Date(n.updatedAt).getTime() < 7 * 86_400_000).length)}
+                ],
+                items: notes.slice(0, 4).map(n => ({text: clip(n.title || n.content || 'Untitled'), meta: `edited ${ago(n.updatedAt)}`})),
+                empty: 'No notes yet.'
+            }
+        };
+    });
+
+    /** GET /api/notes/items - supports ?q= and ?category= */
+    fastify.get('/items', {preHandler: [authenticate, requirePermission('notes', 'read')]}, async (request, reply) => {
         const uid = userId(request);
         const { q, category } = request.query;
 
@@ -55,8 +99,8 @@ export default async function notesPlugin(fastify, options) {
         return reply.send(items);
     });
 
-    /** POST /api/plugins/notes/items */
-    fastify.post('/items', { preHandler: [authenticate] }, async (request, reply) => {
+    /** POST /api/notes/items */
+    fastify.post('/items', {preHandler: [authenticate, requirePermission('notes', 'create')]}, async (request, reply) => {
         const uid = userId(request);
         const { title, content, categories } = request.body ?? {};
 
@@ -72,8 +116,8 @@ export default async function notesPlugin(fastify, options) {
         return reply.code(201).send(toNote(entry));
     });
 
-    /** PUT /api/plugins/notes/items/:id */
-    fastify.put('/items/:id', { preHandler: [authenticate] }, async (request, reply) => {
+    /** PUT /api/notes/items/:id */
+    fastify.put('/items/:id', {preHandler: [authenticate, requirePermission('notes', 'update')]}, async (request, reply) => {
         const uid = userId(request);
         const { id } = request.params;
         const { title, content, categories } = request.body ?? {};
@@ -95,8 +139,8 @@ export default async function notesPlugin(fastify, options) {
         return reply.send(toNote(updated));
     });
 
-    /** DELETE /api/plugins/notes/items/:id */
-    fastify.delete('/items/:id', { preHandler: [authenticate] }, async (request, reply) => {
+    /** DELETE /api/notes/items/:id */
+    fastify.delete('/items/:id', {preHandler: [authenticate, requirePermission('notes', 'delete')]}, async (request, reply) => {
         const uid = userId(request);
         const { id } = request.params;
 
@@ -108,8 +152,8 @@ export default async function notesPlugin(fastify, options) {
         return reply.send({ success: true });
     });
 
-    /** GET /api/plugins/notes/categories */
-    fastify.get('/categories', { preHandler: [authenticate] }, async (request, reply) => {
+    /** GET /api/notes/categories */
+    fastify.get('/categories', {preHandler: [authenticate, requirePermission('notes', 'read')]}, async (request, reply) => {
         const uid = userId(request);
         const items = await loadAll(uid);
         const cats = new Set();