domma-cms 0.92.1 → 0.94.0

package/server/services/markdown.js

@@ -20,15 +20,24 @@ import {buildTextStyle} from '../../public/js/text-style.mjs';
 const __dirname_md = path.dirname(fileURLToPath(import.meta.url));
 const BLOCKS_DIR = path.resolve(__dirname_md, '../../content/blocks');
 
-const BUILTIN_SHORTCODES = new Set([
-    'block', 'collection', 'view', 'dconfig', 'effect', 'tabs', 'tab',
+/**
+ * Tag names the pipeline owns, so a block template with one of these names is
+ * never treated as a block short tag (`[name /]`). Keep in step with the
+ * processors in parseMarkdown() when adding a shortcode.
+ */
+export const BUILTIN_SHORTCODES = new Set([
+    'block', 'collection', 'view', 'dconfig', 'component', 'tabs', 'tab',
     'accordion', 'item', 'carousel', 'slide', 'countdown', 'timeline',
-    'event', 'spacer', 'center', 'icon', 'form', 'hero', 'table', 'badge',
+    'event', 'listgroup', 'spacer', 'center', 'icon', 'demo', 'embed', 'form', 'hero', 'table', 'badge',
     'text', 'button', 'link', 'cta', 'grid', 'row', 'col', 'card', 'box',
-    'banner', 'slideover', 'counter', 'celebrate', 'firework', 'fireworks', 'scribe',
+    'banner', 'slideover', 'menu',
+    // effects
+    'counter', 'celebrate', 'firework', 'fireworks', 'scribe',
     'reveal', 'breathe', 'pulse', 'shake', 'scramble', 'ripple', 'twinkle',
-    'ticker-tape', 'butterflies', 'strobe', 'animate', 'ambient', 'list-group', 'menu',
-    'demo',
+    'ticker-tape', 'butterflies', 'strobe', 'animate', 'ambient',
+    // named celebrations - sugar for [celebrate theme="…"]
+    'christmas', 'halloween', 'st-patricks', 'valentines', 'guy-fawkes',
+    'st-andrews', 'st-davids', 'st-georges',
 ]);
 
 // Configure marked for safe output
@@ -380,6 +389,7 @@ function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts, cols,
             let btnCls = `btn btn-${ctaStyle} dm-cta-trigger`;
             let btnData = `data-action="${escapeAttr(ctaOpts.action)}" data-entry="${escapeAttr(e.id || '')}"`;
             if (ctaOpts.confirm) btnData += ` data-confirm="${escapeAttr(ctaOpts.confirm)}"`;
+            if (ctaOpts.scope) btnData += ` data-scope="${escapeAttr(ctaOpts.scope)}"`;
             const iconHtml = ctaOpts.icon ? `<span data-icon="${escapeAttr(ctaOpts.icon)}"></span> ` : '';
             html += `\n<button class="${btnCls}" ${btnData}>${iconHtml}${escapeHtmlText(ctaOpts.label || 'Run')}</button>`;
         }
@@ -607,6 +617,7 @@ function renderCollectionCards(entries, visibleFields, titleField, columns, empt
             let btnCls = `btn btn-${ctaStyle} dm-cta-trigger`;
             let btnData = `data-action="${escapeAttr(ctaOpts.action)}" data-entry="${escapeAttr(e.id || '')}"`;
             if (ctaOpts.confirm) btnData += ` data-confirm="${escapeAttr(ctaOpts.confirm)}"`;
+            if (ctaOpts.scope) btnData += ` data-scope="${escapeAttr(ctaOpts.scope)}"`;
             const iconHtml = ctaOpts.icon ? `<span data-icon="${escapeAttr(ctaOpts.icon)}"></span> ` : '';
             footer = `<div class="card-footer"><button class="${btnCls}" ${btnData}>${iconHtml}${escapeHtmlText(ctaOpts.label || 'Run')}</button></div>`;
         }
@@ -634,6 +645,7 @@ function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaO
             let btnCls = `btn btn-${ctaStyle} dm-cta-trigger`;
             let btnData = `data-action="${escapeAttr(ctaOpts.action)}" data-entry="${escapeAttr(e.id || '')}"`;
             if (ctaOpts.confirm) btnData += ` data-confirm="${escapeAttr(ctaOpts.confirm)}"`;
+            if (ctaOpts.scope) btnData += ` data-scope="${escapeAttr(ctaOpts.scope)}"`;
             const iconHtml = ctaOpts.icon ? `<span data-icon="${escapeAttr(ctaOpts.icon)}"></span> ` : '';
             ctaHtml = `<button class="${btnCls}" ${btnData}>${iconHtml}${escapeHtmlText(ctaOpts.label || 'Run')}</button>`;
         }
