domma-cms 1.6.60 → 1.7.0

package/docs/plugin-development.md

@@ -0,0 +1,827 @@
+# Plugin Development
+
+Plugins extend Domma CMS with new server-side routes, admin UI panels, and public-page injection snippets. Each plugin is a self-contained directory inside `plugins/`.
+
+---
+
+## Scaffolding a New Plugin
+
+The quickest start is the built-in scaffolder: **Admin → Marketplace → New Plugin**. It instantiates `plugins/_template/` into `plugins/<slug>/` - server entry, config defaults, a wired admin view (sidebar item, route, template, CSS) and a `CLAUDE.md` - with your name, description and icon substituted throughout. The plugin is created pre-enabled; restart the server to activate it (routes and admin views only register at boot).
+
+Programmatically: `POST /api/plugins/scaffold` with `{slug, displayName, description?, author?, icon?}` (requires the `plugins.create` permission). Slugs are lowercase letters, digits and hyphens; free-text fields may not contain `<`, `>`, `"`, backslash or `*/` since they are substituted into JSON, HTML and JS comment contexts.
+
+---
+
+## Editing a Plugin from the Admin
+
+Every plugin card has a **Code** button opening an in-admin editor (`#/plugins/code/<name>`): file tree on the left, monospace editor on the right, `Ctrl+S` to save, plus new-file and delete-file actions. The two reload rules are surfaced on save:
+
+- **`admin/` files** (views, templates, CSS) are fetched by the SPA - a hard refresh of the admin tab picks them up. No restart.
+- **Everything else** (`plugin.js`, `config.js`, `plugin.json`, `public/` snippets) is imported or read server-side - the editor flags these saves as restart-required. The header's **Restart Server** button restarts in place (the process exits cleanly and the supervisor - fleet manager, pm2, systemd - brings it back; unsupervised `node server/server.js` runs are warned first).
+
+**Enabling or disabling a plugin restarts the server automatically.** The same
+boot-only registration rule applies to the enabled flag, so the toggle on
+the admin Marketplace screen exits the process once the change is saved and waits for
+the supervisor to bring it back - no manual step. It restarts only where a
+supervisor is detected, and only when the flag actually changed (a settings save
+never does). Turn it off with `restartOnPluginToggle: false` in
+`config/server.json`; see [Configuration](configuration.md#configserverjson).
+
+Guard rails: everything is confined to `plugins/<name>/` (traversal and symlink escapes are refused), only text extensions (`.js .json .md .html .css .txt .svg`) are editable, `.json` saves must parse (and `plugin.json` must keep its `name` matching the directory), and the three required files cannot be deleted. Access needs the **`plugins.develop`** permission - deliberately separate from `plugins.update`, because editing plugin source is code execution on the server. Base admin roles have it (bare `plugins` grants expand to all actions); grant it to custom roles explicitly via the role editor.
+
+The scaffolded `CLAUDE.md` in each plugin also makes the directory a good target for a local Claude Code session if you prefer editing outside the browser.
+
+---
+
+## Required Structure
+
+Every plugin must have exactly these three files:
+
+```
+plugins/
+└── my-plugin/
+    ├── plugin.json   # Manifest (metadata + admin integration)
+    ├── plugin.js     # Fastify plugin entry point (ESM)
+    └── config.js     # Default settings export (ESM)
+```
+
+Any missing mandatory file causes a startup warning and the plugin is skipped - the server does not crash.
+
+Optional directories:
+
+```
+plugins/my-plugin/
+├── admin/            # Admin SPA views, templates and CSS (served at /plugins/my-plugin/admin/)
+│   ├── views/index.js
+│   ├── templates/index.html
+│   └── css/index.css
+├── public/           # Browser assets and inject snippets (served at /plugins/my-plugin/public/)
+│   ├── inject-head.html
+│   └── inject-body.html
+├── plugin.public.js  # Optional root-level public routes (e.g. /shop)
+├── collections/<slug>/schema.json   # Collections created on first enable
+├── forms/*.json, pages/**/*.md      # Created on enable, removed on disable
+├── roles/*.json      # Plugin roles, created once
+└── data/             # Runtime state - never served, exported or shipped
+```
+
+Only `admin/**` and `public/**` are served; `plugin.js`, `config.js` and `data/` are never reachable over HTTP.
+
+---
+
+## `plugin.json` - Manifest
+
+```json
+{
+  "name": "my-plugin",
+  "displayName": "My Plugin",
+  "version": "1.0.0",
+  "description": "What this plugin does.",
+  "author": "Your Name",
+  "date": "2026-01-01",
+  "icon": "package",
+  "admin": {
+    "sidebar": [
+      {
+        "id": "my-plugin",
+        "text": "My Plugin",
+        "icon": "package",
+        "url": "#/plugins/my-plugin",
+        "section": "#/plugins/my-plugin"
+      }
+    ],
+    "routes": [
+      {
+        "path": "/plugins/my-plugin",
+        "view": "plugin-my-plugin",
+        "title": "My Plugin - Domma CMS"
+      }
+    ],
+    "views": {
+      "plugin-my-plugin": {
+        "entry": "my-plugin/admin/views/index.js",
+        "exportName": "myPluginView"
+      }
+    }
+  },
+  "inject": {
+    "head": "public/inject-head.html",
+    "bodyEnd": "public/inject-body.html"
+  },
+  "scaffold": {
+    "reset": [
+      { "path": "data.json", "content": "{}" }
+    ]
+  }
+}
+```
+
+### Mandatory fields
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | string | Unique machine name - must match the directory name |
+| `displayName` | string | Human-readable name shown in the admin Marketplace screen |
+| `version` | string | Semver version string |
+| `description` | string | Brief description of what the plugin does |
+| `author` | string | Author name displayed in the admin Marketplace screen |
+| `date` | string | Release date (ISO 8601, e.g. `"2026-01-01"`) |
+| `icon` | string | Domma icon name for the plugin's card on the Marketplace screen |
+
+### Optional fields
+
+| Field | Description |
+|---|---|
+| `admin.sidebar` | Array of sidebar nav items to add when the plugin is enabled. Each may name its default `folder` and a `group` inside it (see [Admin Sidebar Items](#6-admin-sidebar-items)) |
+| `admin.routes` | Array of admin SPA route definitions |
+| `admin.views` | Map of view name → `{ entry, exportName }` for admin SPA views |
+| `inject.head` | Path (relative to the plugin directory) to an HTML snippet injected into `<head>` of every public page |
+| `inject.headLate` | Path to an HTML snippet injected at the **end** of `<head>`, after the site stylesheets and other plugins' `inject.head` snippets (but before generated theme overrides and `content/custom.css`) - use it for CSS that must override the site's own styles |
+| `inject.bodyEnd` | Path (relative to the plugin directory) to an HTML snippet injected before `</body>` of every public page |
+| `scaffold.reset` | Array of `{ path, content }` objects - files to create/reset when `npm run reset` is run |
+| `permissions` | Array of permission resources the plugin guards its routes with - see [Roles & Permissions](#roles--permissions) |
+| `supersedes` | Array of plugin names this one replaces outright (a Pro edition of a free plugin, or a built-in Tool it takes over) - the replaced one registers nothing while this one runs |
+| `requires` | Array of names this plugin cannot work without - a built-in Tool (`contacts`, `notes`, `todo`, `analytics`) or another plugin. It is not loaded while one is off; switching one off switches this off too, and switching this on brings them on (0.88.0) |
+| `admin.css` | Array of admin stylesheets loaded with the plugin's views (may include `../_lib/admin/ui/help.css`) |
+| `settingsSchema` | The Marketplace **Configure** form - see [Settings in the Marketplace](#settings-in-the-marketplace-configure) |
+| `tier` | `free` or `paid` - used by the marketplace catalogue |
+| `closedSource` | `true` for a licensed plugin: an entitlement is required, and the source editor and export are refused |
+| `licence` | Overrides the licence line shown on the plugin's admin banner |
+| `contentPaths` | Folders inside the plugin holding user-authored work; they are tracked in the site's git and preserved by `npx domma-cms update` |
+| `npmDependencies`, `minCmsVersion` | Carried into the marketplace catalogue. `minCmsVersion` (e.g. `"0.92.2"`) is enforced: install and update refuse a plugin that needs a newer CMS (0.92.2). `npmDependencies` is informational |
+| `uses` | `{name: "What is lost without it"}` - Tools or plugins this one works without but uses when they are on. Switching one off leaves this on and shows the admin the text first, so write it as a short feature phrase ("Invite a contact group"). Check at request time: `isToolEnabled(name)` from `server/services/tools.js`, or `GET /api/tools/enabled` in an admin view - and treat an engine without either (before 0.88.0) as "on" (0.88.0) |
+| `docs.permission` | Who may read the plugin's user guides (`docs/*.md`, see [User guides](#user-guides-in-the-documentation-folder)). Defaults to the permission on the first `admin.sidebar` entry that names one; with neither, anyone signed in to the admin (0.93.1) |
+
+---
+
+## `plugin.js` - Server Entry Point
+
+The default export must be an **async Fastify plugin function**. It receives the Fastify instance scoped to the plugin's route prefix (`/api/plugins/<name>/`) and an `options` object.
+
+```js
+export default async function myPlugin(fastify, options) {
+  const { authenticate, requireAdmin } = options.auth;
+
+  // Public endpoint - no auth
+  fastify.get('/ping', async () => {
+    return { ok: true };
+  });
+
+  // Admin-only endpoint
+  fastify.get('/data', { preHandler: [authenticate, requireAdmin] }, async () => {
+    return { data: 'admin only' };
+  });
+}
+```
+
+### `options.auth`
+
+The `options` object exposes the following auth middleware helpers:
+
+| Helper | Description |
+|---|---|
+| `authenticate` | Verifies the JWT Bearer token; rejects with `401` if missing or invalid |
+| `requireAdmin` | Requires the authenticated user to have admin role level (level 0 or 1) |
+| `requirePermission(resource, action?)` | Requires a role holding `resource` (or `resource.action`) - use this with your own resources, see below |
+| `requireRole(roles)` | Requires one of the named roles as the PRIMARY role - prefer `requirePermission`, which the admin can re-assign |
+| `requireVisibility(visibility)` | Gates a route with the page `visibility` syntax, including `=role` |
+
+All routes registered inside `plugin.js` are automatically prefixed with `/api/plugins/<name>/`.
+
+---
+
+## Roles & Permissions
+
+A plugin can bring its own permissions and its own roles - a job board's `candidate` and `employer`, say - and the
+admin then controls them like any other: who holds which role, what each role may do, and which menu items and pages
+each role sees.
+
+**Permissions** are resources in the permission registry. Declare them in `plugin.json`:
+
+```json
+{
+  "permissions": [
+    {"key": "vacancies",    "label": "Vacancies",    "actions": ["read", "create", "update", "delete"], "grant": ["admin"]},
+    {"key": "applications", "label": "Applications", "actions": ["read", "update"]}
+  ]
+}
+```
+
+- `actions` may be bare keys or `{key, label, description}` objects; omitted = read/create/update/delete.
+- `group` (default `Plugins`) and `icon` place it in the role editor.
+- `grant` gives those existing roles the permission **once**. The grant is recorded on the role, so if the admin later
+  removes it, it stays removed. The super-admin (level 0) holds every plugin permission without a grant.
+
+Guard your routes with them:
+
+```js
+const {authenticate, requirePermission} = options.auth;
+fastify.post('/vacancies', {preHandler: [authenticate, requirePermission('vacancies', 'create')]}, handler);
+```
+
+**Roles** are JSON files in `plugins/<name>/roles/`:
+
+```json
+{
+  "name": "candidate",
+  "label": "Candidate",
+  "level": 3,
+  "permissions": ["applications.read", "vacancies.read"],
+  "badgeClass": "badge-info",
+  "resources": [{"key": "applications", "label": "Applications", "actions": ["read", "update"]}]
+}
+```
+
+- A role is created the first time the plugin is enabled and is then the admin's: a role already present is never
+  overwritten, so edits made at **System > Roles** survive updates and restarts.
+- `level` must be 1 or more; a role file asking for level 0 is ignored. Roles on the same level are peers.
+- `resources` in a role file is the older place to declare permissions and still works.
+- `admin` confines the role to your plugin's screens: `{"home": "/my-plugin", "allow": ["/my-plugin"]}`.
+  `allow` lists admin route prefixes (`/my-plugin` also admits `/my-plugin/items`); `home` is where the user lands
+  and where any other route sends them, defaulting to the first allowed route. My Profile is always open. A user is
+  confined only if EVERY role they hold is, so giving someone `admin` as an additional role lifts it. The admin can
+  change this per role under **Roles > Admin area**. It keeps confined users on screens that work for them; the API
+  permission checks are still what protects data.
+- Disabling the plugin unregisters its permissions but **keeps its roles**, so users holding them are not demoted.
+  The admin can delete a role that is no longer wanted.
+
+Permissions are registered on every boot for every enabled plugin (they live in memory); roles are created once.
+
+**From code: `hooks.registerRole()` / `hooks.unregisterRole()`.** For roles a plugin decides on at runtime (from
+its settings, say), use the hooks instead of a file. Both are bound to your plugin, so they can only ever touch roles
+your plugin created. They are on `options.hooks` in `plugin.js`, and on the `hooks` argument of `onEnable` /
+`onDisable`.
+
+```js
+export default async function plugin(fastify, options) {
+  const {registerRole} = options.hooks;
+  await registerRole({
+    name: 'candidate', label: 'Candidate', level: 3,
+    permissions: ['applications.read'],
+    resources: [{key: 'applications', label: 'Applications', actions: ['read', 'update'], grant: ['admin']}]
+  });
+}
+
+export async function onDisable({hooks, uninstall}) {
+  if (uninstall) await hooks.unregisterRole('candidate');
+}
+```
+
+| Hook | Returns | Behaviour |
+|---|---|---|
+| `registerRole(def)` | `{name, created}` | Same fields as a role file (`name`, `level` ≥ 1, `label?`, `permissions?`, `badgeClass?`, `resources?`, `admin?`). Creates the role once; calling it again for a role your plugin already owns is a no-op, so it is safe on every boot and admin edits are kept. **Throws** for an invalid definition, or a name the site or another plugin already holds. |
+| `unregisterRole(name)` | `{name, removed, usersReassigned}` | Removes a role your plugin owns. Users holding it as their primary role are moved to `user`; it is dropped from everyone's additional roles. A name that does not exist answers `removed: false`. **Throws** for a role your plugin does not own. |
+
+**Removal vs. disable.** Disabling a plugin keeps its roles, so a pause demotes nobody. Uninstalling it (Marketplace
+> Uninstall) calls `onDisable` with `uninstall: true` and then removes every role the plugin still owns, the same way
+`unregisterRole` does, so a plugin that forgets to clean up leaves nothing behind.
+
+**Showing things to one role.** Menu items and pages take `visibility: "=candidate"` - candidates only, not employers
+and not admins (the super-admin excepted). Plain `visibility: candidate` means "candidate and anyone more senior,
+including roles on the same level". Admin sidebar items (`admin.sidebar` or `registerSidebarItem`) accept the same
+`visibility` field as well as `permission`, and a user who can see nothing else still gets a sidebar - the menu comes
+from `GET /api/sidebar/menu`, which needs only a signed-in user.
+
+---
+
+## `config.js` - Default Configuration
+
+The default export must be a plain object containing the plugin's default settings. This object is merged with any user-defined overrides stored in `config/plugins.json` at runtime - user values take precedence.
+
+```js
+export default {
+  excludeAdmin: true,
+  trackingInterval: 30,
+  storageBackend: 'file'
+};
+```
+
+Access merged settings in `plugin.js` via `options.settings` if you need them at registration time, or call `getPluginSettings(name)` from `server/services/plugins.js` inside route handlers.
+
+### Settings in the Marketplace (Configure)
+
+Every plugin with a `config.js` can be configured from **System › Marketplace** - right-click it (or click
+it) → settings. With no schema, the form is built from the effective settings, typed from their values
+(boolean → switch, number → number box, object → JSON). To control labels, order, choices and help, declare
+`settingsSchema` in `plugin.json`:
+
+```json
+"settingsSchema": [
+  {"key": "maxBackups", "label": "Backups to keep", "type": "number", "min": 1, "max": 500,
+   "help": "The oldest beyond this are removed automatically."},
+  {"key": "mode", "label": "Mode", "type": "select", "options": ["fast", "safe"]},
+  {"key": "enabled", "label": "Enabled", "type": "boolean"},
+  {"key": "dvlaApiKey", "label": "DVLA API key", "type": "text", "secret": true}
+]
+```
+
+Types: `text`, `number`, `select`, `boolean`. Saving writes only what differs from `config.js`.
+
+**Secrets.** A value whose key looks secret (`password`, `secret`, `token`, `apiKey`, `private`,
+`credential`, `…Uri`, `dsn`), or a field marked `"secret": true`, is sent to the browser masked; saving an
+untouched secret keeps the stored value. Read secrets on the server with `getPluginSettings()` at request
+time (not once at registration), so a new value works without a restart.
+
+---
+
+## Lifecycle Hooks
+
+Plugins receive a `hooks` object via `options.hooks`. Hooks are bound to the plugin's name where it matters (sources,
+roles and notifications are stamped with it). The sections below cover the main ones in detail; the full set is:
+
+| Hook | Purpose |
+|---|---|
+| `on(event, fn)` | Subscribe to the event bus - see [Event Bus](#1-event-bus) |
+| `registerShortcode(name, handler, {priority})` | Add a `[name]` shortcode - see [Custom Shortcodes](#2-custom-shortcodes) |
+| `registerSanitizeRules({tags, attributes})` | Let custom tags/attributes through the HTML sanitiser |
+| `registerTransform(hookName, fn, {priority})` | Modify values at a named hook point - see [Transform Pipeline](#4-transform-pipeline) |
+| `registerMenuLocation(slot, {label, description, maxDepth})` | Add a menu slot - see [Menu Locations](#5-menu-locations) |
+| `registerSidebarItem({folder?, parent?, item})` | Add an admin sidebar Tool at runtime - see [Admin Sidebar Items](#6-admin-sidebar-items) |
+| `registerThemes(provider)` | Offer custom themes - see [Custom Themes](#7-custom-themes) (0.73.0) |
+| `registerRole(def)` / `unregisterRole(name)` | Create or remove roles from code - only the plugin's own (0.71.0) |
+| `registerCalendarSource({id, label, icon, tone, list})` | Dated items shown by the Calendar plugin, per viewer and date range (0.79.0) |
+| `getCalendarSources()` | Read the registered calendar sources (used by the Calendar plugin) |
+| `registerRelatedItems(kind, provider)` | Show items beside a core contact or note, with menu actions (0.79.0). Kind `message` (0.103.0): actions on an email's menu in the mail reader, `{email}`/`{name}`/`{subject}` in the url; any action can carry `permission: {resource, action}` |
+| `enableInstantCalls()` | A paid Tool with calls switches on the CMS's instant calls ("Call Sam now…" on contacts and emails, `#/calls/new`, `/api/calls`, `/_call/<id>`). Bound to the plugin's name; refused unless the manifest is `tier: "paid"` AND `closedSource: true` (so it loads only under a licence). Disabling the plugin takes its hold off at once. Returns true when on. Call it with `?.()` - older cores lack it |
+| `registerContactAccess(fn)` | A plugin that shares contacts says which contacts that are not the viewer's own they may read: `fn(entries, {id, roles})` resolves to the readable entry ids. Core code taking a contact id (instant calls) uses it through `readableContactIds()` |
+| `registerSitemapSource({id, label, list})` / `sitemapChanged()` | Add public URLs to `/sitemap.xml`; call `sitemapChanged()` when they change (otherwise they show within ten minutes) (0.89.0) |
+| `notify({...})` / `resolveNotification(key)` | Raise or clear an admin notification (source ids are `<plugin>:<id>`) (0.80.0) |
+| `registerNotificationSource({id, label, severity, defaultOn, every, atBoot, check, audience})` | A switchable notification source, optionally scheduled (`boot`, `15m`, `hourly`, `daily`) (0.80.0) |
+| `registerLoginCheck({id, phase, check, verify?})` | A sign-in check: `phase: 'before'` (e.g. lockout, before the password is checked) or `'after'` (e.g. two-factor, can ask one more question) (0.83.0) |
+| `registerPasswordCheck({id, check})` | A password rule applied wherever a password is set (0.83.0) |
+| `registerComponent({name, source})` | Add a Domma component from a `.dmc` source string, used on pages as `<dm-name>` or `[component]`; it is listed read-only in Components (0.92.2) |
+
+`onEnable` / `onDisable` exports receive `{fastify, services, hooks}` where `hooks` holds only the role and notification
+hooks; `plugin.public.js` receives only the notification hooks. `hideSidebarUrl` and the
+`unregister*` counterparts of the source hooks are exported from `server/services/hooks.js` but are **not** handed to
+plugins in `options.hooks`.
+
+```js
+export default async function myPlugin(fastify, options) {
+  const { on, registerShortcode, registerSanitizeRules, registerTransform } = options.hooks;
+  // ...
+}
+```
+
+---
+
+### 1. Event Bus
+
+Subscribe to fire-and-forget lifecycle events emitted by the CMS. Handlers receive a payload object and must not return
+a value - errors thrown inside handlers are caught and logged.
+
+```js
+options.hooks.on('content:pageCreated', ({ page, urlPath }) => {
+  console.log('New page created:', urlPath);
+});
+```
+
+#### Content events
+
+| Event                   | Payload              | Fired when                                                  |
+|-------------------------|----------------------|-------------------------------------------------------------|
+| `content:pageCreated`   | `{ page, urlPath }`  | A page is created via the admin API                         |
+| `content:pageRenamed`   | `{ from, to }`       | A page's URL path changes                                   |
+| `content:pageUpdated`   | `{ page, urlPath }`  | A page is saved or restored from version history            |
+| `content:pageDeleted`   | `{ urlPath }`        | A page is deleted                                           |
+| `content:mediaUploaded` | `{ filename }`       | A file is uploaded to the media library                     |
+| `content:mediaDeleted`  | `{ filename }`       | A file is deleted from the media library                    |
+| `content:pageViewed`    | `{ urlPath, title }` | A published public page is successfully rendered and served |
+
+#### Collection events
+
+| Event                     | Payload                           | Fired when                    |
+|---------------------------|-----------------------------------|-------------------------------|
+| `collection:entryCreated` | `{ slug, entryId, data, userId }` | A collection entry is created |
+| `collection:entryUpdated` | `{ slug, entryId, data, userId }` | A collection entry is updated |
+| `collection:entryDeleted` | `{ slug, entryId, userId }`       | A collection entry is deleted |
+
+#### Form events
+
+| Event            | Payload                              | Fired when                                                                                                       |
+|------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| `form:submitted` | `{ slug, entryId, data, formTitle }` | A public form submission passes validation and is stored. `entryId` is `null` if collection storage is disabled. |
+
+#### Auth events
+
+| Event                  | Payload                                         | Fired when                                                                                   |
+|------------------------|-------------------------------------------------|----------------------------------------------------------------------------------------------|
+| `user:loggedIn`        | `{ userId, email, role }`                       | A user successfully authenticates via the login endpoint                                     |
+| `auth:loginSucceeded`  | `{ userId, email, role, ip, ua, sid }`          | The same, with where from and the new session's id                                           |
+| `auth:loginFailed`     | `{ email, ip, ua, reason, userId?, by? }`       | A sign-in is refused - `reason`: `unknown`, `inactive`, `password` or `denied` (a check)     |
+| `auth:loggedOut`       | `{ userId, sid, ip, by }`                       | A session is signed out                                                                      |
+| `auth:rateLimited`     | `{ ip, ua, route }`                             | The sign-in rate limit refuses an address                                                    |
+| `auth:passwordChanged` | `{ userId, by, ip, ua? }`                       | A password changes - `by` is `'reset'` (a reset link) or the id of whoever changed it        |
+| `auth:resetRequested`  | `{ email, userId, ip, ua, sent, reason }`       | Someone asks "Forgot your password?" - after the reply; `reason`: `sent`, `unknown`, `inactive`, `throttled`, `no-smtp`, `no-origin`, `failed` |
+| `auth:resetIssued`     | `{ userId, by, via }`                           | An administrator makes a reset link from Users - `via`: `email` or `link`                    |
+
+Every `auth:passwordChanged` also emails the account holder ("your password was changed"), when a mail server is
+set up.
+
+#### Other events
+
+| Event | Fired when |
+|---|---|
+| `user:deleted` | A user account is deleted |
+| `contact:deleted` | A contact is deleted from the built-in Contacts Tool |
+| `note:deleted` | A note is deleted from the built-in Notes Tool |
+| `audit` | Every successful POST, PUT, PATCH or DELETE under `/api/` by a signed-in user - `{actor, action, route, target, fields, status, ip}` (field names only, never values). Core stores nothing; Security Pro keeps the trail |
+
+---
+
+### 2. Custom Shortcodes
+
+Register a handler for a custom `[shortcode]` tag processed in page Markdown. Lower priority values run first (default
+`10`).
+
+```js
+options.hooks.registerShortcode('my-tag', (attrStr, body, context) => {
+  // attrStr - raw attribute string, e.g. 'title="Hello" color="blue"'
+  // body     - inner content string, or null for self-closing [my-tag /]
+  // context  - { parseShortcodeAttrs, marked, processCardBlocks, processGridBlocks }
+  const { title } = context.parseShortcodeAttrs(attrStr);
+  return `<div class="my-tag"><h3>${title}</h3>${body || ''}</div>`;
+}, { priority: 10 });
+```
+
+Shortcode handlers run synchronously during Markdown processing. Self-closing shortcodes (`[name attrs /]`) receive
+`null` as `body`.
+
+---
+
+### 3. Sanitize Rule Extensions
+
+Extend the HTML sanitizer whitelist so that custom tags and attributes output by your shortcode are not stripped.
+
+```js
+options.hooks.registerSanitizeRules({
+  tags:       ['my-tag', 'my-widget'],
+  attributes: { 'my-tag': ['data-config', 'data-theme'] }
+});
+```
+
+Without registering custom tags here, any non-standard HTML your shortcode emits will be sanitized out before it reaches
+the browser.
+
+---
+
+### 4. Transform Pipeline
+
+Register a function at a named hook point to intercept and modify values as they flow through the Markdown and render
+pipelines. Lower priority values run first.
+
+```js
+options.hooks.registerTransform('markdown:afterParse', (html, context) => {
+  // Wrap every <table> in a scroll container
+  return html.replace(/<table/g, '<div class="table-scroll"><table')
+             .replace(/<\/table>/g, '</table></div>');
+}, { priority: 20 });
+```
+
+#### Available hook points
+
+| Hook name              | Value type | Context    | Description                                                                       |
+|------------------------|------------|------------|-----------------------------------------------------------------------------------|
+| `markdown:beforeParse` | `string`   | `{}`       | Raw Markdown string, before shortcode processing and `marked.parse()`             |
+| `markdown:afterParse`  | `string`   | `{}`       | Sanitised HTML string, after parsing and `sanitize-html`                          |
+| `render:beforeRender`  | `object`   | `{ page }` | Template variable map (title, body, headInject, etc.) before string interpolation |
+| `render:afterRender`   | `string`   | `{ page }` | Final assembled HTML page string, just before it is sent to the browser           |
+| `seo:meta`             | object     | see `server/services/seo/` | The page's SEO meta before it is written into `<head>` (0.89.0)          |
+| `sitemap:entries`      | array      | see `server/services/seo/` | The `/sitemap.xml` entries before they are serialised (0.89.0)           |
+| `robots:lines`         | array      | see `server/services/seo/` | The `/robots.txt` lines before they are joined (0.89.0)                  |
+
+Transforms run **synchronously** in the render path - keep them fast.
+
+---
+
+### 5. Menu Locations
+
+Register a named slot that admins can map a menu to in the **Menus → Locations** editor. The slot becomes available to the public renderer and to the `[menu location="…" /]` shortcode. Call this during plugin registration (synchronously inside the plugin function, or from inside `setupPlugin()`).
+
+```js
+options.hooks.registerMenuLocation('sidebar', {
+    label:       'Sidebar',
+    description: 'Renders in the left sidebar of pages with sidebar layout',
+    maxDepth:    1
+});
+```
+
+| Field         | Required | Description                                                              |
+|---------------|----------|--------------------------------------------------------------------------|
+| `label`       | yes      | Human-readable slot name shown in the admin Locations table              |
+| `description` | no       | What the slot is for and where it renders                                |
+| `maxDepth`    | no       | Advisory depth cap - the admin Locations UI shows a depth-overflow warning when the mapped menu exceeds it, but rendering still attempts to flatten beyond the cap |
+
+Slot names must match `/^[a-z0-9][a-z0-9-]*$/` (the same shape as menu slugs). Re-registering an existing slot logs a warning and the second registration wins (last-write semantics - consistent with other plugin hooks). Core registers `navbar`, `footer-primary`, `footer-legal`, and `admin-sidebar` at startup.
+
+---
+
+### 6. Admin Sidebar Items
+
+Every admin screen is a **Tool**, and each Tool has a **default folder** in the admin sidebar. An
+enabled plugin's entries go to **Tools** unless they name another folder; an admin can then move any
+Tool anywhere in the sidebar (Content > Menus > Admin sidebar), and that choice wins.
+
+Most plugins declare their entries in `plugin.json` and never call anything:
+
+```json
+"admin": {
+  "sidebar": [
+    {"text": "Invoices", "url": "#/plugins/invoice", "icon": "file-text", "folder": "data"}
+  ]
+}
+```
+
+From code, register the same thing with the hook (inside `setupPlugin()`, or synchronously in the
+plugin function):
+
+```js
+options.hooks.registerSidebarItem({
+    folder: 'system',
+    item: {
+        text:       'My Plugin',
+        url:        '#/plugins/my-plugin',
+        icon:       'puzzle',
+        permission: 'my-plugin'
+    }
+});
+```
+
+| Field    | Required | Description |
+|----------|----------|-------------|
+| `folder` | no       | The key of the folder the Tool lives in by default: `overview`, `projects`, `content`, `data`, `tools`, `system` or `documentation`. Defaults to `tools`. May also be given as `item.folder`. A folder that cannot be found falls back to Tools. |
+| `group`  | no       | A sub-folder of `folder` to sit in, by name (`"Core"` puts the Tool in Tools > Core). The group is keyed `<folder>.<slug>` (`tools.core`) and made at render time if the menu has none; Tools that name the same group share it. May also be given as `item.group`. Leave it out to sit directly in the folder. |
+| `parent` | no       | Older form: the **text** of a node to nest under. Still honoured; prefer `folder`, which survives an admin renaming the folder. |
+| `item`   | yes      | `{text, url, icon?, permission?, visibility?, countUrl?, hotkey?, items?}` - same shape as menu items (see `docs/configuration.md`). |
+
+**Hotkeys.** Give the entry `"hotkey": "e"` and **G then E** opens your Tool from anywhere in the admin;
+the sidebar shows it on hover and beside **Open** in the Tool's right-click menu, and **?** lists it.
+One letter (`a`-`z`, not `g`, which starts the sequence) or a comma; digits are the Frequent folder's.
+Every Tool also appears in the palette (Ctrl+K or Ctrl+D) by its name, hotkey or not. The built-in
+Tools claim their letters first (`CORE_HOTKEYS` in `admin/js/lib/hotkeys.js`: D Dashboards, P Pages,
+M Media, L Collections, F Forms, V Views, U Users, A Analytics, N Notes, T Todo, C Contacts, `,` Site
+Settings); after that the first Tool in the sidebar to ask for a letter has it, and a later one goes
+without - the browser console names it. A Pro Tool that supersedes another takes over its entry, so it
+asks for the same letter (Blog Pro, like Blog, is B). Ours: E Email, R Mail Reader, B Blog, K Booking,
+Y Calendar, C Contacts Pro, O Docs, I Invoices, H Shop, Q Surveys, W Waypoint, J Job Board, S Support.
+
+
+**Placement.** Registered items are **not persisted** into `config/menus/admin-sidebar.json`; plugins
+re-register on every boot and the renderer places them at render time
+(`placeTools()` in `admin/js/lib/sidebar-grouping.js`):
+
+1. If the admin-sidebar menu has an item with the Tool's `url`, the Tool renders **there** - that is
+   an admin's move. Its live properties (`countUrl`, permission, sub-items) still come from your
+   registration; the admin's label and icon win.
+2. Otherwise it goes into its default `folder`, matched by the folder's `key`, so a folder the admin
+   renamed still receives its Tools - and, if it names a `group`, into that sub-folder: found by its
+   key anywhere (an admin may have moved the whole group), else by name inside the folder, else made.
+   A made group is saved only once the admin saves something in it.
+3. A placeholder `{url, ref: true}` for a Tool that is not enabled is dropped, so disabling a plugin
+   leaves no dead link and re-enabling it puts it back where the admin had it.
+
+A Tool is identified by its `url`, never its text - give each entry a unique url.
+
+**Moving and hiding a Tool.** In Content > Menus > Admin sidebar every enabled Tool is listed where it
+appears, badged with the plugin it comes from. Move, hide or relabel it like any item and Save; only
+the Tools you placed are saved, as `{url, ref: true}` placeholders, so the rest keep following their
+default folder. A Tool's address and permission cannot be changed there,
+and its bin puts it back in its default place. (The older same-`text`, url-less hidden item is still
+honoured.)
+
+
+### 7. Custom Themes
+
+Offer themes that join the built-in ones everywhere a theme is chosen (site, admin, day/night,
+element overrides). The provider is a function, called on every read - including every page render -
+so keep it synchronous and in memory:
+
+```js
+options.hooks.registerThemes(() => [
+    {id: 'brand', label: 'Brand', baseTheme: 'ocean-dark', tokens: {'--dm-primary': '#1144ff'}}
+]);
+```
+
+| Field       | Description |
+|-------------|-------------|
+| `id`        | Slug (`a-z0-9-`, 60 max). Must not be a built-in theme id; the first provider to claim an id keeps it. |
+| `label`     | Shown in the pickers. |
+| `baseTheme` | A built-in theme id; an unknown one falls back to `charcoal-dark`. |
+| `tokens`    | `--dm-*` tokens and values; anything else, or a value that could break out of its declaration, is dropped. |
+
+The CMS applies a custom theme as `dm-theme-<base> dm-custom-<id>` - see `docs/theming.md`. The hook is
+bound to your plugin: registering again replaces your themes, never another plugin's. It exists from
+domma-cms 0.73; check `typeof options.hooks.registerThemes === 'function'` to degrade on older ones.
+
+---
+
+## Admin Views Integration
+
+To add a page to the admin SPA, declare `admin.routes` and `admin.views` in `plugin.json`.
+
+### View file
+
+Admin views follow the same pattern as core admin views:
+
+```js
+// plugins/my-plugin/admin/views/index.js
+export const myPluginView = {
+  templateUrl: '/plugins/my-plugin/admin/templates/index.html',
+  async onMount($container) {
+    // H.get adds the auth header and refreshes the token for you -
+    // do not hand-build a Bearer header with fetch().
+    const res = await H.get('/api/plugins/my-plugin/data');
+    const data = res.data ?? res;
+    $container.find('#my-output').text(data);
+  }
+};
+```
+
+The view object must have:
+
+- `templateUrl` - URL of the HTML template (plugin admin files are served at `/plugins/<name>/admin/...`)
+- `onMount($container)` - called after the template is rendered; receives the Domma-wrapped container element
+
+### Template file
+
+```html
+<!-- plugins/my-plugin/admin/templates/index.html -->
+<div class="plugin-my-plugin">
+  <h2>My Plugin</h2>
+  <p id="my-output">Loading...</p>
+</div>
+```
+
+Use Domma class names (`card`, `btn`, `form-input`, `flex`, `justify-between` and so on), not Bootstrap ones such as
+`container` or `py-4`. The admin already wraps every plugin view in a banner (`.dm-plugin-shell`) showing the plugin's
+name, version and licence - do not draw your own. `plugins/CLAUDE.md` and the template plugin's `CLAUDE.md` list the
+other conventions.
+
+
+### User guides in the Documentation folder
+
+Ship user documentation for site owners as Markdown in `docs/` inside the plugin (0.93.1):
+
+```
+plugins/my-plugin/docs/guide.md       first page (tab "Guide")
+plugins/my-plugin/docs/settings.md    further pages, as tabs
+```
+
+While the plugin is loaded (enabled, licensed, not superseded) each file is a page under
+**Documentation > Plugins > <Display name>** (`#/docs/plugins/<name>[/<page>]`), and `#/docs/plugins` lists every
+guide as a card. A guide is shown only to users who can use the plugin - see `docs.permission` in the manifest
+fields. Optional frontmatter: `title` (the tab label; default from the file name, `guide.md` reads "Guide") and
+`order` (lowest first; `guide.md` defaults to 0, others to 100).
+
+- Plain GitHub-flavoured Markdown, sanitised on the server. Shortcodes are NOT run, so `[collection ...]`
+  examples in a fenced block show literally - which is what a guide wants.
+- Do not open with an H1: the page header already shows the plugin name and page title. Use `##` sections.
+- Admin hash links (`[Invoices](#/plugins/invoice)`) stay in the admin; `https://` links open a new tab.
+- Guides are read at boot with the plugin, like its sidebar entry - a new or changed file shows after a restart.
+- Suggested sections: What it does, Getting started, one `###` per screen, Settings, Shortcodes, Permissions and
+  roles, Tips, Limitations. Write for site owners, not developers - developer notes belong in `CLAUDE.md`.
+
+---
+
+## Dashboard widgets
+
+With **Dashboard Pro**, admins build their own Dashboard from widgets the Tools offer. A widget ships
+no code: it names a `kind` the admin knows how to draw and a `dataUrl` that answers in that kind's
+shape, so every widget looks like part of the same admin.
+
+**You may already have one.** Every sidebar entry with a `countUrl` is offered as a `count` widget
+automatically - the badge's own answer (`{count, label, tone, details}`) is drawn as a big number with
+its `details` rows and items underneath. Email, Booking, Support and the rest arrive this way.
+
+For anything more, list widgets in `plugin.json`:
+
+```json
+"admin": {
+  "widgets": [
+    {
+      "id": "blog:latest",
+      "title": "Latest posts",
+      "description": "The five newest posts and their status.",
+      "icon": "edit",
+      "kind": "list",
+      "size": "m",
+      "dataUrl": "/api/plugins/blog/widget/latest",
+      "href": "#/plugins/blog",
+      "permission": "blog",
+      "refresh": 120
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Unique; lowercase, digits, `: . _ / -`. Prefix it with your plugin's name. |
+| `kind` | `count`, `stat`, `list` or `chart` - see below |
+| `dataUrl` | An `/api/...` route of yours answering in the kind's shape, as the signed-in user |
+| `size` | Its usual width on the four-column board: `s`, `m`, `l` or `xl` (full width) |
+| `href` | The admin screen its title opens (`#/...`) |
+| `permission` | Offered only to users holding it (any action on the resource) |
+| `admin` | `true`: administrators only |
+| `refresh` | Seconds between refreshes (15-3600, default 60). A `dm:sidebar-count` for its `href` refreshes it at once too. |
+
+| Kind | `dataUrl` answers | Drawn as |
+|---|---|---|
+| `count` | `{count, label, tone, details: {rows, items}}` - a sidebar badge | big number, its rows and items |
+| `stat` | `{value, label, sub, tone}` | big value with a line under it |
+| `list` | `{items: [{text, meta, value, href, tone}], empty}` | rows; one with `href` opens it |
+| `chart` | `{labels: [], values: [], label}` | a line chart |
+
+Everything is drawn with `textContent`, so a widget's data can never inject markup. `tone` is `ok`,
+`warn`, `danger`, `info` or `attention`. A route should answer quickly - every widget on a board asks
+on its own, and again on its refresh. From code, `hooks.registerWidget(def)` takes the same object.
+Widgets go away when your plugin is disabled.
+
+Without Dashboard Pro the widgets are simply not offered: the fixed Dashboard is unchanged.
+
+## Head/Body Injection
+
+Injection snippets are plain HTML files included verbatim into every rendered public page. They are loaded once at startup and cached. Paths are confined to the plugin's folder. Three slots exist: `inject.head` (early in `<head>`), `inject.headLate` (end of `<head>`, after the site stylesheets - for CSS that must win) and `inject.bodyEnd` (before `</body>`).
+
+**`public/inject-head.html`** - injected inside `<head>`:
+
+```html
+<script>
+  window.__MY_PLUGIN_CONFIG__ = { version: '1.0.0' };
+</script>
+```
+
+**`public/inject-body.html`** - injected just before `</body>`:
+
+```html
+<script src="/plugins/my-plugin/public/tracker.js" defer></script>
+```
+
+Static files in the plugin's `public/` directory are served at `/plugins/<name>/public/`.
+
+---
+
+## Minimal Plugin Skeleton
+
+Below is the smallest possible working plugin:
+
+**`plugins/hello-world/plugin.json`**
+
+```json
+{
+  "name": "hello-world",
+  "displayName": "Hello World",
+  "version": "1.0.0",
+  "description": "A minimal example plugin.",
+  "author": "Your Name",
+  "date": "2026-01-01",
+  "icon": "smile"
+}
+```
+
+**`plugins/hello-world/plugin.js`**
+
+```js
+export default async function helloWorldPlugin(fastify, options) {
+  fastify.get('/hello', async () => {
+    return { message: 'Hello from my plugin!' };
+  });
+}
+```
+
+**`plugins/hello-world/config.js`**
+
+```js
+export default {};
+```
+
+After enabling the plugin on the admin **Marketplace** screen, the endpoint `GET /api/plugins/hello-world/hello` will return `{ "message": "Hello from my plugin!" }`.
+
+---
+
+## Bundled Plugins Reference
+
+These free plugins ship in the core package's `plugins/` directory and are good references:
+
+| Plugin        | Directory        | Description                                                                                   |
+|---------------|------------------|-----------------------------------------------------------------------------------------------|
+| Blog          | `blog/`          | Public routes, collections, admin views and its own shortcodes - the fullest example here |
+| Mail Reader   | `mail-reader/`   | Read-only IMAP mailbox reader; a permission-guarded admin view over an external service      |
+| Security      | `security/`      | Sign-in lockout and password rules via `registerLoginCheck` / `registerPasswordCheck`, a health check, sign-in log and scanner blocking |
+| Shopping Cart | `shopping-cart/` | Products, storefront and cart with root-level public routes (`plugin.public.js`) and payment providers |
+
+Analytics, effects, the theme switcher, Notes, Todo, Contacts and the demo viewer used to be plugins and are now part
+of the core CMS. Theme Roller and the other paid plugins are installed from the Marketplace.
+
+## Signed plugins and `requireSignedPlugins`
+
+Plugins from the marketplace are distributed as signed `.dcmsplugin` bundles, and the signature is verified at install.
+A bundle whose signature does not verify is always refused. An **unsigned** bundle (for example one exported from
+another running site) is only accepted when the installer explicitly confirms it - and never when the site sets:
+
+```json
+// config/server.json
+{ "requireSignedPlugins": true }
+```
+
+With that set, only signed bundles can be installed.