@@ -1116,7 +1128,7 @@ async function processCollectionBlocks(markdown, tagSet) {
         // a server-rendered fragment as the no-JS fallback (visible until the
         // browser hydrates and replaces it).
         if (isInteractiveCollection(attrs)) {
-            const shell = await renderCollectionBrowserShell(attrs, schemaForFallback => schemaForFallback);
+            const shell = await renderCollectionBrowserShell(attrs);
             result = result.replace(fullMatch, shell);
             continue;
         }
@@ -1128,6 +1140,25 @@ async function processCollectionBlocks(markdown, tagSet) {
     return restore(result);
 }
 
+/**
+ * Render a `[collection scope="mine"]` for one signed-in viewer - what
+ * `POST /api/collections/render-scope` returns. The rows are always those the
+ * viewer created (`createdBy = userId`, set here, never by the client). An
+ * interactive block (searchable / sortable / filterable / paginate) comes back
+ * as a Collection Browser shell, so `transitions` works on it; anything else
+ * as the static fragment.
+ *
+ * @param {Record<string, string>} attrs - Parsed shortcode attributes
+ * @param {string} userId
+ * @returns {Promise<string>}
+ */
+export async function renderScopedCollection(attrs, userId) {
+    const opts = {extraFilter: {createdBy: userId}, scope: 'mine'};
+    return isInteractiveCollection(attrs)
+        ? renderCollectionBrowserShell(attrs, opts)
+        : renderCollectionFragment(attrs, opts);
+}
+
 /**
  * Detect whether a `[collection]` shortcode opts into the interactive Browser.
  * Any of `searchable`, `sortable`, `filterable`, or `paginate` flips it on.
@@ -1171,10 +1202,19 @@ function isTruthyAttr(v) {
  * A static server-rendered fragment is also embedded as the no-JS fallback -
  * visible until `collection-browser.js` hydrates and replaces the shell.
  *
+ * With `scope: 'mine'` (render-scope, for `[collection scope="mine"]`) the
+ * shell is built for one viewer: `extraFilter` (`createdBy = <user id>`) is
+ * ANDed into the seed and the fallback, and `config.scope` makes the browser
+ * ask for `scope=mine` on every later fetch, transition list and action run,
+ * so the server keeps the viewer to their own rows throughout.
+ *
  * @param {Record<string, string>} attrs - Parsed shortcode attributes
+ * @param {object} [opts]
+ * @param {Record<string, unknown>} [opts.extraFilter] - ANDed into every listing
+ * @param {string} [opts.scope] - 'mine' for a per-viewer shell
  * @returns {Promise<string>} HTML for the hydration shell
  */
-async function renderCollectionBrowserShell(attrs) {
+async function renderCollectionBrowserShell(attrs, {extraFilter = null, scope = ''} = {}) {
     const slug = attrs.slug;
     const pageSize = parseInt(attrs['page-size'], 10) || 12;
     const declaredMode = attrs.mode === 'server' ? 'server' : 'client';
@@ -1198,6 +1238,7 @@ async function renderCollectionBrowserShell(attrs) {
         // Build the seed listEntries() opts - push any author-baked where_* filter
         // and the initial sort/order down to the adapter, just like the static path.
         const seedFilter = buildShortcodeFilter(attrs);
+        if (extraFilter) Object.assign(seedFilter, extraFilter);
         const seedOpts   = {
             sort:  attrs.sort  || 'createdAt',
             order: attrs.order || 'desc'
@@ -1263,6 +1304,7 @@ async function renderCollectionBrowserShell(attrs) {
         exportable:  isTruthyAttr(attrs.exportable),               // adds "Export CSV" button
         savedSearches: !isTruthyAttr(attrs['no-saved-searches']),  // opt-out flag (defaults on)
         transitions: isTruthyAttr(attrs.transitions),              // render per-row transition buttons
+        scope:       scope === 'mine' ? 'mine' : '',               // per-viewer shell (render-scope)
         emptyMsg:    attrs.empty || 'No entries found',
         cta:         attrs.cta ? {
             action:  attrs.cta,
@@ -1278,7 +1320,7 @@ async function renderCollectionBrowserShell(attrs) {
 
     // No-JS fallback - render the same first-page state with the static renderer.
     const fallbackAttrs = {...attrs, limit: String(pageSize)};
-    const fallback      = await renderCollectionFragment(fallbackAttrs);
+    const fallback      = await renderCollectionFragment(fallbackAttrs, {extraFilter, scope});
 
     // Encode payloads. Schema can be modest; data can be large in client mode,
     // so we base64 once each and let the browser decode.
@@ -1420,9 +1462,10 @@ async function renderViewBrowserShell(attrs, {viewConfig = null, allowed = false
  * @param {Record<string, string>} attrs        - Parsed shortcode attributes
  * @param {object}                 [opts]
  * @param {Record<string, unknown>} [opts.extraFilter]  - Additional filter conditions to AND in
+ * @param {string}                 [opts.scope]        - 'mine': CTA buttons carry data-scope
  * @returns {Promise<string>} HTML fragment ready to inject into a page
  */
-export async function renderCollectionFragment(attrs, { extraFilter = null } = {}) {
+export async function renderCollectionFragment(attrs, { extraFilter = null, scope = '' } = {}) {
     const slug = attrs.slug || '';
     if (!slug) return '';
 
@@ -1440,7 +1483,10 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
         label:   attrs['cta-label']   || 'Run',
         icon:    attrs['cta-icon']    || '',
         style:   attrs['cta-style']   || 'primary',
-        confirm: attrs['cta-confirm'] || ''
+        confirm: attrs['cta-confirm'] || '',
+        // scope="mine": the button tells the server so, and a row outside the
+        // viewer's scope is refused when the action runs (entryInScope).
+        ...(scope === 'mine' && {scope: 'mine'})
     } : null;
 
     let replacement = `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
@@ -4221,10 +4267,13 @@ export async function parseMarkdown(raw, opts = {}) {
   const {data, content} = matter(raw);
   const extensions = getSanitizeExtensions();
 
-  // Pipeline:
-    // beforeParse → collection → view → staticBlock → menu → dconfig → effects → plugin shortcodes → tabs → accordion → carousel
-  //   → countdown → timeline → spacer → center → icon → form → hero → table → badge → button → link → cta
-  //   → grid → card → slideover → marked → sanitize → afterParse
+  // Pipeline (earlier stages are already HTML when later ones run; keep in step
+  // with "Shortcode Nesting Rules" in CLAUDE.md and docs/markdown-shortcodes.md):
+  //   beforeParse → components ([component] / <dm-*>) → collection → view → block (+ short tags) → menu
+  //   → dconfig → effects → plugin shortcodes → tabs → accordion → carousel → countdown → timeline
+  //   → listgroup → spacer → center → icon → demo → embed → form → hero → table
+  //   → badge → text → button → link → cta → grid → card (+ box) → banner → slideover
+  //   → marked → sanitize → afterParse
   const preprocessed = applyTransforms('markdown:beforeParse', content);
   const {output: withComponents, used: usedComponents} = collectAndRewriteComponents(preprocessed);
   const tagSet = new Set();
@@ -4237,19 +4286,19 @@ export async function parseMarkdown(raw, opts = {}) {
       : {};
   const withMenu = await processMenuBlocks(withStaticBlock, opts.user || null, menuCtx);
   const withDconfig = processDConfigBlocks(withMenu);
-    const withEffects = processEffectsBlocks(withDconfig);
-    const withPluginShortcodes = await processPluginShortcodes(withEffects);
+  const withEffects = processEffectsBlocks(withDconfig);
+  const withPluginShortcodes = await processPluginShortcodes(withEffects);
   const withTabs = processTabsBlocks(withPluginShortcodes);
   const withAccordion = processAccordionBlocks(withTabs);
   const withCarousel = processCarouselBlocks(withAccordion);
   const withCountdown = processCountdownBlocks(withCarousel);
   const withTimeline = processTimelineBlocks(withCountdown);
-    const withListGroup = processListGroupBlocks(withTimeline);
-    const withSpacer = processSpacerBlocks(withListGroup);
-    const withCenter = processCenterBlocks(withSpacer);
-    const withIcon = processIconBlocks(withCenter);
-    const withDemo = processDemoBlocks(withIcon);
-    const withEmbed = processEmbedBlocks(withDemo);
+  const withListGroup = processListGroupBlocks(withTimeline);
+  const withSpacer = processSpacerBlocks(withListGroup);
+  const withCenter = processCenterBlocks(withSpacer);
+  const withIcon = processIconBlocks(withCenter);
+  const withDemo = processDemoBlocks(withIcon);
+  const withEmbed = processEmbedBlocks(withDemo);
   const withForm = await processFormBlocks(withEmbed, tagSet);
   const withHero = processHeroBlocks(withForm);
   const withTable = processTableBlocks(withHero);
@@ -4257,11 +4306,11 @@ export async function parseMarkdown(raw, opts = {}) {
   const withText   = processTextBlocks(withBadge);
   const withButton = processButtonBlocks(withText);
   const withLink   = processLinkBlocks(withButton);
-    const withCta = processCtaBlocks(withLink);
+  const withCta = processCtaBlocks(withLink);
   const withGrid = processGridBlocks(withCta);
   const withCard = processCardBlocks(withGrid);
-    const withBanner = processBannerBlocks(withCard);
-    const withSlideover = processSlideoverBlocks(withBanner);
+  const withBanner = processBannerBlocks(withCard);
+  const withSlideover = processSlideoverBlocks(withBanner);
   const rendered = marked.parse(withSlideover);
 
   const sanitized = sanitizeHtml(rendered, {

package/server/services/notification-sources.js

@@ -19,6 +19,7 @@ import fs from 'fs';
 import path from 'path';
 import {config, getConfig} from '../config.js';
 import {notify, registerNotificationSource, resolveNotification} from './notify.js';
+import {fmtDate, fmtDateTime} from './dates.js';
 
 const day = (d = new Date()) => d.toISOString().slice(0, 10);
 
@@ -37,7 +38,7 @@ const day = (d = new Date()) => d.toISOString().slice(0, 10);
  */
 export function licenceNotice(name, label, verdict, now = new Date()) {
     const e = verdict?.entitlement || {};
-    const ends = (iso) => String(iso || '').slice(0, 10);
+    const ends = (iso) => fmtDate(iso, {utc: true});
     switch (verdict?.state) {
         case 'unlicensed':
             return {severity: 'critical', title: `${label} is not running: no valid licence`,
@@ -48,7 +49,7 @@ export function licenceNotice(name, label, verdict, now = new Date()) {
         case 'grace': {
             const graceEnd = new Date(Date.parse(e.expiresAt) + (Number(e.gracePeriodDays) || 0) * 86_400_000);
             return {severity: 'warning', title: `${label} licence has expired`,
-                body: `The ${label} licence ended on ${ends(e.expiresAt)}. It keeps working until ${day(graceEnd)}, then stops. Renew it before then.`};
+                body: `The ${label} licence ended on ${ends(e.expiresAt)}. It keeps working until ${fmtDate(graceEnd, {utc: true})}, then stops. Renew it before then.`};
         }
         case 'support-ended':
             return {severity: 'info', title: `${label}: support and updates have ended`,
@@ -78,9 +79,9 @@ export function tokenNotice(data, now = new Date()) {
     const name = data.name || 'An API token';
     return left < 0
         ? {severity: 'warning', title: `API token "${name}" has expired`,
-            body: `It expired on ${String(data.expiresAt).slice(0, 10)}. Anything still using it is being refused - issue a new one in API Tokens.`}
+            body: `It expired on ${fmtDate(data.expiresAt, {utc: true})}. Anything still using it is being refused - issue a new one in API Tokens.`}
         : {severity: 'warning', title: `API token "${name}" expires in ${left} day${left === 1 ? '' : 's'}`,
-            body: `It expires on ${String(data.expiresAt).slice(0, 10)}. Anything using it will be refused after that - extend it or issue a new one in API Tokens.`};
+            body: `It expires on ${fmtDate(data.expiresAt, {utc: true})}. Anything using it will be refused after that - extend it or issue a new one in API Tokens.`};
 }
 
 /** Sign-in failures: this many for one account inside the window is worth telling. */
@@ -242,7 +243,7 @@ export async function registerCoreSources() {
             try { fs.rmSync(crashMarker(), {force: true}); } catch { /* raised once anyway: dedupe */ }
             await raise({severity: 'critical', dedupeKey: `crash:${marker.at}`,
                 title: 'The site restarted after a crash',
-                body: `It stopped on an unexpected error at ${String(marker.at).replace('T', ' ').slice(0, 16)} UTC and was started again.\n\n${marker.message}`});
+                body: `It stopped on an unexpected error at ${fmtDateTime(marker.at, {utc: true})} UTC and was started again.\n\n${marker.message}`});
         }
     });
 

package/server/services/passwordReset.js

@@ -40,6 +40,7 @@ import {config, getConfig} from '../config.js';
 import {hooks} from './hooks.js';
 import {getUserByEmail, getUserById, getUserByResetToken, setResetToken} from './users.js';
 import * as email from './email.js';
+import {fmtDateTime} from './dates.js';
 
 export const ORIGINS_FILE = path.resolve(path.dirname(config.content.usersDir), 'sessions', 'origins.json');
 const MAX_ORIGINS = 20;
@@ -482,7 +483,7 @@ export async function passwordChangedNotice({userId, by}) {
     if (!mailer.isSmtpConfigured(site.smtp)) return {sent: false, reason: 'no-smtp'};
     const how = by === 'reset' ? 'reset' : by === userId ? 'self' : 'admin';
     const origin = await trustedOrigin('');
-    const when = new Date().toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+    const when = `${fmtDateTime(new Date(), {utc: true})} UTC`;
     const message = buildChangedEmail({name: user.name, how, when, siteTitle: site.title,
         signInUrl: origin ? `${origin}/admin/#/login` : ''});
     const transport = await mailer.createTransport(site.smtp);

package/server/services/permissionRegistry.js

@@ -212,7 +212,8 @@ export const REGISTRY = [
             {key: 'read', label: 'View', description: 'View own contacts'},
             {key: 'create', label: 'Create', description: 'Add contacts and groups'},
             {key: 'update', label: 'Edit', description: 'Edit own contacts'},
-            {key: 'delete', label: 'Delete', description: 'Delete own contacts'}
+            {key: 'delete', label: 'Delete', description: 'Delete own contacts'},
+            {key: 'manageGroups', label: 'Manage groups', description: 'Rename or delete any group, not only the ones they created - groups are shared, so this changes everyone\'s contacts'}
         ]
     },
     {
@@ -384,7 +385,7 @@ export const RESOURCES = REGISTRY.map(r => r.key);
 export const ACTIONS = ['read', 'create', 'update', 'delete'];
 
 /** Display order for permission groups. */
-export const GROUP_ORDER = ['Content', 'Structure', 'Data', 'Configuration', 'Plugins'];
+export const GROUP_ORDER = ['Content', 'Structure', 'Data', 'Configuration', 'Tools', 'Plugins'];
 
 /**
  * Return the action keys defined for a given resource (base or plugin-contributed).

package/server/services/pluginGuides.js

@@ -0,0 +1,255 @@
+/**
+ * Plugin guides - user documentation a plugin ships for the admin's
+ * Documentation folder.
+ *
+ * A plugin puts Markdown files in `plugins/<name>/docs/*.md`. When the plugin
+ * is loaded (enabled, licensed, not superseded), each file becomes a page under
+ * Documentation > Plugins in the admin sidebar (`#/docs/plugins/<name>`), shown
+ * to users who can use the plugin: the manifest's `docs.permission`, else the
+ * permission on its first `admin.sidebar` entry that names one, else anyone
+ * signed in to the admin.
+ *
+ * Files are plain Markdown with optional frontmatter `title` (the tab label)
+ * and `order` (a number, lowest first; `guide.md` comes first by default).
+ * Shortcodes are NOT run - a guide shows `[collection ...]` examples literally,
+ * which is what a guide wants. The HTML is sanitised like any other page body.
+ *
+ * Pure helpers are exported for tests; the registry is module state filled once
+ * per boot by registerPluginGuides() (plugins load at boot only).
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import matter from 'gray-matter';
+import {marked} from 'marked';
+import sanitizeHtml from 'sanitize-html';
+import {registerSidebarItem} from './hooks.js';
+
+/** The Documentation folder's key in the admin-sidebar menu. */
+export const DOCS_FOLDER_KEY = 'documentation';
+/** Identity (url) of the Plugins sub-folder and its landing page. */
+export const GUIDES_URL = '#/docs/plugins';
+
+const SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/i;
+
+/** name -> {name, displayName, description, icon, version, permission, toolUrl, dir, pages: [{slug, title, order, file}]} */
+let _guides = new Map();
+
+/**
+ * Who may read a plugin's guides: `docs.permission`, else the first sidebar
+ * entry's permission, else null (anyone signed in to the admin).
+ *
+ * @param {object} manifest
+ * @returns {string|null}
+ */
+export function guidePermission(manifest) {
+    const explicit = manifest?.docs?.permission;
+    if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+    const entry = (manifest?.admin?.sidebar || []).find(s => typeof s?.permission === 'string' && s.permission);
+    return entry ? entry.permission : null;
+}
+
+/**
+ * Does this permission list cover `resource`? Same rule as the sidebar's canAny:
+ * the bare resource or any of its actions.
+ *
+ * @param {string[]} permissions
+ * @param {string|null} resource
+ * @returns {boolean}
+ */
+export function canUse(permissions, resource) {
+    if (!resource) return true;
+    if (!Array.isArray(permissions) || !permissions.length) return false;
+    if (permissions.includes(resource)) return true;
+    return ['read', 'create', 'update', 'delete'].some(a => permissions.includes(`${resource}.${a}`));
+}
+
+/** "shipping-zones" -> "Shipping zones"; "guide" -> "Guide". */
+export function titleFromSlug(slug) {
+    const words = String(slug || '').replace(/^\d+[-_]/, '').replace(/[-_]+/g, ' ').trim();
+    return words ? words.charAt(0).toUpperCase() + words.slice(1) : 'Guide';
+}
+
+/**
+ * Parse one guide file's source into its page meta.
+ *
+ * @param {string} slug - file name without `.md`
+ * @param {string} source
+ * @returns {{slug: string, title: string, order: number}}
+ */
+export function pageMeta(slug, source) {
+    let data = {};
+    try { data = matter(source).data || {}; } catch { data = {}; }
+    const title = typeof data.title === 'string' && data.title.trim() ? data.title.trim() : titleFromSlug(slug);
+    const order = Number.isFinite(Number(data.order)) && data.order !== null && data.order !== ''
+        ? Number(data.order)
+        : (slug === 'guide' ? 0 : 100);
+    return {slug, title, order};
+}
+
+/** Pages sorted by order, then slug. */
+export function sortPages(pages) {
+    return [...pages].sort((a, b) => (a.order - b.order) || a.slug.localeCompare(b.slug));
+}
+
+const SANITIZE = {
+    allowedTags: [...sanitizeHtml.defaults.allowedTags, 'img', 'h1', 'h2', 'del', 'details', 'summary'],
+    allowedAttributes: {
+        a: ['href', 'title', 'target', 'rel'],
+        img: ['src', 'alt', 'title', 'width', 'height'],
+        code: ['class'],
+        table: ['class'],
+        th: ['align', 'style'],
+        td: ['align', 'style'],
+        ol: ['start']
+    },
+    allowedStyles: {th: {'text-align': [/^(left|right|center)$/]}, td: {'text-align': [/^(left|right|center)$/]}},
+    allowedSchemes: ['http', 'https', 'mailto'],
+    transformTags: {
+        // Links leaving the admin open in a new tab; hash links stay in the SPA.
+        a: (tagName, attribs) => {
+            const href = attribs.href || '';
+            if (/^https?:\/\//i.test(href)) return {tagName, attribs: {...attribs, target: '_blank', rel: 'noopener noreferrer'}};
+            return {tagName, attribs};
+        },
+        table: () => ({tagName: 'table', attribs: {class: 'table table-sm'}})
+    }
+};
+
+/**
+ * Markdown -> sanitised HTML. Frontmatter is dropped; shortcodes are not run.
+ *
+ * @param {string} source
+ * @returns {string}
+ */
+export function renderGuide(source) {
+    let body = source;
+    try { body = matter(source).content; } catch { /* no frontmatter */ }
+    return sanitizeHtml(marked.parse(body, {gfm: true, async: false}), SANITIZE);
+}
+
+/**
+ * Read a plugin's `docs/` folder into page metas. Missing folder = no pages.
+ *
+ * @param {string} pluginDir
+ * @returns {Promise<Array<{slug, title, order, file}>>}
+ */
+export async function readGuidePages(pluginDir) {
+    const dir = path.join(pluginDir, 'docs');
+    let names;
+    try { names = await fs.readdir(dir); } catch { return []; }
+    const pages = [];
+    for (const name of names) {
+        if (!name.toLowerCase().endsWith('.md')) continue;
+        const slug = name.slice(0, -3);
+        if (!SLUG_RE.test(slug)) continue;
+        const file = path.join(dir, name);
+        try {
+            const source = await fs.readFile(file, 'utf8');
+            pages.push({...pageMeta(slug, source), file});
+        } catch { /* unreadable - skip */ }
+    }
+    return sortPages(pages);
+}
+
+/**
+ * The sidebar node for Documentation > Plugins: a folder of one link per
+ * plugin, each gated by that plugin's permission (the renderer drops the ones
+ * a user cannot use).
+ *
+ * @param {Array<object>} guides - registry values
+ * @returns {object|null}
+ */
+export function guidesSidebarItem(guides) {
+    if (!guides.length) return null;
+    return {
+        source: 'Built in',
+        text: 'Plugins',
+        url: GUIDES_URL,
+        icon: 'package',
+        items: [...guides]
+            .sort((a, b) => a.displayName.localeCompare(b.displayName))
+            .map(g => ({
+                text: g.displayName,
+                url: `${GUIDES_URL}/${g.name}`,
+                icon: g.icon || 'package',
+                ...(g.permission && {permission: g.permission})
+            }))
+    };
+}
+
+/**
+ * Collect the guides of the plugins that loaded and add the sidebar folder.
+ * Called once at boot, after registerPlugins() has loaded them.
+ *
+ * @param {object[]} manifests - manifests of LOADED plugins
+ * @param {string} pluginsDir
+ * @param {{register?: Function}} [opts] - sidebar registration (tests pass a stub)
+ * @returns {Promise<number>} how many plugins have guides
+ */
+export async function registerPluginGuides(manifests, pluginsDir, {register = registerSidebarItem} = {}) {
+    const next = new Map();
+    for (const manifest of manifests || []) {
+        if (!manifest?.name) continue;
+        const dir = path.join(pluginsDir, manifest.name);
+        const pages = await readGuidePages(dir);
+        if (!pages.length) continue;
+        next.set(manifest.name, {
+            name: manifest.name,
+            displayName: manifest.displayName || manifest.name,
+            description: manifest.description || '',
+            icon: manifest.icon || 'package',
+            version: manifest.version || '',
+            tier: manifest.tier || '',
+            permission: guidePermission(manifest),
+            toolUrl: (manifest.admin?.sidebar || []).find(s => s?.url)?.url || null,
+            pages
+        });
+    }
+    _guides = next;
+    const item = guidesSidebarItem([...next.values()]);
+    if (item) register({folder: DOCS_FOLDER_KEY, item});
+    return next.size;
+}
+
+/** Public shape of a guide (no file paths). */
+function publicGuide(g) {
+    const {pages, ...rest} = g;
+    return {...rest, pages: pages.map(({slug, title}) => ({slug, title}))};
+}
+
+/**
+ * Every guide this permission list may read.
+ *
+ * @param {string[]} permissions
+ * @returns {object[]}
+ */
+export function listGuides(permissions) {
+    return [...(_guides.values())]
+        .filter(g => canUse(permissions, g.permission))
+        .sort((a, b) => a.displayName.localeCompare(b.displayName))
+        .map(publicGuide);
+}
+
+/**
+ * One guide with one page rendered, or a reason it cannot be shown.
+ *
+ * @param {string} name
+ * @param {string|undefined} pageSlug - defaults to the first page
+ * @param {string[]} permissions
+ * @returns {Promise<{status: 200|403|404, guide?: object}>}
+ */
+export async function getGuide(name, pageSlug, permissions) {
+    const g = _guides.get(name);
+    if (!g) return {status: 404};
+    if (!canUse(permissions, g.permission)) return {status: 403};
+    const page = pageSlug ? g.pages.find(p => p.slug === pageSlug) : g.pages[0];
+    if (!page) return {status: 404};
+    let source;
+    try { source = await fs.readFile(page.file, 'utf8'); } catch { return {status: 404}; }
+    return {status: 200, guide: {...publicGuide(g), page: {slug: page.slug, title: page.title, html: renderGuide(source)}}};
+}
+
+/** Test seam: replace the registry. */
+export function _setGuidesForTest(list) {
+    _guides = new Map((list || []).map(g => [g.name, g]));
+}